---
id: 11882
title: Require surface-anchor V-B-A for Contract Ledger rows
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - architecture
  - model-experience
assignees:
  - neo-gpt
createdAt: '2026-05-24T06:42:21Z'
updatedAt: '2026-05-24T10:14:02Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11882'
author: neo-gpt
commentsCount: 1
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-24T10:14:02Z'
---
# 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

| Target Surface | Source of Authority | Proposed Behavior | Fallback / Edge Case | Docs | Evidence |
|---|---|---|---|---|---|
| `learn/agentos/contract-ledger.md` authoring guidance | #11788-#11791 refinement cycle + AGENTS.md Verify-Before-Assert | Add a row-level surface-anchor V-B-A subsection requiring empirical lookup for cited existing surfaces before naming fields, methods, helpers, tools, or docs. | If the surface is intentionally new, row must say it is introduced by this work rather than current substrate. | Yes | Static grep confirms the section exists and includes examples for field name, helper semantics, consumer alias, nonexistent surface, and stale scope. |
| `ticket-create` workflow pointer | Existing Contract Ledger creation gate | Add a compact pointer from the Contract Ledger bullet to the new surface-anchor V-B-A guidance; keep payload detail out of router/top-level skill. | If payload budget is tight, link only to `learn/agentos/contract-ledger.md`. | Yes | `rg` shows pointer present; skill manifest lint if workflow payload changes require it. |
| `ticket-intake` / `pr-review` audit wording | Existing intake and review ledger gates | Intake/review should check not only ledger presence, but whether rows naming existing surfaces cite or match current substrate. | For old tickets, reviewers may request a ledger refresh instead of blocking on historical prose if implementation matches current reality. | Yes | Focused doc diff; no runtime tests unless a lint/check is added. |

## 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

| Trap | Why rejected |
|---|---|
| Add another global rule to `AGENTS.md` | The failure is specific to Contract Ledger authoring and review; always-loaded substrate is unnecessary. |
| Require line-number citations in every ledger row | Useful when cheap, but too heavy as a universal rule; the key invariant is empirical anchoring before naming the surface. |
| Treat comments/A2A lessons as durable enough | Mailbox memory helped this session, but future ledger authors need the discipline in the contract-authoring substrate. |

## 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")`

## Timeline

- 2026-05-24T06:42:23Z @neo-gpt added the `documentation` label
- 2026-05-24T06:42:23Z @neo-gpt added the `enhancement` label
- 2026-05-24T06:42:23Z @neo-gpt added the `ai` label
- 2026-05-24T06:42:23Z @neo-gpt added the `architecture` label
- 2026-05-24T06:42:24Z @neo-gpt added the `model-experience` label
- 2026-05-24T06:44:54Z @neo-gpt assigned to @neo-gpt
### @neo-gpt - 2026-05-24T06:47:39Z

**Input from GPT-5 (Codex):**

> ● ## Ticket Intake Classification
> 
> Pre-Flight / V-B-A: To accept #11882, I re-read the live issue, searched the current Contract Ledger and workflow payloads for existing `surface-anchor` / row-level anchoring guidance, ran a live duplicate sweep, queried the Knowledge Base for adjacent Contract Ledger/V-B-A guidance, and checked Memory Core for the #11789/#11790/#11791 refinement cycle.
> 
> **Classification:** `valid-as-written`.
> 
> - **Ticket age:** created `2026-05-24T06:42:21Z`; current state is fresh / `pre-stale`; no stale/no-auto-close concern.
> - **Labels:** has `documentation`, `enhancement`, `ai`, `architecture`, `model-experience`; no triage blocker.
> - **ADR successor-risk:** no ADR amendment or successor dependency triggered; this hardens existing Contract Ledger workflow docs.
> - **Duplicate sweep:** live search for `"Contract Ledger" "surface-anchor"` returned only #11882.
> - **Existing enforcement audit:** current V-B-A and Contract Ledger payloads require verification and a six-column matrix, but do not name the row-level failure mode where existing surfaces are semantically plausible but stale/wrong. `rg` found Contract Ledger presence/drift gates, but no `surface-anchor` or equivalent row-authoring check.
> - **Memory evidence:** recent raw memories from session `967e325b-d90a-43f4-9e91-c212e9bda746` show the exact repeated refinements: `sourceFiles` -> `files/deleted/manifestSnapshot/baseRevision/headRevision`, `resolveDeploymentEnabled()` cloud-default inversion, `orchestrator.tasks` health anchor, and removal of nonexistent `setTenantConfig` MCP-tool framing.
> - **ROI:** positive. This is a narrow docs/workflow hardening that prevents repeated reviewer/operator correction cycles without adding always-loaded AGENTS.md payload.
> 
> Proceeding under #11882 with a narrow scope: `learn/agentos/contract-ledger.md` plus compact workflow pointers where needed; no new skill and no AGENTS.md expansion.

- 2026-05-24T06:51:34Z @neo-gpt cross-referenced by PR #11883
- 2026-05-24T09:30:15Z @neo-opus-ada cross-referenced by #11886
- 2026-05-24T10:14:02Z @tobiu referenced in commit `aa33672` - "docs(agentos): require contract ledger surface anchors (#11882) (#11883)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-24T10:14:02Z @tobiu closed this issue

