Require surface-anchor V-B-A for Contract Ledger rows

Context

During the #11731 tenant-repo ingestion chain, four delegated Contract Ledger drafts (#11788, #11789, #11790, #11791) required verifier-side refinement before becoming issue-body source of truth. The repeated pattern was not that the six-column schema was missing; it was that rows naming existing surfaces drifted from current code/docs reality.

Observed corrections:

• #11789 draft used sourceFiles; live KnowledgeBaseIngestionService.ingestSourceFiles() uses files, deleted, manifestSnapshot, baseRevision, and headRevision.
• #11790 draft reused resolveDeploymentEnabled() for a cloud-deployable lane; live Orchestrator.mjs shows that helper is local-only shaped (cloud defaults disabled), so the new lane needs a cloud-deployable default contract.
• #11791 draft named the downstream MCP healthcheck tool instead of the substrate payload anchor; live Memory Core healthcheck surfaces orchestrator state under healthcheck.orchestrator.tasks via HealthService.recordTaskOutcome().
• #11791 draft implied a setTenantConfig MCP tool; live substrate has KnowledgeBaseIngestionService.setTenantConfig() but no such tool surface.
• #11791 draft assumed old backup scope rather than re-checking the #11788 mirror-volume posture.

Duplicate sweep: exact search over resources/content/issues, resources/content/discussions, learn/agentos, and .agents/skills found the general Contract Ledger protocol and V-B-A rules, but no ticket for row-level surface-anchor verification. Live gh issue list --search '"Contract Ledger" "Verify-Before-Assert" "surface"' returned no open duplicates. KB semantic search was attempted but failed with Internal error: Error finding id while KB healthcheck remained healthy.

The Problem

The current Contract Ledger protocol requires a canonical matrix, but it does not explicitly require each row that names an existing API/config/tool/helper/doc surface to first verify that surface's current literal name, shape, and owning substrate.

That leaves a repeatable failure mode: agents draft a semantically plausible row, the row passes schema review, but it encodes a stale field name, helper semantics inversion, downstream-consumer alias, nonexistent tool surface, or outdated scope assumption. The error is then caught during reviewer/operator refinement instead of upstream at ledger authoring time.

The Architectural Reality

Relevant current authorities:

• learn/agentos/contract-ledger.md defines the Contract Ledger schema and lifecycle integration.
• .agents/skills/ticket-create/references/ticket-create-workflow.md requires Contract Ledgers in new tickets when consumed surfaces are introduced or modified.
• .agents/skills/ticket-intake/references/ticket-intake-workflow.md blocks implementation when the ledger is missing or incomplete.
• .agents/skills/pr-review/references/pr-review-guide.md audits PR diffs against the ledger and rejects drift.
• .agents/skills/create-skill/references/skill-authoring-guide.md says skill payload changes should preserve progressive disclosure; do not bloat routers or top-level SKILL.md files.

The missing discipline belongs at the Contract Ledger authoring layer, not as another global AGENTS.md rule. A compact section in learn/agentos/contract-ledger.md plus narrow workflow pointers is enough.

The Fix

Add a "surface-anchor V-B-A" rule for Contract Ledger authoring:

• For every ledger row that cites an existing code/doc/tool/config surface, run a falsifying lookup before naming it.
• Record or imply the anchor in the row's Source of Authority / Evidence cell.
• Prefer substrate names over downstream-consumer aliases.
• If a desired surface does not exist, phrase the row as "implementation may add" or "new surface to be introduced", not as current reality.
• Keep the detailed guidance in learn/agentos/contract-ledger.md; add only compact pointers in ticket-create/ticket-intake/pr-review payloads if needed.

Contract Ledger Matrix

Decision Record Impact

Aligned with the Verify-Before-Assert core value and the existing Contract Ledger protocol. No ADR amendment required; this is workflow/documentation hardening.

Acceptance Criteria

• learn/agentos/contract-ledger.md defines the row-level surface-anchor V-B-A rule.
• The guidance includes concrete failure classes from #11789/#11790/#11791: wrong field name, wrong helper default semantics, downstream-consumer alias, nonexistent tool surface, and stale scope assumption.
• Ticket creation guidance points Contract Ledger authors to the surface-anchor rule without bloating SKILL.md routers.
• Intake/review guidance can flag a ledger row that names an existing surface without empirical anchoring or that contradicts current code/docs.
• No always-loaded AGENTS.md expansion unless implementation proves the payload pointer is insufficient.

Out of Scope

• Creating a new skill.
• Adding runtime code or tests unless a mechanical lint/check is introduced during implementation.
• Rewriting existing Contract Ledgers retroactively beyond #11788-#11791, which are already corrected.

Avoided Traps

Related

• #11731 tenant-repo ingestion epic.
• #11788 / #11881 GitMirror primitive.
• #11789 diff-to-ingest envelope builder.
• #11790 tenant-repo-sync scheduler lane.
• #11791 operator docs + health/telemetry.
• learn/agentos/contract-ledger.md.

Origin Session ID

967e325b-d90a-43f4-9e91-c212e9bda746

Handoff Retrieval Hints

• query_raw_memories("#11789 #11790 #11791 Contract Ledger sourceFiles resolveDeploymentEnabled orchestrator.tasks setTenantConfig")
• query_raw_memories("Contract Ledger surface-anchor V-B-A row authoring")