Campaign 9 — Repository readiness and agent guidance

Objective

Capture cheap, high-leverage technical debt as explicit repository guidance, deterministic checks, or bounded issues without turning the estate review into a blanket modernization program.

The initial scope is the connected core declared by estate/core-system-graph.yaml. The audit follows that graph rather than hard-coding a permanent repository count.

Central rule

Each readiness dimension answers a different question:

Dimension	Question
AGENTS.md	How may an agent safely work in this directory tree?
README / docs	How does a human understand and operate the repository?
Make / command surface	What stable local commands already exist?
GitHub Actions	Which deterministic checks should run automatically?
License	What reuse rights does the owner intentionally grant?
Issues	Which active red states deserve persistent tracking?

One missing dimension does not imply that all the others must be added.

AGENTS.md policy

An agent file is useful when repository work has non-obvious constraints that are likely to be violated by a capable implementation agent.

Good content includes:

• mission and current bounded objective;
• authority and non-authority boundaries;
• files or directories that are canonical, generated, archival, sensitive, or forbidden;
• verified commands and side effects;
• data, migration, deployment, and secret-handling rules;
• stop conditions and required decision packets;
• expected completion evidence and PR summary.

Do not use it as:

• a duplicate README;
• a speculative architecture document;
• an unverified command list;
• a permanent copy of one temporary task;
• generic advice such as “write clean code.”

Root files apply to the repository tree. Nested files are justified only when a subdirectory has materially different rules, such as legacy notebooks, generated documentation, private fixtures, or a frontend/backend split.

Initial core finding

Across the current 25-node connected graph:

• three repositories have substantive domain-specific agent guidance: income-modeling-eph, matias-context-mcp, and site-factory-showcase;
• three repositories have only the framework-generated Next.js warning: office-review, web-grafo, and web-professional-template;
• nineteen have no root AGENTS.md observed.

This does not create nineteen automatic PRs. Priority goes to control planes, mutation-capable runtimes, data products, contract authorities, and repositories with sensitive or generated artifacts.

Documentation audit

The front-door campaign repaired many root READMEs after the original missing-entrances.csv was generated. Therefore the old queue is evidence of the pre-repair state, not a current execution queue.

The next documentation scan should distinguish:

• missing root entrance;
• generic framework entrance;
• truthful front door but missing operator runbook;
• truthful front door but missing architecture or data-contract explanation;
• documentation site whose build is unverified;
• sufficient documentation for the current lifecycle.

Do not open a docs issue merely because a docs/ directory is absent.

Command-surface audit

The Make audit is also intentionally refreshable. Four reference adapters merged after its initial snapshot:

• kb-contracts;
• site-factory-showcase;
• IPC-Argentina;
• canastasINDEC.

A readiness scan should detect that drift. Do not preserve obsolete counts by editing generated reports directly.

Common aliases remain semantic and optional:

check  test  smoke  run  docs  clean

Repository-specific commands remain preferable when they expose meaningful side effects, such as regenerate, run-full, corpus-parse, or triage-payment.

GitHub Actions policy

Actions are high-value when all of the following are true:

1. the command is deterministic;
2. the command is bounded enough for pull requests;
3. it does not require private production data or billable APIs;
4. its failure has a clear interpretation;
5. the repository is active or maintained;
6. the workflow does not silently publish, migrate, or mutate external state.

High-confidence candidates

• projects: run the standard-library metadata validators through make check;
• kb-contracts: offline contract validation, typecheck, and docs build;
• IPC-Argentina and canastasINDEC: offline snapshot verification only;
• simple web repositories after npm ci and build behavior are confirmed;
• Python libraries with fixture-driven tests and no required external datasets.

Blocked or review-required candidates

• live data refreshes;
• repository-health or office mutation commands;
• accounting runs requiring private inputs;
• database migrations;
• deployed smoke tests;
• model training over large local datasets;
• placeholder command surfaces such as the current eph-censo-aligner Makefile.

License policy

A public repository is not automatically an open-source repository.

Use these classifications:

present
missing-advisable
missing-intentional
review-third-party-rights
review-data-rights
review-client-or-institutional-rights
not-applicable-private
unknown

A license is a high-confidence recommendation only when:

• Matías owns or can license the relevant code;
• the intended reuse model is explicit;
• embedded dependencies, copied templates, notebooks, datasets, figures, client content, employer assignments, and collaborator contributions have been reviewed;
• software and non-software artifacts are separated where needed.

Do not choose MIT merely because it is simple. Licensing is a human authority decision; the agent may prepare evidence and options.

Issue policy

Create an issue when all are true:

• the repository remains active or maintained;
• the problem is currently real, not merely possible;
• the consequence is visible or operationally relevant;
• there is a bounded acceptance condition;
• the issue will not duplicate a stronger source-of-truth artifact.

Good issue candidates from the current campaigns include:

• reconciling the intended 31-node graph with the 25-node graph currently merged in projects;
• replacing the false placeholder Make surface in eph-censo-aligner;
• repairing the known-broken acquisition workflow in min-economia-arg-datos;
• resolving the legacy/placeholder Atlas deployment configuration.

Do not create issues for frozen historical repositories, generic dependency staleness, speculative features, or every audit unknown.

Remote scan contract

make readiness-scan may query GitHub metadata through gh api. It records observed facts only:

• repository visibility and archived state;
• root AGENTS.md, README, Makefile, and common license-file presence;
• documentation-directory presence;
• Actions workflow count;
• issues enabled and open-issue count;
• GitHub-detected license metadata when available.

The scan must not:

• modify another repository;
• run repository commands;
• infer documentation quality from file presence;
• select a license;
• create issues;
• treat a workflow file as evidence that CI currently passes.

Rollout order

1. Add the scanner, validator, queue, control-plane AGENTS.md, and a projects CI pilot.
2. Upgrade the three framework-only Next.js agent files with repository-specific boundaries.
3. Add concise agent files to high-risk control, contract, pipeline, and data repositories.
4. Run the remote scan locally and review the generated queue.
5. Create only the high-signal issues that survive duplicate review.
6. Prepare a separate license decision packet; do not batch license text into the audit PR.
7. Stop before broad CI, dependency, or documentation implementation.

Close condition

Campaign 9 is seeded when:

• the remote scan can be reproduced;
• the offline audit validates current graph coverage;
• projects checks run in CI;
• reference agent-guidance patterns exist;
• the issue policy has produced only bounded red-state issues;
• license recommendations remain evidence-backed human decisions.