Campaign 8 — Repository-local Make command surfaces

Purpose

Use the repository-local SYSTEM.yaml declarations and the core-system graph to improve operator fluency without creating a central runtime orchestrator.

The objective is not to install a Makefile in every repository. The objective is to make useful repository commands:

• easy to discover;
• truthful about cost and side effects;
• stable enough for a human or coding agent to use;
• bounded by the repository's own authority;
• explicit when execution still requires local verification.

Architectural boundary

The existing authority split remains unchanged:

• each repository owns its own Makefile and SYSTEM.yaml.canonical_commands;
• projects owns the audit, policy vocabulary, rollout queue, and graph-level consistency checks;
• projects never imports, shells into, clones, or executes another repository;
• native tools such as npm scripts, Python CLIs, pytest, Docusaurus, Next.js, and domain scripts remain implementation authority;
• a Make target may delegate to a native command, but it must not hide material behavior.

A repository can be healthy without Make. A false or placeholder Makefile is worse than no Makefile.

Scope and graph reconciliation

The audit is graph-driven. At branch creation, projects/main contained the merged Campaign 7 graph with:

• 25 repositories;
• 6 connected components;
• 28 seams.

The intended expanded contract is 31 repositories, seven components, and 33 seams. That expansion was not yet visible on projects/main when this audit was created.

The Make-audit validator therefore compares its rows with the checked-out graph instead of hard-coding either count. When the graph gains nodes, validation fails until those repositories receive an explicit Make assessment.

Repository renames do not change stable IDs. The audit already reconciles:

• repo.knowledge-base-app → paper-kb;
• repo.gpt-digests → kb-artifacts;
• repo.context → context-routing;
• repo.office-window → office-review.

Common command vocabulary

These names are available where they express real behavior. They are not mandatory checkboxes.

Target	Contract
make check	Deterministic repository validation. No production mutation, external publication, or broad data refresh.
make test	The actual automated test suite. Do not alias a compile or build command and call it a test.
make smoke	Cheap, bounded and preferably offline or fixture-driven. It must fail meaningfully.
make run	The normal local runtime only when dependencies and side effects are understood.
make docs	Build or validate the repository's documentation surface.
make clean	Remove generated local outputs only. Never delete source data, secrets, approved releases or irreplaceable artifacts.

Domain-specific targets remain first-class. Examples include:

• corpus-parse and corpus-validate;
• triage-payment;
• run-canonical and publish-latest;
• thesis-freeze;
• contract-release-verify;
• repo-health-run.

The common vocabulary should sit above those commands only when the composition is honest and useful.

Classification model

Each graph node receives one policy:

Policy	Meaning
keep-and-document	Mature Makefile already acts as a trustworthy operator control plane.
polish-existing	Real Makefile exists, but a small operator alias, help surface or taxonomy improvement may help.
replace-placeholder	Existing Makefile advertises commands that are not implemented. Inspect locally before replacement.
add-adapter-high-confidence	Native commands are clear enough for a thin, mechanical Make adapter.
add-adapter-after-local-verification	Likely useful, but fixtures, side effects, environments or command authority require local inspection.
defer-until-real-command	No truthful validation or runtime command exists yet; do not add Make for visual consistency.

Audit result for the checked-out graph

• 9 repositories have real root Makefiles.
• 1 has a placeholder Makefile.
• 15 have no root Makefile.
• 11 are high-confidence thin-adapter candidates.
• 3 require local verification before an adapter.
• 8 existing Makefiles merit bounded polishing.
• 1 mature Makefile should be preserved as-is except for domain-driven changes.
• 1 documentation-only repository is deliberately deferred.

The canonical row-level evidence lives in estate/make-command-surface-audit.yaml. Generated projections are:

• generated/make-command-surface-audit.csv;
• generated/make-adapter-queue.csv;
• generated/make-command-surface-summary.md.

Important findings

Mature reference surface

accounting-workflows demonstrates a real operator control plane: explicit smoke/live separation, guarded inputs, timestamped outputs, validation, publication and release checks. It should not be flattened into six generic targets.

Useful compact surfaces

