Context
Epic #11558 requires a correctness substrate before semantic-anchor migration PRs can safely proceed. Discussion #11557 v5 selected Option C globally and made lint/CI one of the risk-mitigation pillars replacing phased execution.
The Problem
Without automated linting, new §N positional references can re-enter live skill or instruction substrate after the migration. Cross-family review can catch some cases, but the policy needs a mechanical merge-gate to prevent regression.
The Architectural Reality
The existing lint surface is ai/scripts/lint-agents.mjs and the CI check lint-skill-manifest. Discussion #11557's cascade-correctness substrate specifically calls for extending this lint path to flag new positional refs in skill files. This ticket modifies an existing build/lint script; it does not introduce a new .mjs file.
The Fix
Extend the agent lint path to detect forbidden live-substrate positional references and validate semantic-anchor usage according to the ADR from #11559.
Expected scope:
ai/scripts/lint-agents.mjs- tests or fixtures for allowed historical/archaeology exceptions and disallowed live
§N refs
- CI evidence from
lint-skill-manifest
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
| Agent lint |
New ADR from #11559 + Epic #11558 |
Fail when new live skill refs use positional §N instead of semantic anchors |
Cross-family review while lint evolves |
ADR + lint error text |
Unit/fixture coverage and CI run |
| Historical exceptions |
New ADR from #11559 |
Allow explicitly marked archaeology refs |
Manual review if classification ambiguous |
ADR |
Fixture coverage |
Discussion Criteria Mapping
- Cascade-correctness substrate -> lint + CI gate.
- Step 2.5 path determinism -> lint verifies semantic identity where practical.
- Active/archive boundary -> lint supports or documents exception handling.
- Migration blast-radius partial -> lint gives merge-gate confidence during partitioned PRs.
Acceptance Criteria
Out of Scope
- Migrating all existing references.
- Defining the ADR policy itself.
- Enforcing runtime framework behavior.
Avoided Traps / Gold Standards Rejected
- Review-only enforcement is rejected because it cannot prevent recurrence across every future session and PR.
- Over-broad banning of every historical
§N occurrence is rejected because archaeology refs may intentionally point to historical states.
Related
Origin Session ID: 6e5b995a-c68e-4179-840c-a4cc48d449da
Retrieval Hint: "lint-agents semantic anchor positional section refs lint-skill-manifest #11558"
Context
Epic #11558 requires a correctness substrate before semantic-anchor migration PRs can safely proceed. Discussion #11557 v5 selected Option C globally and made lint/CI one of the risk-mitigation pillars replacing phased execution.
The Problem
Without automated linting, new
§Npositional references can re-enter live skill or instruction substrate after the migration. Cross-family review can catch some cases, but the policy needs a mechanical merge-gate to prevent regression.The Architectural Reality
The existing lint surface is
ai/scripts/lint-agents.mjsand the CI checklint-skill-manifest. Discussion #11557's cascade-correctness substrate specifically calls for extending this lint path to flag new positional refs in skill files. This ticket modifies an existing build/lint script; it does not introduce a new.mjsfile.The Fix
Extend the agent lint path to detect forbidden live-substrate positional references and validate semantic-anchor usage according to the ADR from #11559.
Expected scope:
ai/scripts/lint-agents.mjs§Nrefslint-skill-manifestContract Ledger Matrix
§Ninstead of semantic anchorsDiscussion Criteria Mapping
Acceptance Criteria
.agents/skills/**references that use raw positional§Nanchors.lint-skill-manifestexercises the new guard.Out of Scope
Avoided Traps / Gold Standards Rejected
§Noccurrence is rejected because archaeology refs may intentionally point to historical states.Related
Origin Session ID: 6e5b995a-c68e-4179-840c-a4cc48d449da Retrieval Hint: "lint-agents semantic anchor positional section refs lint-skill-manifest #11558"