feat(KEN-3179): decider: a removed routine record keeps its ID reserved without keeping its document

[vanillagreen-fleet-lanes]

Summary

• The decider rule now separates removing a routine record (its choice holds, its reason moves to the code or principle doc it governs) from retiring one (its choice is withdrawn). Both delete the document and keep the INDEX row, so the ID stays reserved and next-id allocates past it. New Removed status; the row's Link cell stays as written, the Rationale cell names where the reason lives.
• The commit-guards md-refs lane accepts a decision ID whose INDEX row exists with no document file; an ID with neither a row nor a file still fails decision-missing, and a § Heading citation of a row-only ID fails decision-markdown. No new check, gate or limit.
• docs-writing rewrite.md step 6 agrees: a routine record whose reason moved may be removed, not only shortened, and every surviving citation points at the reason's new home; a one-line pointer document stays only where a citation outside the repository needs the path.

Rule map

Every changed rule, its old wording, and its new place or removal reason. The master reads this before merge.

Old rule (place)	New place or removal reason
decider SKILL.md § What warrants a decision record: "A record is never deleted: one withdrawn with no replacement is retired ... keeps its row and a one-line document"	Replaced in the same section: a routine record is removed once its reason lives in the code or principle doc it governs (removal is not withdrawal and changes no policy); a withdrawal with no replacement is a retirement; both follow workflows/update-decision.md, which deletes the document and keeps the INDEX row
decider SKILL.md: "a retired one binds nothing"	Kept; "a removed one binds through the code or principle doc its INDEX row names" added beside it
decider SKILL.md workflows table, update-decision trigger	Now also names retirement and removal
decider schemas/decision-format.md § INDEX.md: "The Link cell must name the decision document, a retired one included"	Replaced: the Link cell names the record's document and stays as written after that document is gone; decisions check reads it as the record's identity across branches
decider schemas/decision-format.md § Status values, Retired: "the row and a one-line document keep the ID reserved"	Replaced: "the row alone keeps the ID reserved"
(new) decider schemas/decision-format.md § Status values, Removed	Added: the choice holds; its reason lives in the code or principle doc the Rationale cell names; the row alone keeps the ID reserved
(new) decider schemas/decision-format.md § Decision document	Added: an active or superseded record has a document; a retired or removed one has none, except a one-line pointer where a citation outside the repository needs the path; md-refs accepts a row with no document
(new) decider schemas/decision-format.md § Cross-references, "Code → removed decision"	Added: the reason as a comment at the code, or a <path>.md § Heading citation of the principle doc
decider workflows/update-decision.md § 1: "For a retirement, shrink the file ... the file stays so the INDEX link resolves"	Replaced: for a retirement or a removal, delete the file; keep a one-line document only where a citation outside the repository needs the path
decider workflows/update-decision.md § 2: "Never remove a row"	Extended: never change its Link cell; for a removal, write where the reason now lives in the Rationale cell
(new) decider workflows/update-decision.md § 3, removal	Added: rewrite each REVISIT(ID) marker and every other citation of the ID in code, docs and AGENTS.md to point at the reason's new home, found by a literal search for the ID
(new) decider workflows/update-decision.md table, Remove row	Added: the choice is routine and holds; its reason now lives in the code or principle doc it governs; status Removed
decider templates/index-row.md: "The Link cell must name the decision file"	Extended: decisions check reads it as the identity across branches, so a retired or removed record keeps it as written
commit-guards CHECKS.md § md-refs: a decision ID "must have a tracked file DECISIONS_DIR/<ID>-*.md"	Replaced: must name a tracked file there or a row of the tracked DECISIONS_DIR/INDEX.md; the § form fails on an ID whose row has no file
commit-guards scripts/md-refs usage text, decision IDs	States the same two sources for an ID
docs-writing workflows/rewrite.md step 6: "Retire a record ... only when its choice is withdrawn"; "leave a pointer where an ID is still cited"	Retirement kept; removal per the decider's update-decision.md added for a routine record whose reason moved; the pointer sentence replaced by: keep a one-line pointer document only where a citation outside the repository needs the path, and a citation of a removed record points at the reason's new home

Route B (master note 1791312535), second commit aff5589: the Link cell of a retired or removed row becomes the backticked filename, so no dead link remains where md-refs judges the INDEX.

Old rule (place)	New place or removal reason
decider schemas/decision-format.md § INDEX.md (first commit): "The Link cell names the record's document and stays as written after that document is gone: decisions check reads it as the record's identity across branches"	Replaced: the Link cell names the record's document, as a link while the document exists and as the backticked filename once it is gone, so no dead link stays in a scope the commit-guards md-refs lane judges; decisions check compares the filename the cell resolves to, not the cell as written
decider schemas/decision-format.md § Status values, Retired and Removed rows	Each gains "its Link cell the backticked filename"
decider templates/index-row.md LINK row (first commit): "kept as written after the document is gone"	Replaced: a link while the document exists, the backticked filename once it is gone; the sentence below says decisions check compares the resolved filename
decider workflows/update-decision.md § 2 (first commit): "never change its Link cell ... reads the Link cell as the record's identity"	Replaced: for a retirement or a removal that deletes the document, rewrite the Link cell to the backticked filename; decisions check compares the filename the cell resolves to; never remove a row
decider scripts/decisions comment above parse_index: "its link cell as written ... is a record's identity"	Corrected: the filename the link cell resolves to is the identity across branches, so a status edit or a removal that rewrites the cell keeps the record it edits. No code change: parse_rows already resolves a link, a backticked filename or a bare filename to the same .link, and the base and duplicate checks already compare that value

Third commit 55a9302 (Copilot thread on update-decision.md § 3): one deletion rule for a retirement and a removal, so no citation of a deleted document dangles.

Old rule (place)	New place or removal reason
decider workflows/update-decision.md § 3 heading "Code markers"	Renamed "Citations": the step covers links in docs and sibling records as well as code markers
decider workflows/update-decision.md § 3: "For a retirement, remove each marker and leave a comment at its site only where the code still needs the reason. For a removal, rewrite each marker, and every other citation of the ID in code, docs and AGENTS.md, to point at the reason's new home ... Find them by searching for the ID literally"	Replaced by one rule for both: before the document is deleted, find every citation of the ID and of the document's file name by a literal search for both, in code, docs and AGENTS.md, a sibling record's [ID](ID-descriptor.md) link included; a removal's citations point at the reason's new home; a retirement's point at the INDEX row (the INDEX.md path or the row's Decision text in prose) or are removed, and its REVISIT markers are removed with a comment only where the code still needs the reason. The supersession and partial-supersession sentences are unchanged
decider workflows/update-decision.md § 1: "For a retirement or a removal, delete the file"	Extended: "once § 3 has repointed every citation of it", so the deletion follows the search
docs-writing workflows/rewrite.md step 6: "search for that ID literally, and search the INDEX links"	Now "search for that ID and the record's file name literally, and search the INDEX links"; nothing else in the step changed

Fourth commit 598d02f (Copilot threads on SKILL.md and the status table): the read instruction and one Link cell rule.

Old rule (place)	New place or removal reason
decider SKILL.md: "Read the full decision file and its status before acting on a hit"	Replaced: read a hit's INDEX row first, and its document only when the status is active or superseded; a retired or removed record has no document to read, and a removed one's reason lives where its Rationale cell names it. The binding sentences that follow are unchanged
decider schemas/decision-format.md § Status values, Retired and Removed rows (second commit): "its Link cell the backticked filename"	Replaced by "its Link cell following § INDEX.md", which is the one statement of the rule: a link while the document exists, the backticked filename once it is gone
decider templates/index-row.md LINK row and the sentence below (second commit): "becomes that filename in a code span"	Replaced: the row opens "See ../schemas/decision-format.md § INDEX.md", and the sentence says the cell's form follows the document's existence, so a retired or removed record whose pointer document is kept keeps its link
decider workflows/update-decision.md § 2	Unchanged: it already carries the conditional "a retirement or a removal that deletes the document"

Dropped with reason: the dev skill's workflows/dev-implement.md § 2.3 and the orch workflows/review-pr.md § 1.1 still say to read the full decision record before treating it as binding. Both sentences govern active records, whose documents exist; the decider SKILL.md owns the read rule and now states the retired and removed cases, and a restatement there would be a second copy of that rule.