knowledge-inspect, kb-artifacts, and indice-pobreza-UBA already expose bounded checks or smoke commands. Their likely improvement is a small check composition, not a rewrite.

False command surface

eph-censo-aligner contains an auto-generated Makefile whose smoke and run_all targets print “not implemented” and exit. This creates false discoverability. The correct sequence is:

1. inspect actual scripts, notebooks, tests and fixtures locally;
2. define one bounded verification path;
3. replace the stub with real targets;
4. update SYSTEM.yaml.canonical_commands only after execution succeeds.

Native package managers remain authoritative

Docusaurus and Next.js repositories already have npm scripts. A thin adapter may improve estate-wide muscle memory, but npm remains the source of command truth.

For example:

.PHONY: check run docs clean

check:
	npm run typecheck
	npm run build

run:
	npm run start

docs:
	npm run build

clean:
	npm run clear

This is a pattern, not a universal template. A repository without typecheck must not invent it. A Next.js repository using dev rather than start should delegate accordingly.

Data repositories need asymmetric commands

For IPC-Argentina and canastasINDEC, an offline snapshot verifier is suitable for check and smoke. Source-dependent regeneration should retain a descriptive command and should not be hidden under a generic make run.

For microdatos-EPH-INDEC, a network-wide historical download is not a smoke test. A future adapter should use CLI help or a small fixture extraction.

Documentation-only governance

weekly-ops-governance should not receive a Makefile until it has a real internal-link, route-manifest or printable validation command. Documentation structure alone does not justify a fake check target.

Rollout packets

Packet 0 — Reference decisions

• add make check and Make-audit commands to projects, remaining metadata-only;
• add a thin adapter to kb-contracts around contract validation and documentation build;
• add a thin adapter to site-factory-showcase, whose npm vocabulary is already complete;
• inspect and replace the eph-censo-aligner placeholder locally.

This packet establishes three reference patterns: control-plane metadata, Docusaurus/contracts, and Next.js/application.

Packet 1 — High-confidence adapters

After Packet 0 is reviewed and executed locally:

• accounting-docs;
• atlas-pobreza-docs;
• capture-site;
• context-routing;
• office-review;
• web-grafo;
• web-professional-template;
• IPC-Argentina;
• canastasINDEC.

Each repository receives only targets supported by its existing native commands.

Packet 2 — Existing-surface polish

Review command cost and side effects before changing:

• accounting-doc-triage;
• kb-artifacts;
• knowledge-inspect;
• income-modeling-eph;
• indice-pobreza-UBA;
• paper-kb;
• office-auto-lab.

Do not rename domain targets merely to look consistent.

Packet 3 — Local-verification adapters

• accounting-viewer: bounded Flask test-client smoke;
• matias-context-mcp: real stdio MCP acceptance smoke with example mounts;
• microdatos-EPH-INDEC: fixture or CLI-help smoke, never broad live acquisition.

Deferred

• weekly-ops-governance until a real validator exists.

Codex execution contract

Each repository packet should begin with an assessment table:

Repository	Existing commands	Missing useful alias	Safe one-line adapter?

Codex may then implement a bounded change only when:

1. the native command was found in the repository;
2. the target's side effects and prerequisites are stated;
3. make help or equivalent documents the surface;
4. the relevant targets are actually executed locally;
5. SYSTEM.yaml.canonical_commands is updated from verified results;
6. generated and large-data policies are respected;
7. no cross-repository runtime dependency is introduced.

The closeout should report commands attempted, exit codes, generated files, duration, environment assumptions and remaining unknowns.

Control-plane commands

make make-surface-check
make make-surface-generate
make make-surface-all
make check

make check remains confined to projects: estate, lifecycle, freshness, system-graph and Make-audit metadata checks. It does not execute the selected repositories.

Non-goals

• no monorepo orchestration;
• no central dependency installation;
• no blanket replacement of npm, Python or shell commands;
• no invented tests or smoke checks;
• no generic run target for expensive, mutating or source-dependent pipelines;
• no cleanup target that risks source or private data;
• no automatic modification of all selected repositories in this anchor packet.