fix(skills): record settled ADR decisions #98
Loading…
Reference in a new issue
No description provided.
Delete branch "fix/project-docs-adr-acceptance"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
ADRs now record acceptance when the user settles a decision, even before implementation. Accepted and statusless records bind; proposed choices remain open. Conflicting plans use the same rule in documentation and grilling sessions.
Keep only current decisions, preserve useful rejected alternatives, repair deleted-record links, and never reuse ADR numbers. Every new or edited ADR receives a whole-record check against relevant implementation and governing decisions, including after mechanical edits. Implementation gaps are reported without rewriting settled intent.
The reviewer integration in j4k/review#94 and the skill pin in j4k/review-runner#25 must use the merged revision; repin the runner after this merges.
Review
01M41SFZWKA8GGYFCW0ZY7PGEB— headbc0921e42bab9862a5108abda1377c10de421e99Review — j4k-oss/agent-skills @
2034125557Scope: diff against base tree
2bb52ad1ca16Status: dispatched — coverage complete (4/4 slots terminal)
Facts: current review-wide projection
Computed under:
Findings (7)
high — ADR loading rule repeats the complete status value set
01M41SRZK1AA7QXAW0CH87CMZEskills/project-docs/SKILL.md(snippet)high — Design brief count duplicates the constraint list
01M41SPMTDFYW4XN25RCP5C0F1skills/reengineer-program/references/compare-designs.md(snippet)high — Completion rule copies the number of verification checks
01M41SQ0VYDZ9TZG3GVQ92RVYJskills/reengineer-program/references/implementation.md(snippet)high — verify-doc-drift copies the binding ADR status set
01M41SNRHJN7GVSFZ4JS21YZ9Hskills/verify-doc-drift/SKILL.md(snippet)high — ADR drift rule repeats project-docs maintenance actions
01M41STGVHDAQ8A4Z39KBR3HR6skills/verify-doc-drift/SKILL.md(snippet)medium — Statusless reengineering backlog becomes binding without migration
01M41SN326AB5VY88DAFHFGAQ8skills/project-docs/SKILL.md(snippet)medium — ADR maintenance refers to a skill that this audit never loads
01M41SR8B4BRF263JVRJ39D11Cskills/verify-doc-drift/SKILL.md(snippet)Other claims
Coverage
Coverage pass: 01M41SFZY6AF097K8066D4S79S
Accounting: complete
Slot health: healthy
@ -52,3 +52,3 @@Before planning or designing on top of an existing codebase:1. Check the repo root. If `CONTEXT-MAP.md` exists, read it, identify which contexts the task touches, and read their `CONTEXT.md` files. Otherwise read the root `CONTEXT.md` if present.1. Check the repo root. If `CONTEXT-MAP.md` exists, read it, list every tracked `CONTEXT.md`, the root one included (`git ls-files ':(glob)**/CONTEXT.md'`), identify which contexts the task touches, and read their `CONTEXT.md` files. Otherwise read the root `CONTEXT.md` if present.medium — Context discovery skips untracked glossaries in the working tree
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3XVA54BMXDT8QGHHMRMAMZHof review01M3XV50BTQCWEGQD4AF64TVWFsuperseded by review
01M3XVM7DM1RXJMNJVKDT8YYR1for headb7a6d1aaacf26262ba8c3cfb9a0047215287fc98Already fixed in
e7d1864, which removed thegit ls-filesdiscovery step and restored the context list inCONTEXT-MAP.md; loading reads the contexts from the map again.@ -58,3 +58,3 @@- **Use the glossary's canonical terms** in everything you produce — plans, code, commit messages. When the user's wording conflicts with a defined term, flag the mismatch instead of silently adopting either side.- **Don't re-litigate recorded ADRs.** A status-less ADR counts as accepted; only an ADR marked `proposed` is still open, and a `deprecated` or `superseded` one no longer binds — its successor, where one exists, governs instead. If the plan contradicts a binding ADR, name it ("this conflicts with ADR-0007") and either adjust the plan or supersede the ADR — never silently override a recorded decision.- **Don't re-litigate recorded ADRs.** A status-less ADR counts as accepted, and one marked `proposed` is decided but not yet built; a `deprecated` or `superseded` one no longer binds — its successor, where one exists, governs instead. If the plan contradicts a binding ADR, name it ("this conflicts with ADR-0007") and either adjust the plan or supersede the ADR — never silently override a recorded decision.medium —
proposedhas conflicting meanings across documentation skillslens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3XV82Q857XA3W14T0EGSDT5of review01M3XV50BTQCWEGQD4AF64TVWFsuperseded by review
01M3XVM7DM1RXJMNJVKDT8YYR1for headb7a6d1aaacf26262ba8c3cfb9a0047215287fc98Already fixed in
a02ba51:proposedagain means an open decision in project-docs, matching verify-doc-drift's "open question" reading, and a settled decision isaccepted.@ -146,2 +143,3 @@- **Update inline, don't batch.** When the user settles a term or a decision mid-session, write it down right then. Deferred documentation doesn't happen. A plan you propose is not a decision until the user accepts it.- **Update inline, don't batch.** When the user settles a term or a decision mid-session, write it down right then. Deferred documentation doesn't happen. A plan you suggest is not a decision until the user accepts it.- **Accept an ADR with its implementation.** Record a decision that is not yet built as `proposed`. The change that builds it, and no earlier one, sets the ADR to `accepted` before it merges and marks each older record the ADR supersedes or amends; an amended record keeps its status and gains a note naming the amending ADR.medium — Delayed supersession leaves contradictory ADRs binding during planning
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3XVAW7EMNM3XQSGN54W8D5Wof review01M3XV50BTQCWEGQD4AF64TVWFsuperseded by review
01M3XVM7DM1RXJMNJVKDT8YYR1for headb7a6d1aaacf26262ba8c3cfb9a0047215287fc98Already fixed in
a02ba51andc672626:proposedis open again and does not bind, so the accepted predecessor is the one governing decision until the change that builds the replacement edits or deletes it. No supersession step remains.@ -52,3 +52,3 @@Before planning or designing on top of an existing codebase:1. Check the repo root. If `CONTEXT-MAP.md` exists, read it, identify which contexts the task touches, and read their `CONTEXT.md` files. Otherwise read the root `CONTEXT.md` if present.1. Check the repo root. If `CONTEXT-MAP.md` exists, read it, list every tracked `CONTEXT.md`, the root one included (`git ls-files ':(glob)**/CONTEXT.md'`), identify which contexts the task touches, and read their `CONTEXT.md` files. Otherwise read the root `CONTEXT.md` if present.medium — Include untracked context glossaries when loading project docs
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3XVVDQ0JYC53YMFHS818ZZ9of review01M3XVM7DM1RXJMNJVKDT8YYR1superseded by review
01M3XWHXMV98SN26Q201S1D7BPfor heade7d186400ced1a3495e7d4c2b4b9d44d775ec3cbAlready fixed in
e7d1864, which removed thegit ls-filesdiscovery step and restored the context list inCONTEXT-MAP.md; loading reads the contexts from the map again.@ -58,3 +58,3 @@- **Use the glossary's canonical terms** in everything you produce — plans, code, commit messages. When the user's wording conflicts with a defined term, flag the mismatch instead of silently adopting either side.- **Don't re-litigate recorded ADRs.** A status-less ADR counts as accepted; only an ADR marked `proposed` is still open, and a `deprecated` or `superseded` one no longer binds — its successor, where one exists, governs instead. If the plan contradicts a binding ADR, name it ("this conflicts with ADR-0007") and either adjust the plan or supersede the ADR — never silently override a recorded decision.- **Don't re-litigate recorded ADRs.** A status-less ADR counts as accepted, and one marked `proposed` is decided but not yet built; a `deprecated` or `superseded` one no longer binds — its successor, where one exists, governs instead. If the plan contradicts a binding ADR, name it ("this conflicts with ADR-0007") and either adjust the plan or supersede the ADR — never silently override a recorded decision.medium — Project-docs treats new open ADRs as binding decisions
lens
general-bug· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3XVQVXKCJS7M299V8VHC557of review01M3XVM7DM1RXJMNJVKDT8YYR1superseded by review
01M3XWHXMV98SN26Q201S1D7BPfor heade7d186400ced1a3495e7d4c2b4b9d44d775ec3cbAlready fixed in
80588f6, which reverted thestatus: openrecords; reengineer-program again marks open ADRsstatus: proposed, which project-docs treats as still open.@ -46,3 +46,1 @@- **Open (`status: proposed`):** state the situation and current behavior. Status-less ADRs count as proposed and stay unchanged until answered. Superseded or deprecated ADRs do not settle promises still in code.- **Keep (`status: accepted`):** state the situation, obligation, stakeholder goal, or risk and the chosen promise. A deferred keep names the owner who must decide.- **Drop (`status: accepted`):** state the negative promise and reason, such as "We do not support concurrent writers because each deployment has one writer." For "don't care, take the smallest," record only the negative promise. Record drops even when `project-docs`' ADR test excludes them.- **Open (`status: open`):** state the situation and current behavior. Superseded or deprecated ADRs do not settle promises still in code.medium — Previously open status-less ADRs are treated as settled on resume
lens
general-bug· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3XVQ2X4K3R9NDPA03HTK9SWof review01M3XVM7DM1RXJMNJVKDT8YYR1superseded by review
01M3XWHXMV98SN26Q201S1D7BPfor heade7d186400ced1a3495e7d4c2b4b9d44d775ec3cbDeclining: a status-less ADR counting as accepted is the user's decision for this PR. The statuses are
proposed(open) andaccepted(decided), and a status-less ADR is accepted. project-docs on main already said so; reengineer-program's "status-less ADRs count as proposed" override contradicted it. reengineer-program did not create status-less question ADRs either: on main it gave every ADRstatusfrontmatter and created each open root asstatus: proposed, which still marks an open ADR.@ -49,0 +47,4 @@- **Keep:** state the situation, obligation, stakeholder goal, or risk and the chosen promise. A deferred keep names the owner who must decide.- **Drop:** state the negative promise and reason, such as "We do not support concurrent writers because each deployment has one writer." For "don't care, take the smallest," record only the negative promise. Record drops even when `project-docs`' ADR test excludes them.Mark a keep or drop `accepted` when the code already reflects it; otherwise mark it `proposed` until the change that builds it merges. Both are decided ADRs.medium — Existing proposed ADRs become decided without a user answer
lens
general-bug· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3XVRP4CRMXFQXAASC94BV76of review01M3XVM7DM1RXJMNJVKDT8YYR1superseded by review
01M3XWHXMV98SN26Q201S1D7BPfor heade7d186400ced1a3495e7d4c2b4b9d44d775ec3cbAlready fixed in
80588f6, which revertedb7a6d1a; reengineer-program again marks an unanswered ADROpen (status: proposed), so existing proposed ADRs stay in the decision backlog.fix(project-docs): accept ADRs with their implementation and keep the context map to relationshipsto fix(project-docs): accept ADRs with their implementation@ -58,3 +58,3 @@- **Use the glossary's canonical terms** in everything you produce — plans, code, commit messages. When the user's wording conflicts with a defined term, flag the mismatch instead of silently adopting either side.- **Don't re-litigate recorded ADRs.** A status-less ADR counts as accepted; only an ADR marked `proposed` is still open, and a `deprecated` or `superseded` one no longer binds — its successor, where one exists, governs instead. If the plan contradicts a binding ADR, name it ("this conflicts with ADR-0007") and either adjust the plan or supersede the ADR — never silently override a recorded decision.- **Don't re-litigate recorded ADRs.** A status-less ADR counts as accepted, and one marked `proposed` is decided but not yet built; a `deprecated` or `superseded` one no longer binds — its successor, where one exists, governs instead. If the plan contradicts a binding ADR, name it ("this conflicts with ADR-0007") and either adjust the plan or supersede the ADR — never silently override a recorded decision.medium — Existing statusless question ADRs become settled without an answer
lens
general-bug· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3XWRDVN83FNAPVQTPHE8QK1of review01M3XWHXMV98SN26Q201S1D7BPsuperseded by review
01M3XYGR3KHZXEV5EJVPMTXCDTfor heada02ba510acbbff8582b9f9c4833c656b9dfff285superseded by review
01M3XYGR3KHZXEV5EJVPMTXCDTfor heada02ba510acbbff8582b9f9c4833c656b9dfff285Declining: a status-less ADR counting as accepted is the user's decision for this PR. The statuses are
proposed(open) andaccepted(decided), and a status-less ADR is accepted. project-docs on main already said so; reengineer-program's "status-less ADRs count as proposed" override contradicted it. reengineer-program did not create status-less question ADRs either: on main it gave every ADRstatusfrontmatter and created each open root asstatus: proposed, which still marks an open ADR.@ -121,3 +121,3 @@That's it. An ADR can be a single paragraph — the value is in recording _that_ a decision was made and _why_, not in filling out sections. Add optional sections only when they earn their place:- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — when decisions get revisited- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — when a decision is not yet built or gets revisitedmedium — Define the open ADR status in the shared documentation contract
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3XWNTBGK78RESH76KFWFWCBof review01M3XWHXMV98SN26Q201S1D7BPsuperseded by review
01M3XYGR3KHZXEV5EJVPMTXCDTfor heada02ba510acbbff8582b9f9c4833c656b9dfff285superseded by review
01M3XYGR3KHZXEV5EJVPMTXCDTfor heada02ba510acbbff8582b9f9c4833c656b9dfff285Already fixed in
80588f6, which reverted thestatus: openrecords; the shared status list (proposed | accepted) covers every status the skills write.@ -146,2 +146,3 @@- **Update inline, don't batch.** When the user settles a term or a decision mid-session, write it down right then. Deferred documentation doesn't happen. A plan you propose is not a decision until the user accepts it.- **Update inline, don't batch.** When the user settles a term or a decision mid-session, write it down right then. Deferred documentation doesn't happen. A plan you suggest is not a decision until the user accepts it.- **Accept an ADR with its implementation.** Record a decision that is not yet built as `proposed`. The change that builds it, and no earlier one, sets the ADR to `accepted` before it merges and marks each older record the ADR supersedes or amends; an amended record keeps its status and gains a note naming the amending ADR.medium — Specify which ADR governs while a decided replacement awaits implementation
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3XWPW8BT8ZP7SEKT3HF1KV7of review01M3XWHXMV98SN26Q201S1D7BPsuperseded by review
01M3XYGR3KHZXEV5EJVPMTXCDTfor heada02ba510acbbff8582b9f9c4833c656b9dfff285superseded by review
01M3XYGR3KHZXEV5EJVPMTXCDTfor heada02ba510acbbff8582b9f9c4833c656b9dfff285Already fixed in
a02ba51andc672626:proposedis open again and does not bind, so the accepted predecessor is the one governing decision until the change that builds the replacement edits or deletes it. No supersession step remains.fix(project-docs): accept ADRs with their implementationto fix(project-docs): ship an ADR accepted with the change that builds it@ -145,6 +145,7 @@ What qualifies:## Maintenance rules- **Update inline, don't batch.** When the user settles a term or a decision mid-session, write it down right then. Deferred documentation doesn't happen. A plan you propose is not a decision until the user accepts it.- **Ship an ADR accepted with the change that builds it.** That change sets the ADR to `accepted` before it merges and marks each older record it supersedes or amends; an amended record keeps its status and gains a note naming the amending ADR.medium — Clarify when a draft ADR becomes accepted
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3XYS034F59QPTYBHAEPXDXNof review01M3XYGR3KHZXEV5EJVPMTXCDTsuperseded by review
01M3Y07MB5A1RCDDP61X4SJCHFfor headc672626bd054c406bcbf7766008c5dee6a50e672Already fixed in
71043340d9via #102: acceptance occurs when the user settles the decision, even before implementation; implementation completion is a separate check.@ -145,6 +145,7 @@ What qualifies:## Maintenance rules- **Update inline, don't batch.** When the user settles a term or a decision mid-session, write it down right then. Deferred documentation doesn't happen. A plan you propose is not a decision until the user accepts it.- **Ship an ADR accepted with the change that builds it.** That change sets the ADR to `accepted` before it merges and marks each older record it supersedes or amends; an amended record keeps its status and gains a note naming the amending ADR.medium — Clarify when a draft ADR becomes accepted
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3XYS034F59QPTYBHAEPXDXNof review01M3XYGR3KHZXEV5EJVPMTXCDTsuperseded by review
01M3Y07MB5A1RCDDP61X4SJCHFfor headc672626bd054c406bcbf7766008c5dee6a50e672Already fixed in
71043340d9via #102: acceptance occurs when the user settles the decision, even before implementation; implementation completion is a separate check.fix(project-docs): ship an ADR accepted with the change that builds itto fix(skills): keep only current ADRs@ -58,3 +58,3 @@- **Use the glossary's canonical terms** in everything you produce — plans, code, commit messages. When the user's wording conflicts with a defined term, flag the mismatch instead of silently adopting either side.- **Don't re-litigate recorded ADRs.** A status-less ADR counts as accepted; only an ADR marked `proposed` is still open, and a `deprecated` or `superseded` one no longer binds — its successor, where one exists, governs instead. If the plan contradicts a binding ADR, name it ("this conflicts with ADR-0007") and either adjust the plan or supersede the ADR — never silently override a recorded decision.- **Don't re-litigate recorded ADRs.** A status-less ADR counts as accepted; only an ADR marked `proposed` is still open. An ADR with any other status, such as `superseded` or `deprecated`, is outdated and does not bind: delete it per the maintenance rules. If the plan contradicts an accepted ADR, name it ("this conflicts with ADR-0007"), then either adjust the plan or, on the user's decision, change the ADR per the maintenance rules — never silently override a recorded decision.medium — Clarify that accepted ADRs still bind
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3Y0C3YESESRCDPX1GKZBJ2Bof review01M3Y07MB5A1RCDDP61X4SJCHFsuperseded by review
01M3Y3EMSCR0EWR8CFG2FV7Z2Qfor headd2e1564536a5f4cd367bf7e660375f3ec10bcf02Already fixed in
71043340d9via merged followup #102: the loading rule explicitly classifies accepted and statusless ADRs as binding, proposed as open, and only other statuses as outdated. Rechecked the live source.@ -145,6 +145,7 @@ What qualifies:## Maintenance rules- **Update inline, don't batch.** When the user settles a term or a decision mid-session, write it down right then. Deferred documentation doesn't happen. A plan you propose is not a decision until the user accepts it.- **Ship an ADR accepted with the change that builds it.** That change sets the ADR to `accepted` before it merges and marks each older record it supersedes or amends; an amended record keeps its status and gains a note naming the amending ADR.medium — Clarify when a draft ADR becomes accepted
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3XYS034F59QPTYBHAEPXDXNof review01M3XYGR3KHZXEV5EJVPMTXCDTsuperseded by review
01M3Y07MB5A1RCDDP61X4SJCHFfor headc672626bd054c406bcbf7766008c5dee6a50e672Already fixed in
71043340d9via #102: acceptance occurs when the user settles the decision, even before implementation; implementation completion is a separate check.@ -146,3 +146,3 @@- **Update inline, don't batch.** When the user settles a term or a decision mid-session, write it down right then. Deferred documentation doesn't happen. A plan you propose is not a decision until the user accepts it.- **Supersede living decisions; delete dead ones.** When a decision is reversed but the area it governs still exists, write a new ADR and mark the old one `superseded by ADR-NNNN` — the old rationale still explains why the code looked the way it did. But when a refactor removes the subject of a decision entirely, edit or delete the ADR: a record about code that no longer exists only misleads, and version control remembers. Leave numbering gaps as-is after a deletion — renumbering breaks `superseded by` references.- **Ship an ADR accepted with the change that builds it.** That change sets a `proposed` ADR to `accepted` before it merges and edits or deletes each older ADR whose decision it changes, per the next rule.low — project-docs gives two incompatible rules for when an ADR becomes
accepted(on user settlement vs. on the merge that builds it)lens
general-bug· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3Y3JB71C911P0WEN71CSYNZof review01M3Y3EMSCR0EWR8CFG2FV7Z2QAlready fixed in
71043340d9via merged followup #102: Accept when settled now explicitly accepts on the user decision before implementation and distinguishes acceptance from implementation completion. Rechecked the live source; the contradictory ship-time trigger is gone.@ -147,2 +147,3 @@- **Update inline, don't batch.** When the user settles a term or a decision mid-session, write it down right then. Deferred documentation doesn't happen. A plan you propose is not a decision until the user accepts it.- **Supersede living decisions; delete dead ones.** When a decision is reversed but the area it governs still exists, write a new ADR and mark the old one `superseded by ADR-NNNN` — the old rationale still explains why the code looked the way it did. But when a refactor removes the subject of a decision entirely, edit or delete the ADR: a record about code that no longer exists only misleads, and version control remembers. Leave numbering gaps as-is after a deletion — renumbering breaks `superseded by` references.- **Ship an ADR accepted with the change that builds it.** That change sets a `proposed` ADR to `accepted` before it merges and edits or deletes each older ADR whose decision it changes, per the next rule.- **Keep only current decisions.** When a decision changes, edit its ADR to state the new decision. When a new decision replaces it outright, delete the old ADR and add a new one. Delete an ADR whose decision no longer applies. After deleting an ADR, update or remove every link to it. Never keep an outdated ADR marked superseded or deprecated, or annotated with a note pointing to another ADR, and never write "amends ADR-X" or "supersedes ADR-X" in the newer one: each ADR states its own decision, and version control keeps the history. When the reason the old approach was dropped is worth keeping, record it under the current ADR's Considered Options.low — "Keep only current decisions" offers edit-in-place vs delete-and-renumber with no usable criterion between "changes" and "replaces outright"
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3Y3KC6JVHWZ9HXHWHZVC25Xof review01M3Y3EMSCR0EWR8CFG2FV7Z2QDeclining: the edit-or-replace split is the user's decision for this PR. A changed decision edits its ADR, and a decision replaced outright gets a new ADR while the old one is deleted. The proposed criterion would turn most changes into delete-and-add, which reverses that default. Nothing is renumbered: a new ADR takes the next unused number, and a deleted one leaves a gap (ADR format section). An old commit citing
ADR-0007after an in-place edit follows from the same decision: ADRs state only the current decision, and git keeps the version that commit executed.superseded by review
01M41KHRHF0D8BVKBP18YFCNQDfor head71043340d911e11dff997d7fd7af7733b0d468f6@ -57,3 +57,3 @@Replace proposed text with the accepted decision when answered. Delete proposed ADRs only when they duplicate another root; retain accepted negatives after their code disappears. Use the same format for design choices, implementation gaps, and review findings. ADRs plus git carry resume state; execution history belongs in commits.Accepted ADRs remain settled across sessions. Supersede one when a fact undermines its reason, a witness appears for a don't-care drop, or a deferred keep's owner answers. Proposed and status-less ADRs are the decision backlog.Accepted ADRs remain settled across sessions. When a fact undermines one's reason or a witness appears for a don't-care drop, put it to the user; when the user or a deferred keep's owner answers, edit or replace the ADR per `project-docs`. Proposed ADRs are the decision backlog; status-less ADRs count as accepted.low — reengineer-program restates project-docs' status-less default, creating a second home that its precedence clause would let drift into an override
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M3Y3KPWDZ9ECKE0X7S2SXXGDof review01M3Y3EMSCR0EWR8CFG2FV7Z2QAlready fixed in
71043340d9via merged followup #102: reengineer-program now says only Proposed ADRs are the decision backlog; the duplicate statusless default was removed. Project-docs remains its declared, loaded dependency.Real, and deliberately deferred under the review round gate. This is round 6 on this PR (five fix pushes since it opened), where only security, data-corruption, or data-loss bugs are fixed in place. Reviewed at
d2e1564.Follow-up fix, in
skills/project-docs/SKILL.mdunder Maintenance rules: make the user's settlement the one trigger foraccepted, and keep the build rule as a merge gate. Replace the "Ship an ADR accepted with the change that builds it" bullet with: "Mark an ADR accepted when the user settles it. The change that builds a decision never merges with its ADR stillproposed, and it edits or deletes each older ADR whose decision it changes, per the next rule." verify-doc-drift'sproposedhandling then needs no change.Real, and deliberately deferred under the review round gate. This is round 6 on this PR, where only security, data-corruption, or data-loss bugs are fixed in place.
d2e1564replaced the on-sight deletion with "flag it, and fix it … only when that is the task or the user agrees", so an accepted ADR can no longer be deleted through this sentence. The wording itself remains: "any other status" follows "only an ADR markedproposedis still open", so it can be read as includingaccepted.Follow-up fix, in
skills/project-docs/SKILL.mdunder "Don't re-litigate recorded ADRs": change "An ADR with any other status, such assupersededordeprecated," to "An ADR with any status other thanacceptedorproposed, such assupersededordeprecated,".Real, and deliberately deferred under the review round gate (round 6 on this PR).
c672626madeproposedmean a decision "recorded before it is settled", but "Ship an ADR accepted with the change that builds it" still reads as the acceptance trigger. The current head re-raises the same ambiguity as #102381. The follow-up fix named there settles this one too: inskills/project-docs/SKILL.md, accept an ADR when the user settles it, and bar the change that builds it from merging while the ADR is stillproposed.Duplicate posting of claim
01M3XYS034F59QPTYBHAEPXDXN, handled at #101868: real, deferred under the round gate (round 6 on this PR) to the follow-up fix named at #102381, inskills/project-docs/SKILL.md.Real, and deliberately deferred under the review round gate. This is round 6 on this PR, where only security, data-corruption, or data-loss bugs are fixed in place. Reviewed at
d2e1564.Follow-up fix, in
skills/reengineer-program/SKILL.md(line 59): change "Proposed ADRs are the decision backlog; status-less ADRs count as accepted." to "Proposed ADRs are the decision backlog." project-docs, which this skill loads first, owns the status-less default.@ -28,3 +28,3 @@**Cross-reference with code.** When the user states how something works, check whether the code agrees, and surface any contradiction: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"**Name ADR conflicts.** When the plan contradicts a recorded ADR, say so explicitly — "this conflicts with ADR-0007" — and force the choice: adjust the plan, or supersede the ADR per the `project-docs` skill. Never let a plan silently override a recorded decision.**Name ADR conflicts.** When the plan contradicts an accepted ADR, say so explicitly — "this conflicts with ADR-0007" — and force the choice: adjust the plan, or change the ADR per the `project-docs` skill. Never let a plan silently override a recorded decision.high — Grilling instruction copies ADR conflict choices
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41KTMJ6EPCTFE5M0X7ZYYNDof review01M41KHRHF0D8BVKBP18YFCNQDFixed in
babf98cbbcwhile repairing the binding-ADR guard: grill-with-docs names the conflict and delegates resolution to its declared and explicitly loaded project-docs dependency.@ -58,3 +58,3 @@- **Use the glossary's canonical terms** in everything you produce — plans, code, commit messages. When the user's wording conflicts with a defined term, flag the mismatch instead of silently adopting either side.- **Don't re-litigate recorded ADRs.** A status-less ADR counts as accepted; only an ADR marked `proposed` is still open, and a `deprecated` or `superseded` one no longer binds — its successor, where one exists, governs instead. If the plan contradicts a binding ADR, name it ("this conflicts with ADR-0007") and either adjust the plan or supersede the ADR — never silently override a recorded decision.- **Don't re-litigate recorded ADRs.** An ADR marked `accepted`, or without a status, is decided and binding; `proposed` means the decision is still open. Other statuses, including `superseded` and `deprecated`, are outdated and do not bind: flag them and use the maintenance rules when that cleanup is authorized. If the plan contradicts an accepted ADR, name it ("this conflicts with ADR-0007"), then either adjust the plan or, on the user's decision, change the ADR per the maintenance rules — never silently override a recorded decision.medium — Conflict rule omits binding ADRs without a status
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41KPHNVTAJEHTG2049AVGTKof review01M41KHRHF0D8BVKBP18YFCNQDFixed in
babf98cbbc: both project-docs and grill-with-docs now check conflicts against binding ADRs, covering explicit accepted and statusless records. The shared rule retains the user decision gate; accepted-but-unimplemented targets, proposed choices, and whole-record verification are unchanged.@ -31,3 +31,3 @@Have a fresh-context sub-agent attack the result from both directions: find situations the old code handles that the rebuild omits without an accepted decision, and promises the rebuild makes that no accepted decision covers. Mechanism-only differences and replacements chosen by an accepted ADR are not findings.Put each uncovered situation to the user and record the answer in an added or superseding ADR before adding, removing, or keeping its promise. Completion requires the implementation to satisfy the confirmed design, all three checks to pass, and every review finding to be resolved.Put each uncovered situation to the user and record the answer in a new or edited ADR before adding, removing, or keeping its promise. Completion requires the implementation to satisfy the confirmed design, all three checks to pass, and every review finding to be resolved.high — Completion rule repeats the verification-check count
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41KQ42VEQ6TN8VHVXFBWXTPof review01M41KHRHF0D8BVKBP18YFCNQD@ -35,3 +35,3 @@## Fix direction and missing featuresFix docs to match code by default. Change code only for a confirmed **code-drift** where the doc is the intended source of truth. A third case hides inside "incorrect": the doc describes a capability that _should_ exist but doesn't (an endpoint, a flag). Removing the claim and _implementing_ the feature are both valid — surface the fork to the user, and if the claim is removed, flag the missing feature as separate work rather than silently dropping it. ADRs are decision records, not behaviour docs. A `proposed` ADR is an open question: correct its statement of current behaviour if the code contradicts it, never delete it as stale. An `accepted` ADR is the source of truth for the decision it records: code contradicting it is `code-drift`, and changing the decision means superseding the ADR per `project-docs`, never editing it to match the code.Fix docs to match code by default. Change code only for a confirmed **code-drift** where the doc is the intended source of truth. A third case hides inside "incorrect": the doc describes a capability that _should_ exist but doesn't (an endpoint, a flag). Removing the claim and _implementing_ the feature are both valid — surface the fork to the user, and if the claim is removed, flag the missing feature as separate work rather than silently dropping it. ADRs are decision records, not behaviour docs. A `proposed` ADR is an open question: correct its statement of current behaviour if the code contradicts it, never delete it as stale. An `accepted` or status-less ADR is the source of truth for the decision it records: code contradicting it is `code-drift`. Changing the decision is the user's call, after which the ADR is edited, replaced, or deleted per `project-docs`; never edit an ADR just to match the code.high — Drift-audit instructions copy the ADR maintenance actions
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41KQXQZFY6J5J09EF4P2GJMof review01M41KHRHF0D8BVKBP18YFCNQDhigh — Drift-audit instructions copy ADR status classes
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41KREHBVG8512KGVNCKZFPEof review01M41KHRHF0D8BVKBP18YFCNQDThe proposed removal assumes project-docs is available to this reader. At
71043340, verify-doc-drift has no metadata.axskills.requires and never calls project-docs. writing-for-agents (One Idea, One Place) explicitly permits short required material from undeclared skills that readers may not have; skill-packaging says delivery guarantees availability only for declared dependencies. The local maintenance summary supplies that portable guidance and explicitly leaves the decision with the user. The actions currently agree; no conflicting maintenance behavior is demonstrated. Deleting them without separately changing the dependency/loading contract is unsupported.At
71043340verify-doc-drift neither declares project-docs in metadata.axskills.requires nor invokes it. writing-for-agents explicitly permits short required material from undeclared skills that readers may not have; skill-packaging says catalog discovery may omit capabilities and delivery requires declared dependencies. The local proposed/accepted/statusless split supplies the audit-specific correction direction for those readers and matches the canonical contract. Replacing it with an unguaranteed lookup would lose that guidance. No present classification conflict is shown.superseded by review
01M41MPNRQQVAHPRDQJBK6VM0Qfor headbabf98cbbc3f37c673af24c448ccd89d9750191ffix(skills): keep only current ADRsto fix(skills): ADRs should reflect settled decisionsTracked in #104: completion refers to the verification checks defined above instead of copying their count. The one-line maintenance change is based on the current default branch and preserves the checks themselves. This source PR is not claimed fixed by the unmerged follow-up.
@ -58,3 +58,3 @@- **Use the glossary's canonical terms** in everything you produce — plans, code, commit messages. When the user's wording conflicts with a defined term, flag the mismatch instead of silently adopting either side.- **Don't re-litigate recorded ADRs.** A status-less ADR counts as accepted; only an ADR marked `proposed` is still open, and a `deprecated` or `superseded` one no longer binds — its successor, where one exists, governs instead. If the plan contradicts a binding ADR, name it ("this conflicts with ADR-0007") and either adjust the plan or supersede the ADR — never silently override a recorded decision.- **Don't re-litigate recorded ADRs.** An ADR marked `accepted`, or without a status, is decided and binding; `proposed` means the decision is still open. Other statuses, including `superseded` and `deprecated`, are outdated and do not bind: flag them and use the maintenance rules when that cleanup is authorized. If the plan contradicts a binding ADR, name it ("this conflicts with ADR-0007"), then either adjust the plan or, on the user's decision, change the ADR per the maintenance rules — never silently override a recorded decision.medium — Status-less binding ADRs are omitted from reengineering requirements
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41MW4TW2R1GN0PTQRB9AFKCof review01M41MPNRQQVAHPRDQJBK6VM0QFixed in
e1a7d3f05d. Reengineering completion, resumed authority, the generated future rule, designer and implementer briefs, and the replacement-review exception now use binding ADRs through the loaded project-docs definition. New Keep/Drop records and newly answered proposals still explicitly become status: accepted; no settled decision is reopened.@ -31,3 +31,3 @@Have a fresh-context sub-agent attack the result from both directions: find situations the old code handles that the rebuild omits without an accepted decision, and promises the rebuild makes that no accepted decision covers. Mechanism-only differences and replacements chosen by an accepted ADR are not findings.Put each uncovered situation to the user and record the answer in an added or superseding ADR before adding, removing, or keeping its promise. Completion requires the implementation to satisfy the confirmed design, all three checks to pass, and every review finding to be resolved.Put each uncovered situation to the user and record the answer in a new or edited ADR before adding, removing, or keeping its promise. Completion requires the implementation to satisfy the confirmed design, all three checks to pass, and every review finding to be resolved.high — Completion rule repeats the count of verification checks
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41MYBSN6VXTSCFDCRSHM0KQof review01M41MPNRQQVAHPRDQJBK6VM0Q@ -35,3 +35,3 @@## Fix direction and missing featuresFix docs to match code by default. Change code only for a confirmed **code-drift** where the doc is the intended source of truth. A third case hides inside "incorrect": the doc describes a capability that _should_ exist but doesn't (an endpoint, a flag). Removing the claim and _implementing_ the feature are both valid — surface the fork to the user, and if the claim is removed, flag the missing feature as separate work rather than silently dropping it. ADRs are decision records, not behaviour docs. A `proposed` ADR is an open question: correct its statement of current behaviour if the code contradicts it, never delete it as stale. An `accepted` ADR is the source of truth for the decision it records: code contradicting it is `code-drift`, and changing the decision means superseding the ADR per `project-docs`, never editing it to match the code.Fix docs to match code by default. Change code only for a confirmed **code-drift** where the doc is the intended source of truth. A third case hides inside "incorrect": the doc describes a capability that _should_ exist but doesn't (an endpoint, a flag). Removing the claim and _implementing_ the feature are both valid — surface the fork to the user, and if the claim is removed, flag the missing feature as separate work rather than silently dropping it. ADRs are decision records, not behaviour docs. A `proposed` ADR is an open question: correct its statement of current behaviour if the code contradicts it, never delete it as stale. An `accepted` or status-less ADR is the source of truth for the decision it records: code contradicting it is `code-drift`. Changing the decision is the user's call, after which the ADR is edited, replaced, or deleted per `project-docs`; never edit an ADR just to match the code.high — ADR maintenance actions are copied into verify-doc-drift
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41MZGA77DNVW75H3Y71PHA8of review01M41MPNRQQVAHPRDQJBK6VM0Qhigh — Verify-doc-drift copies ADR status members from project-docs
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41N046QS7TG2BES0A5REX7Cof review01M41MPNRQQVAHPRDQJBK6VM0QThe tree does contain the delivery boundary: verify-doc-drift has no metadata.axskills.requires and no Call the Skill tool with project-docs invocation. writing-for-agents, One Idea One Place, allows short required material from undeclared skills the reader may not have. Its skill-packaging reference states that catalog discovery may omit capabilities and only declared dependencies guarantee delivery. A textual per-project-docs reference does not establish that runtime availability. This portable local summary currently agrees with the source and keeps the user decision gate; simply removing it is not a supported fix.
The inaccessible-source counterevidence is the actual skill delivery contract: verify-doc-drift declares no project-docs dependency and never invokes it. writing-for-agents permits short required material from undeclared skills; its packaging reference says catalog discovery may omit a capability and declared dependencies guarantee delivery. Merely naming project-docs does not load or deliver it. This local split keeps the audit-specific correction direction available; no current contradictory classification is reproduced. Introducing a hard dependency would be a separate delivery-contract change, not evidence that this deletion is safe.
superseded by review
01M41NG4S8JHH19TW7JCMXNQCHfor heade1a7d3f05db3e0bf1345e7c84d8f175475c19447Tracked in #104, which already owns the same count-reference finding from #109916. The independent one-line change preserves every verification contract. It is not yet merged into this PR.
@ -57,3 +57,3 @@Replace proposed text with the accepted decision when answered. Delete proposed ADRs only when they duplicate another root; retain accepted negatives after their code disappears. Use the same format for design choices, implementation gaps, and review findings. ADRs plus git carry resume state; execution history belongs in commits.Accepted ADRs remain settled across sessions. Supersede one when a fact undermines its reason, a witness appears for a don't-care drop, or a deferred keep's owner answers. Proposed and status-less ADRs are the decision backlog.Binding ADRs remain settled across sessions. When a fact undermines one's reason or a witness appears for a don't-care drop, put it to the user; when the user or a deferred keep's owner answers, edit or replace the ADR per `project-docs`. Proposed ADRs are the decision backlog.high — Reengineering skill repeats ADR maintenance choices
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41NRXZQSZQYXFZ00MFN6TQJof review01M41NG4S8JHH19TW7JCMXNQCHsuperseded by review
01M41PW2V1NMN8WKZDND4XDBEBfor head8e30deffaacb6c045b09ace982a6db57d95bd269@ -32,2 +31,3 @@Have a fresh-context sub-agent attack the result from both directions: find situations the old code handles that the rebuild omits without an accepted decision, and promises the rebuild makes that no accepted decision covers. Mechanism-only differences and replacements chosen by a binding ADR are not findings.Put each uncovered situation to the user and record the answer in an added or superseding ADR before adding, removing, or keeping its promise. Completion requires the implementation to satisfy the confirmed design, all three checks to pass, and every review finding to be resolved.Put each uncovered situation to the user and record the answer in a new or edited ADR before adding, removing, or keeping its promise. Completion requires the implementation to satisfy the confirmed design, all three checks to pass, and every review finding to be resolved.high — Completion criterion restates the shared verification-check count
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41NQP4VEY4WS7PS45Q7TB66of review01M41NG4S8JHH19TW7JCMXNQCH@ -35,3 +35,3 @@## Fix direction and missing featuresFix docs to match code by default. Change code only for a confirmed **code-drift** where the doc is the intended source of truth. A third case hides inside "incorrect": the doc describes a capability that _should_ exist but doesn't (an endpoint, a flag). Removing the claim and _implementing_ the feature are both valid — surface the fork to the user, and if the claim is removed, flag the missing feature as separate work rather than silently dropping it. ADRs are decision records, not behaviour docs. A `proposed` ADR is an open question: correct its statement of current behaviour if the code contradicts it, never delete it as stale. An `accepted` ADR is the source of truth for the decision it records: code contradicting it is `code-drift`, and changing the decision means superseding the ADR per `project-docs`, never editing it to match the code.Fix docs to match code by default. Change code only for a confirmed **code-drift** where the doc is the intended source of truth. A third case hides inside "incorrect": the doc describes a capability that _should_ exist but doesn't (an endpoint, a flag). Removing the claim and _implementing_ the feature are both valid — surface the fork to the user, and if the claim is removed, flag the missing feature as separate work rather than silently dropping it. ADRs are decision records, not behaviour docs. A `proposed` ADR is an open question: correct its statement of current behaviour if the code contradicts it, never delete it as stale. An `accepted` or status-less ADR is the source of truth for the decision it records: code contradicting it is `code-drift`. Changing the decision is the user's call, after which the ADR is edited, replaced, or deleted per `project-docs`; never edit an ADR just to match the code.high — Doc-drift guidance repeats the ADR maintenance options
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41NR92A46Q6QQMWWJBGACPJof review01M41NG4S8JHH19TW7JCMXNQCHAt
1610808, verify-doc-drift declares no project-docs dependency and does not invoke it. The writing-for-agents portability rule permits short required material from undeclared skills that readers may not have; axskills guarantees delivery only for declared dependencies. A prose reference alone is not proof of loading or availability. This audit-specific mapping agrees with the canonical maintenance policy and preserves the user-authority boundary; no present contradiction was demonstrated. Removing it would leave the standalone audit reader without the repair choices. The existing source and packaging evidence therefore do not support this finding.superseded by review
01M41PW2V1NMN8WKZDND4XDBEBfor head8e30deffaacb6c045b09ace982a6db57d95bd269fix(skills): ADRs should reflect settled decisionsto fix(skills): record settled ADR decisionsThe medium claim
01M41NQ78J88Y5AJW0P67JW3CW(statusless drops at the subtraction/review gates, review01M41NG4S8JHH19TW7JCMXNQCH) is fixed in1610808ae9. Subtraction excludes removal/replacement settled by a binding ADR, and the review checks omissions and new promises against binding ADRs. The consumer audit also covers retained negative ADRs and generated repository rules. New choices still receivestatus: accepted; accepted design and accepted fallout retain their ordinary user-approval meaning.This reports that source fix only. The report's unadjudicated pointer claim and separate duplication suggestions still require their own disposition; the summary is not yet acknowledged as complete.
The unadjudicated medium claim
01M41NP1WF93J55D4Q7TJ885VG, 'Follow existing superseded ADR pointers to the governing decision', identified a removed loading guarantee. Defaulte7d02b52says an outdated ADR's successor governs instead. ADR2's verification gate applies to added or edited records, so it does not cover read-only planning throughimprove-codebase-architecture.8e30deffaarestores bounded direct-pointer reading inproject-docsand applies the current record's own status rules. Proposed records remain open, outdated records remain nonbinding, and cleanup still requires authorization. No historical chain or archive audit is added. This is the source repair; the report's unadjudicated bucket remains an incomplete service result until a fresh current-head cycle supplies complete evidence.The repeated completion count is tracked in #104. That independently based follow-up refers to the verification checks defined above; it has not merged into this PR.
The local verification procedure also adds program-specific obligations absent from the shared category list: kept-surface snapshots and surviving tests, and rejection or unrepresentability of dropped situations. Those details remain useful implementation instructions. Matching category labels alone do not establish that deleting this procedure preserves its requirements, so the follow-up retains those details.
@ -58,3 +58,3 @@- **Use the glossary's canonical terms** in everything you produce — plans, code, commit messages. When the user's wording conflicts with a defined term, flag the mismatch instead of silently adopting either side.- **Don't re-litigate recorded ADRs.** A status-less ADR counts as accepted; only an ADR marked `proposed` is still open, and a `deprecated` or `superseded` one no longer binds — its successor, where one exists, governs instead. If the plan contradicts a binding ADR, name it ("this conflicts with ADR-0007") and either adjust the plan or supersede the ADR — never silently override a recorded decision.- **Don't re-litigate recorded ADRs.** An ADR marked `accepted`, or without a status, is decided and binding; `proposed` means the decision is still open. Other statuses, including `superseded` and `deprecated`, are outdated and do not bind: flag them and use the maintenance rules when that cleanup is authorized. Read any current ADR an outdated record points to and apply these status rules. If the plan contradicts a binding ADR, name it ("this conflicts with ADR-0007"), then either adjust the plan or, on the user's decision, change the ADR per the maintenance rules — never silently override a recorded decision.medium — Unknown ADR statuses are incorrectly treated as obsolete
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41Q2FA8AXHGFEBYE4VJJYKTof review01M41PW2V1NMN8WKZDND4XDBEBThis asks for an additional status convention rather than demonstrating a defect in the agreed ADR contract. The canonical format defines proposed and accepted, explicitly makes statusless decisions binding, and requires other statuses to be flagged rather than silently treated as authority. The user settled that classification in this change. The finding names a hypothetical implemented convention but supplies no project or governing convention showing it applies here. Explicit user directions still override these defaults. Without a concrete incompatible convention, changing this classification would reopen the approved policy rather than repair its implementation.
superseded by review
01M41SFZWKA8GGYFCW0ZY7PGEBfor headbc0921e42bab9862a5108abda1377c10de421e99@ -58,2 +57,3 @@Replace proposed text with the accepted decision when answered. Delete proposed ADRs only when they duplicate another root; retain binding negative ADRs after their code disappears. Use the same format for design choices, implementation gaps, and review findings. ADRs plus git carry resume state; execution history belongs in commits.Accepted ADRs remain settled across sessions. Supersede one when a fact undermines its reason, a witness appears for a don't-care drop, or a deferred keep's owner answers. Proposed and status-less ADRs are the decision backlog.Binding ADRs remain settled across sessions. When a fact undermines one's reason or a witness appears for a don't-care drop, put it to the user; when the user or a deferred keep's owner answers, edit or replace the ADR per `project-docs`. Proposed ADRs are the decision backlog.medium — Existing status-less backlog ADRs become binding without a decision
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41Q6GRA0Z1MA2ZAZ981TQRWof review01M41PW2V1NMN8WKZDND4XDBEBThe old source at
e7d02b52required status frontmatter on every newly recorded ADR, created each unrecorded root as proposed before the first question, and parked unrelated promises as proposed. It did not generate new statusless backlog records. The old statusless interpretation conflicted with canonical project-docs; removing that exception and treating statusless ADRs as binding is the expressly settled change. Existing proposed records remain open. No actual unanswered statusless downstream ADR was supplied, so a blanket migration that re-interviews statusless decisions would reverse that choice based on an unverified legacy-data hypothesis. A named record with evidence of an unresolved decision would warrant scoped reconciliation; this finding provides none.superseded by review
01M41SFZWKA8GGYFCW0ZY7PGEBfor headbc0921e42bab9862a5108abda1377c10de421e99@ -32,2 +31,3 @@Have a fresh-context sub-agent attack the result from both directions: find situations the old code handles that the rebuild omits without a binding ADR, and promises the rebuild makes that no binding ADR covers. Mechanism-only differences and replacements chosen by a binding ADR are not findings.Put each uncovered situation to the user and record the answer in an added or superseding ADR before adding, removing, or keeping its promise. Completion requires the implementation to satisfy the confirmed design, all three checks to pass, and every review finding to be resolved.Put each uncovered situation to the user and record the answer in a new or edited ADR before adding, removing, or keeping its promise. Completion requires the implementation to satisfy the confirmed design, all three checks to pass, and every review finding to be resolved.high — Completion condition restates the shared verification checklist size
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41Q3PXT3NF16JAX08QTBMVFof review01M41PW2V1NMN8WKZDND4XDBEB@ -35,3 +35,3 @@## Fix direction and missing featuresFix docs to match code by default. Change code only for a confirmed **code-drift** where the doc is the intended source of truth. A third case hides inside "incorrect": the doc describes a capability that _should_ exist but doesn't (an endpoint, a flag). Removing the claim and _implementing_ the feature are both valid — surface the fork to the user, and if the claim is removed, flag the missing feature as separate work rather than silently dropping it. ADRs are decision records, not behaviour docs. A `proposed` ADR is an open question: correct its statement of current behaviour if the code contradicts it, never delete it as stale. An `accepted` ADR is the source of truth for the decision it records: code contradicting it is `code-drift`, and changing the decision means superseding the ADR per `project-docs`, never editing it to match the code.Fix docs to match code by default. Change code only for a confirmed **code-drift** where the doc is the intended source of truth. A third case hides inside "incorrect": the doc describes a capability that _should_ exist but doesn't (an endpoint, a flag). Removing the claim and _implementing_ the feature are both valid — surface the fork to the user, and if the claim is removed, flag the missing feature as separate work rather than silently dropping it. ADRs are decision records, not behaviour docs. A `proposed` ADR is an open question: correct its statement of current behaviour if the code contradicts it, never delete it as stale. An `accepted` or status-less ADR is the source of truth for the decision it records: code contradicting it is `code-drift`. Changing the decision is the user's call, after which the ADR is edited, replaced, or deleted per `project-docs`; never edit an ADR just to match the code.high — Doc drift guidance duplicates the ADR status set
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41Q4WAY5EARNZ1HW1KVX1QXof review01M41PW2V1NMN8WKZDND4XDBEBAt
8e30def, verify-doc-drift has no declared project-docs dependency and never invokes that skill. A prose per-project-docs reference does not establish delivery or loading. writing-for-agents explicitly permits short required material from undeclared skills that readers may not have, and axskills guarantees delivery only for declared dependencies. The local paragraph preserves the audit-specific open-versus-binding repair direction and agrees with the canonical meaning for each case it covers. No operative unknown/outdated ADR case or wrong audit outcome was reproduced. Deleting the local classification solely because status names recur would remove needed context from a standalone reader; the claimed no-exception premise is false.superseded by review
01M41SFZWKA8GGYFCW0ZY7PGEBfor headbc0921e42bab9862a5108abda1377c10de421e99The repeated completion count is tracked in #104. That independently based follow-up refers to the verification checks defined above; it has not merged into this PR.
The local verification procedure also adds program-specific obligations absent from the shared category list: kept-surface snapshots and surviving tests, and rejection or unrepresentability of dropped situations. Those details remain useful implementation instructions. Matching category labels alone do not establish that deleting this procedure preserves its requirements, so the follow-up retains those details.
Tracked in #105. That follow-up replaces copied maintenance options with references to the declared, loaded
project-docsrules while retaining the user-answer triggers. It is based on this PR's8e30deffaabecause those triggers differ from current main. Its unmerged source changes are not fixes in this PR.The loading/admission duplication claims
01M41NSPBCZ0RT5CJ631H1466Rand01M41NT9GH2SCY2K5Q8GPW3487are tracked in #106. The skill already declares and invokesproject-docs; the follow-up refers to its loading and admission procedures while retaining the interview trigger and timing. Its two-line change is independently based on main and is not yet merged into this PR.@ -58,3 +58,3 @@- **Use the glossary's canonical terms** in everything you produce — plans, code, commit messages. When the user's wording conflicts with a defined term, flag the mismatch instead of silently adopting either side.- **Don't re-litigate recorded ADRs.** A status-less ADR counts as accepted; only an ADR marked `proposed` is still open, and a `deprecated` or `superseded` one no longer binds — its successor, where one exists, governs instead. If the plan contradicts a binding ADR, name it ("this conflicts with ADR-0007") and either adjust the plan or supersede the ADR — never silently override a recorded decision.- **Don't re-litigate recorded ADRs.** An ADR marked `accepted`, or without a status, is decided and binding; `proposed` means the decision is still open. Other statuses, including `superseded` and `deprecated`, are outdated and do not bind: flag them and use the maintenance rules when that cleanup is authorized. Read any current ADR an outdated record points to and apply these status rules. If the plan contradicts a binding ADR, name it ("this conflicts with ADR-0007"), then either adjust the plan or, on the user's decision, change the ADR per the maintenance rules — never silently override a recorded decision.high — ADR loading rule repeats the complete status value set
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41SRZK1AA7QXAW0CH87CMZEof review01M41SFZWKA8GGYFCW0ZY7PGEBmedium — Statusless reengineering backlog becomes binding without migration
lens
general-bug· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41SN326AB5VY88DAFHFGAQ8of review01M41SFZWKA8GGYFCW0ZY7PGEBThe proposed mandatory migration contradicts the approved statusless-binding contract. The old source explicitly required unrecorded roots to be created as proposed and answered roots to become accepted; no unanswered statusless record is supplied here. Our bounded owned-record check found no such case and does not claim a complete historical census. A concrete operative backlog record would warrant investigation, but the earlier conflicting fallback alone does not establish one. The independent narrow-contract calibration also confirmed authority applies before any optional metadata edit.
@ -3,3 +3,3 @@Apply the shared reengineering skill's required design-abstractions reading before preparing the briefs.Have three fresh-context sub-agents independently design the scope. Give all three the loaded modeling guidance and `CONTEXT.md`, the boundary ADR, and accepted ADRs as the sole sources of requirements. For a narrower-than-program scope, include exact boundary signatures. Keep the repository outside their reading scope. Give each a different constraint:Have three fresh-context sub-agents independently design the scope. Give all three the loaded modeling guidance and `CONTEXT.md`, the boundary ADR, and binding ADRs as the sole sources of requirements. For a narrower-than-program scope, include exact boundary signatures. Keep the repository outside their reading scope. Give each a different constraint:high — Design brief count duplicates the constraint list
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41SPMTDFYW4XN25RCP5C0F1of review01M41SFZWKA8GGYFCW0ZY7PGEBThe opening sentence is the existing normative requirement for three independent designers, carried from main
e7d02b520e, followed by the named constraints assigned to those designers. This integration was explicitly required to preserve that design requirement; replacing it with an automatically variable agent count would change policy. The incidental repeated “all three” audience wording and completion-check count are owned by #104. That follow-up does not remove the normative opening count, and I am not claiming the broader allegation fully implemented.@ -34,2 +33,3 @@Have a fresh-context sub-agent attack the result from both directions: find situations the old code handles that the rebuild omits without a binding ADR, and promises the rebuild makes that no binding ADR covers. Mechanism-only differences and replacements chosen by a binding ADR are not findings.Put each uncovered situation to the user and record the answer in an added or superseding ADR before adding, removing, or keeping its promise. Completion requires the implementation to satisfy the confirmed design, all three checks to pass, and every review finding to be resolved.Put each uncovered situation to the user and record the answer in a new or edited ADR before adding, removing, or keeping its promise. Completion requires the implementation to satisfy the confirmed design, all three checks to pass, and every review finding to be resolved.high — Completion rule copies the number of verification checks
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41SQ0VYDZ9TZG3GVQ92RVYJof review01M41SFZWKA8GGYFCW0ZY7PGEB@ -35,3 +35,3 @@## Fix direction and missing featuresFix docs to match code by default. Change code only for a confirmed **code-drift** where the doc is the intended source of truth. A third case hides inside "incorrect": the doc describes a capability that _should_ exist but doesn't (an endpoint, a flag). Removing the claim and _implementing_ the feature are both valid — surface the fork to the user, and if the claim is removed, flag the missing feature as separate work rather than silently dropping it. ADRs are decision records, not behaviour docs. A `proposed` ADR is an open question: correct its statement of current behaviour if the code contradicts it, never delete it as stale. An `accepted` ADR is the source of truth for the decision it records: code contradicting it is `code-drift`, and changing the decision means superseding the ADR per `project-docs`, never editing it to match the code.Fix docs to match code by default. Change code only for a confirmed **code-drift** where the doc is the intended source of truth. A third case hides inside "incorrect": the doc describes a capability that _should_ exist but doesn't (an endpoint, a flag). Removing the claim and _implementing_ the feature are both valid — surface the fork to the user, and if the claim is removed, flag the missing feature as separate work rather than silently dropping it. ADRs are decision records, not behaviour docs. A `proposed` ADR is an open question: correct its statement of current behaviour if the code contradicts it, never delete it as stale. An `accepted` or status-less ADR is the source of truth for the decision it records: code contradicting it is `code-drift`. Changing the decision is the user's call, after which the ADR is edited, replaced, or deleted per `project-docs`; never edit an ADR just to match the code.high — verify-doc-drift copies the binding ADR status set
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41SNRHJN7GVSFZ4JS21YZ9Hof review01M41SFZWKA8GGYFCW0ZY7PGEBhigh — ADR drift rule repeats project-docs maintenance actions
lens
restated-sets· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41STGVHDAQ8A4Z39KBR3HR6of review01M41SFZWKA8GGYFCW0ZY7PGEBmedium — ADR maintenance refers to a skill that this audit never loads
lens
writing-quality· armdefault· tally 1 valid / 0 invalid / 0 uncertainclaim
01M41SR8B4BRF263JVRJ39D11Cof review01M41SFZWKA8GGYFCW0ZY7PGEBTracked in #104. That follow-up removes the copied count while preserving the implementation-specific verification methods. It will be integrated against main after this PR merges; it is not a fix already present in this head.
The same-file status-definition consolidation is owned by #107. It is prepared from default and will preserve the binding statusless/accepted and open proposed meanings when integrated after this PR. This parent retains the approved semantics; the unmerged follow-up is not claimed as fixed here.
The canonical dependency and status reference are owned together by #108. Its explicit dependency/invocation supplies project-docs before relying on the shared binding classification; it preserves audit-specific drift mapping. This parent is unchanged and the follow-up remains unmerged.
The maintenance-action reference is owned by #108 together with the missing canonical dependency/invocation. The repair retains the user decision gate and the prohibition on changing intent merely to match code. It is a separate unmerged follow-up.
Verified on default
e7d02b520eas well: verify-doc-drift names project-docs for ADR maintenance but declares no dependency and never invokes it. #108 owns the explicit dependency and point-of-use invocation plus coherent status/action references. This delivery gap is acknowledged as independently owned, not silently counted as fixed by this parent.