No rule was removed without a replacement. No kendex decision record is removed in this PR; the master holds those removals (KEN-3182 removes D006 by this rule).

Context

• decisions check needed no code change: it never tested a document's presence, and its identity rule is the resolved Link cell filename. Suite rows prove the pass on a removing branch whose row carries the backticked cell against a base holding the link, and the allocation past a merged removal.
• Route B closes the gap the first commit left open: a consumer that widens COMMIT_GUARDS_MD_REFS_PATHS to docs/*.md (fleet does) has md-refs judge docs/decisions/INDEX.md, where a relative link to a deleted document fails link-target. Two md-refs suite rows under that setting pin the premise: the backticked form passes, the linked form of a documentless row fails. kendex's default path list leaves the INDEX unjudged.

Completed Issues

• Closes KEN-3179 - decider: a removed routine record keeps its ID reserved without keeping its document

Versions

• decider 2.0.2 → 2.1.3 (Added fragment; one raise per commit on the package), commit-guards 1.2.2 → 1.2.4 (Changed fragment; second raise for the test-only route B change under its directory), docs-writing 3.0.4 → 3.0.6 (Changed fragment; one raise per commit). No kendex program version change, no release.

Size

• Branch size check: unavailable (allowance_missing; the Linear cache is retired). Measured with git numstat against origin/main at 598d02f: 27 files, +202/−64 in all; sources without renders +135/−37, of which production +70/−27 and tests +65/−10. Issue allowance (Expected delta): 45 lines; route B and the citation rule added 15 production lines, the fourth commit rewrote lines without adding any.

Merge decision

Attempt on head 598d02f: exit 75, merge-route: queue cause=queue-occupied, QUEUED IN MERGE QUEUE (queueState=QUEUED).

Test Plan

• tools/guard --full through dev-validate-run: pass (full, 30 min, lanes guard-scans, selection all) at c68c816. The route B commit aff5589 and the doc-only commits 55a9302 and 598d02f validate in CI (mode ci: the PR CI checks the change); aff5589's suites ran locally: md-refs 201 passed, decider-base-collision 76 passed.
• skills/commit-guards/tests/md-refs.test.sh: 199 passed, 0 failed. New row world: a row-only ID passes; a § citation of it fails decision-markdown; an ID with neither row nor document fails decision-missing; a row-loader must-fail control.
• skills/decider/tests/decider-base-collision.test.sh: 75 passed, 0 failed. New rows check-removed-record and next-id-past-removed, one must-fail control each.
• preflight against origin/main: clean, 25 files, no findings.

[linear-code]

KEN-3179

[Copilot]

Copilot review overview

🟡 Changes recommended

Document deletion and retained-link handling remain inconsistent, leaving dangling references and guard failures in supported configurations.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Reconcile deleted documents with INDEX link-checker requirements · New
• Retirement workflow leaves dangling links to deleted decisions · New

What changed in this PR

This PR lets kendex’s decision-management skills remove routine decision documents while retaining INDEX rows to reserve their IDs.

Changes:

• Defines Removed status and updates retirement, removal, and citation guidance.
• Lets md-refs resolve bare decision IDs through retained INDEX rows.
• Adds regression cases, package version bumps, changelog entries, and synchronized renders.

File	Description
skills/​docs-writing/​workflows/​rewrite.md	Allows routine-record removal during rewrites.
skills/​docs-writing/​SKILL.md	Bumps package version.
skills/​decider/​workflows/​update-decision.md	Defines removal and retirement steps.
skills/​decider/​tests/​decider-base-collision.test.sh	Tests retained IDs after document deletion.
skills/​decider/​templates/​index-row.md	Preserves Link-cell identity.
skills/​decider/​SKILL.md	Adds removal policy and version bump.
skills/​decider/​schemas/​decision-format.md	Defines documentless records and statuses.
skills/​commit-guards/​tests/​md-refs.test.sh	Tests row-only citation handling.
skills/​commit-guards/​SKILL.md	Bumps package version.
skills/​commit-guards/​scripts/​md-refs	Supplies the staged INDEX to resolution.
skills/​commit-guards/​scripts/​lib/​md-refs.awk	Loads decision IDs from INDEX rows.
skills/​commit-guards/​CHECKS.md	Documents row-based ID resolution.
changelog.d/​docs-writing/​changed/​ken-3179-rewrite-removes-routine-records.md	Records rewrite guidance changes.
changelog.d/​decider/​added/​ken-3179-removed-records.md	Announces routine-record removal.
changelog.d/​commit-guards/​changed/​ken-3179-md-refs-index-row.md	Announces row-only citation support.
.agents/​skills/​docs-writing/​workflows/​rewrite.md	Synchronizes rendered rewrite guidance.
.agents/​skills/​docs-writing/​SKILL.md	Synchronizes rendered version.
.agents/​skills/​decider/​workflows/​update-decision.md	Synchronizes rendered update workflow.
.agents/​skills/​decider/​templates/​index-row.md	Synchronizes rendered row template.
.agents/​skills/​decider/​SKILL.md	Synchronizes rendered policy and version.
.agents/​skills/​decider/​schemas/​decision-format.md	Synchronizes rendered record schema.
.agents/​skills/​commit-guards/​SKILL.md	Synchronizes rendered version.
.agents/​skills/​commit-guards/​scripts/​md-refs	Synchronizes rendered INDEX loading.
.agents/​skills/​commit-guards/​scripts/​lib/​md-refs.awk	Synchronizes rendered row resolver.
.agents/​skills/​commit-guards/​CHECKS.md	Synchronizes rendered check documentation.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot review overview

🟢 Approved

The final review contains only non-blocking documentation suggestions.

Review effort: Balanced
Findings: 2

Open (2)

• Search instructions incorrectly require files for removed records · New
• Index rules remove links to retained pointer documents · New

Resolved since last review (1)

• Retirement workflow leaves dangling links to deleted decisions

[Copilot]

Copilot review overview

🟢 Approved

No blocking defects remain; the checker matches its documented contract, with regression coverage for documentless records and ID preservation.

Review effort: Balanced
Findings: 2

Open (2)

• Index rules remove links to retained pointer documents
• Search instructions incorrectly require files for removed records

[Copilot]

Copilot review overview

🟢 Approved

The implementation matches the documented ID-resolution contract, regression coverage addresses the changed behavior, and no blocking issues remain.

Review effort: Balanced
Findings: None

[vanillagreen-fleet-lanes]

Completed Issues

• Closes KEN-3179 - decider: a removed routine record keeps its ID reserved without keeping its document

Recommendations Processed

Fixed in PR

• pr-comments (Copilot, head c68c816): a removed or retired row whose Link cell stays a relative link after its document is deleted fails md-refs link-target where the INDEX is judged — aff5589 (route B: the Link cell becomes the backticked filename once the document is deleted; decisions check compares the resolved filename)
• pr-comments (Copilot, head c68c816): retirement deletes the document but update-decision.md § 3 only removed REVISIT markers, leaving sibling records' [ID](ID-descriptor.md) links dangling — 55a9302 (one deletion rule for retirement and removal: find every citation of the ID and the file name before the delete)
• pr-comments (Copilot, head 55a9302): decider SKILL.md's read-the-full-file sentence sent an agent to a deleted path for a retired or removed hit — 598d02f (read the INDEX row first, the document only for an active or superseded status)
• pr-comments (Copilot, head 55a9302): the status rows and index-row.md demanded the backticked Link cell unconditionally while a kept pointer document should keep its link — 598d02f (decision-format.md § INDEX.md is the one Link cell rule; the status rows and index-row.md defer to it)

Skipped

• dev sweep note: the dev skill's dev-implement.md § 2.3 and the orch review-pr.md § 1.1 still say to read the full decision record before treating it as binding — declined: both sentences govern active records, whose documents exist; decider SKILL.md owns the read rule and now states the retired and removed cases, and a restatement there would be a second copy of that rule

Fix rounds: 3 | Docs program terms: no reviewer subagents; every round answered a Copilot thread or the master's route B directive. Review gate approved and CI green at 598d02f. Versions: decider 2.0.2 → 2.1.3, commit-guards 1.2.2 → 1.2.4, docs-writing 3.0.4 → 3.0.6.