[AAASM-5750] 📝 (core): Point the §6 Planned referent at the capability ticket

[Chisanan232]

Description

Repoints the three ADR 0033 §6 Planned referent sites from AAASM-5731 to AAASM-5750, and adds a source scan that keeps them pointed correctly.

§6 scopes Planned to "decided but not implemented — a ticket reference; no capability claim." AAASM-5731 measured the absence of an SDK-side audit sink; it never intended to build one, and it is now closed. So today the term reads as a live commitment while the reference points at finished work. AAASM-5750 owns the capability.

This is that ticket's own "Until then" step — the capability itself (actually wiring a sink) stays open.

Sites repointed (3)

file:line	text
agent_assembly/core/audit_sink.py:22	makes SDK-side recording **Planned** (…), not
agent_assembly/adapters/_shared/tool_governance.py:188	Under ADR 0033 §6 that makes SDK-side recording **Planned** (…)
test/unit/test_quickstart_negative_control.py:303	(…), not Unmeasured, since where the record stops has been

Deliberately NOT repointed

Stated so the boundary is reviewable rather than implicit. Each of these cites AAASM-5731 as the ticket that measured the drop, which is still true:

• client/gateway.py:23, adapters/haystack/patch.py:17, adapters/llamaindex/adapter.py:15, core/assembly.py:127,325,439,544,559, core/runtime_interceptor.py:237,242,390 — finding references
• docs/** and README.md — 14 prose references to the measurement
• the AUDIT-PROBE-AAASM-5731 constant and test_audit_sink_disposition.py's header
• docs/examples/framework-support.md:57's ⏳ Planned — a docs-area maturity label, a different axis with a different owner. Not touched.

The gate

Nothing tests a comment or a docstring — they are the artifacts in a source tree with no mechanical check on them, and these three were corrected by hand once already. test/unit/core/test_planned_referent.py walks from the pyproject.toml root, pairs each §6 Planned with a ticket reference on the same line, and asserts the referent.

Two controls, both run:

control	result
revert core/audit_sink.py:22 to AAASM-5731	FAIL, naming that site and no other
empty the scanned-suffix set so the walk reaches no files	FAIL on the floor: scan found 0 …, floor is 3 … passing over nothing

The second matters as much as the first: an empty scan and a clean scan otherwise report the same result. Lowercase planned is ordinary English and is excluded by the pattern — docs/development/adr/0001-hook-architecture.md:22 ("was planned but superseded … AAASM-162") sits on a line with a ticket reference and is correctly not a site.

Type of Change

• 📚 Documentation update

Breaking Changes

• No

Related Issues

• Related JIRA ticket: AAASM-5750

Testing

• Unit tests added/updated — test/unit/core/test_planned_referent.py, with both controls exercised
• Manual testing performed — controls above

Measured:

gate	result
pytest test/	1224 passed, 16 skipped
ruff check .	All checks passed
ruff format --check on changed files	clean
pre-commit on the staged files	ruff check / ruff format / mypy all Passed

Pre-existing red on main, not from this branch: ruff format --check . reports scripts/check_contact_metadata.py would be reformatted. git diff --name-only remote/main -- scripts/check_contact_metadata.py returns nothing, so this branch does not touch it — it is AAASM-5748 (python-sdk pre-commit red on main, enforced by no CI job). Left alone deliberately rather than swept into this PR.

mypy agent_assembly reports 4 pre-existing import-not-found errors for agent_assembly._core — the native shim is not built in this worktree. Also not from this branch; pre-commit's mypy hook passes over the staged files.

Checklist

• Code follows project style guidelines
• Self-review completed
• Comments added for complex logic
• All tests passing

---

Review round 2 — the gate was broken, and it was broken the way it was built to prevent

Independent review found three ways the first gate could not fail. All three had one cause: the gate scanned its own file, whose header names AAASM-5750. That padded the site count with the gate quoting itself.

#	severity	defect
1	HIGH	node's floor was satisfied entirely by the gate's own two self-references. Deleting the only real site left the suite green.
2	HIGH	python's test_quickstart_negative_control.py splits Planned and its ticket across two lines. The same-line-only scan never saw it — the PR claimed coverage it did not have.
3	MED-HI	go collected 6 sites against a floor of 5, so deleting one site, or merely reflowing a comment, kept it green with a stale referent in the tree.
5	MED	all three asserted that every Planned in the repo names AAASM-5750. §6 scopes the term to any decided-but-unbuilt capability with any ticket, so the next unrelated roadmap row would have broken CI for a reason no reader could guess.
6	MED	the bodies and failure messages attributed the referent rule to ADR 0033 §6. §6 requires a ticket reference and says nothing about which. The rule is AAASM-5750's own, and is now cited as such.

What the gate asserts now

Two assertions, each narrow enough to be true:

1. No forward-looking claim defers to a closed measurement ticket. Planned or tracked as, paired with a ticket on its own line or the next, must not name AAASM-5731 or AAASM-5681. Those measured the absence; neither will build the sink. This never false-positives on an unrelated Planned.
2. Every guarded path is still reachable by the scan — asserted as a set of paths, not a count. A count can be held up by an unrelated site appearing as a real one is deleted; naming them makes that substitution visible.

The gate file is excluded from its own scan, with a positive control proving the exclusion is scoped: the identical stale-referent line fails when placed in any other file.

Every probe that previously passed, re-run against the rebuilt gate

probe	before	after
delete the only/one real site	green	red — names the missing path
reflow so term and ticket split lines	green	red — the lookahead catches the stale referent
revert python's split-line site	green	red
stale referent on node's tracked as line	unguarded	red
unrelated roadmap Planned (AAASM-9999)	red (wrong)	green
stale referent inside the gate file	n/a	green — correct, and the positive control shows the same line fails elsewhere

The reviewer also disputed the AAASM-5755 rationale, and the dispute holds up: capability-manifest row G10 (governance/capability-manifest.yaml:5123-5168) files a measured audit drop as coverage: unmeasured, and governance/README.md:417-419 is normative — "If none fits, the answer is unmeasured, not a twelfth term." That is precedent pointing the other way. AAASM-5755 has been re-scoped from a directive into an adjudication: it now asks which term is right, and lists the outcome where go-sdk and python-sdk are the ones that get corrected. No claim in this PR depends on the answer.

---

Review round 3 — round 2 was too narrow, in the opposite direction

Round 2 replaced an over-broad assertion with a two-element denylist. Review found that this stopped the gate asserting the thing the change made true: repointing a guarded site to any non-stale ticket passed green, including a real sibling ticket.

ffi_governance_client.go:169   AAASM-5750 -> AAASM-9999  ->  ok
ffi_governance_client.go:169   AAASM-5750 -> AAASM-5749  ->  ok

The likeliest drift — AAASM-5750 gets split or superseded and someone updates the referent — was undetected. Round 1 was too broad; round 2 too narrow. Both directions are now covered by splitting the assertion:

site	rule
guarded (a named audit-sink deferral)	must name AAASM-5750 exactly
any other	must merely not name a stale referent

The positive assertion is scoped to a named set, so it carries none of round 1's repo-wide over-breadth — the roadmap-row probe still passes.

A second defect round 2 introduced

The one-line lookahead had no directionality, and created a false-positive class the same-line rule could not produce. Forward-looking prose inserted above a correct backward citation was blamed for it:

153: // Streaming record delivery is Planned for a later release.     <- inserted, unrelated
154: // RecordResult discards the record and reports success (AAASM-5731).   <- pre-existing, CORRECT
FAIL: ffi_governance_client.go:153 defers to AAASM-5731

There are 81 backward citations across the three SDKs — go 30, python 33, node 18 — each a landmine for adjacent claim prose. None is adjacent today, so this was green by luck of layout rather than by construction.

The window now extends only when the claim line carries no ticket of its own and does not end a sentence. The reviewer's suggested fix (extend only within the same comment block) would not have worked — in the example above both lines are in one block. The sentence terminator is the discriminator that actually separates the two cases: the inserted line ends in ., python's genuinely wrapped site ends in §6.

Disclosed rather than fixed

• The reachability check is per file, not per site. A guarded file that reflowed its real site out of reach and gained a second correct claim would keep its entry. Requiring every forward-claim line in a guarded file to pair was considered and rejected: tool_wrapper.go:115 ("which is what Planned names") is legitimate prose with no ticket and would fail. Needs two coordinated edits; no file carries more than one site today.
• The excluded gate file is a hiding place. A test file that documents no SDK behaviour, and the exclusion matches one exact path rather than a prefix — verified with a positive control against a similarly-named neighbour.

Both are written into each gate's header.

Gates re-run

repo	tests	lint	types
go-sdk	407 passed	golangci 0 issues	gofmt clean
python-sdk	1224 passed, 16 skipped	ruff clean	pre-commit mypy pass
node-sdk	665 passed, 2 skipped	eslint 0	tsc 0

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud