@erclx/aitk 0.77.1 → 0.78.1

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.77.1",
+  "version": "0.78.1",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/ai-workflow.md

@@ -81,6 +81,8 @@ Before a handoff, the orchestrator checks the plan against the tree rather than
 
 The plan's shape is fixed by `.claude/standards/plan.md`: the section list, the filename, the lifecycle, and the contract its questions keep. Every question carries a `- Suggested:` line and an empty `- Answer:` slot, and a blank answer accepts the suggestion at execution time. That default is what makes a plan decision-ready in one pass, and it is the opposite of the contract an intake folder keeps, where an empty slot means nobody reached the item.
 
+An execution that picks other than the suggestion rewrites the `- Suggested:` line as `overridden at execution to <pick>,` followed by the measurement that moved it, and leaves the slot blank. That fixed phrase is how a reader of the archived plan tells an override from a suggestion the execution accepted, since an authored suggestion often carries a number of its own. The same deviation takes one line in the open task's `## Findings`, which is the register that survives the plan being archived. A deviation from a question somebody already answered goes back to whoever answered it instead, since a filled slot is a decision already made.
+
 `aitk records validate plans` reports where a plan and that standard disagree: a filename that is not `feature-<slug>.md`, a missing required section, a files-to-touch entry naming no file, and a question carrying a suggestion with no answer slot. The same verb takes `groundwork`, `intake`, and `memory`, which are governed the same way and were unreachable for the same reason. Nothing fires it automatically, because all four folders are gitignored and every check the repository runs reads changed files from git. It reports and never writes, since the folders are per-machine scratch with no history to recover a wrong repair from.
 
 A plan that ships is archived, never deleted. `aitk:claude-docs` moves it to `.claude/plans-archive/` and retargets the task file's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. Both folders are gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.

package/governance/rules/claude/558-plan.md

@@ -11,6 +11,7 @@ paths:
 
 - Never fill an `- Answer:` slot on behalf of the person who owns it. A blank slot accepts the suggestion at execution time.
 - Never ship a question without a `- Suggested:` line. Write `- Suggested: needs your call, <why>` where the answer turns on preference.
+- Rewrite the `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement when execution deviates from an unanswered question, leaving the slot blank. Put the same deviation in one line under the open task's `## Findings`.
 
 ## Archiving
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.77.1",
+  "version": "0.78.1",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/snippets/claude/figma-steps.md

@@ -15,4 +15,10 @@ Cover in order:
 - Alignment and spacing rules
 - Export settings
 
-Use exact values from the spec. Do not restate design rationale. Use Title Case for all layer and frame names. Use Figma terminology throughout, not code or CSS equivalents. Reuse existing frames or components from the same Figma document by name instead of rebuilding from scratch.
+Throughout:
+
+- Use exact values from the spec
+- Do not restate design rationale
+- Use Title Case for all layer and frame names
+- Use Figma terminology throughout, not code or CSS equivalents
+- Reuse existing frames or components from the same Figma document by name instead of rebuilding from scratch

package/standards/architecture.md

@@ -32,8 +32,21 @@ Does not govern:
 
 Use `## Overview`, `## Key technical decisions` with one named H3 per decision, and `## Risks / open questions`. Name each decision and give the reasoning, especially for non-obvious choices. Skip entries where the rationale is self-evident.
 
+## Verification anchors
+
+A decision's reasoning stays correct while the numbers it cites move. The anchor records what a measured claim was read against, so a reader can tell a number that was checked and held from one nobody has looked at since.
+
+- Close a decision entry whose reasoning cites a measured number with a trailing sentence naming the short commit SHA and the ISO date that number was read: `Measured at <short-sha> on <YYYY-MM-DD>.`
+- Anchor on the number alone. A decision citing none takes no anchor whatever its reasoning rests on, because a marker over a claim nobody can re-measure is one no reader can falsify.
+- Anchor a decision when writing it or when amending its reasoning. Leave an entry written before the rule unanchored rather than dating it by blame, which is archaeology for a marker nothing reads back.
+- Read an absent anchor as unchecked rather than as current. On an entry citing no number there is nothing to check. On one citing a number the number is due a read.
+- Do not edit a claim in the pass that first anchors it. The anchor states what the claim was measured against, so changing both at once leaves nothing to check the anchor against.
+- Refresh the anchor whenever the number is re-read, whether or not it moved. A confirmed number and an unread one are the same text without the date.
+
 ## Template
 
+The anchor sentence closes a decision whose reasoning cites a measured number and is absent from one that cites none.
+
 ```markdown
 # Architecture
 
@@ -43,7 +56,7 @@ Use `## Overview`, `## Key technical decisions` with one named H3 per decision,
 
 ### Decision name
 
-Reasoning and tradeoffs.
+Reasoning and tradeoffs, carrying the measured number the choice rested on. Measured at <short-sha> on <YYYY-MM-DD>.
 
 ## Risks / open questions
 ```

package/standards/plan.md

@@ -86,20 +86,33 @@ Every question carries a `- Suggested:` line and an empty `- Answer:` slot below
    - Answer:
 ```
 
+An execution that deviates rewrites the suggestion into the form below, leaving the slot as it found it.
+
+```markdown
+1. <question>
+   - Suggested: overridden at execution to <pick>, <the measurement that moved it>
+   - Answer:
+```
+
 - A blank `- Answer:` means accept the suggestion at execution time. That default is what makes the plan decision-ready in one pass, with no separate round to collect answers.
 - Never ship a question without a suggestion. A bare question defers the judgment the plan exists to supply, and it arrives at the executing session as a stop.
 - State the pick in one line with its reason or its main tradeoff. List an alternative only where it changes the pick.
 - Write `- Suggested: needs your call, <why>` where the answer turns on preference rather than on a technical default. Fabricating a default there hides an open question behind an accepted answer.
 - Never fill an `- Answer:` slot on behalf of the person who owns it. Recording the pick as the suggestion is what the suggestion line is for.
+- Rewrite the `- Suggested:` line to the pick execution made when it deviates from an unanswered question, and leave the slot blank. The prohibition above reaches the answer line alone, so the suggestion line is where a deviation goes.
+- Open the rewritten text with `overridden at execution to <pick>,` and follow it with the measurement that moved the pick. The phrase is fixed, because a suggestion carrying a number is the ordinary shape of an authored one and says nothing about who wrote it.
+- Take a deviation from an answered question back to whoever answered it rather than rewriting either line. A filled slot is a decision already made, and a suggestion rewritten under one leaves the plan holding two picks with no default resolving them.
 - Answer in place when a question is settled in conversation, so the file and the decision do not disagree.
 
+The fixed phrase is what a later reader tells an override by, and the measurement alone is not, since an authored suggestion routinely carries a number of its own and a reader meeting one learns nothing about who put it there. The plan is archived at ship, so the same deviation takes one line in the open task's `## Findings` naming what shipped. That is one fact in two registers, the plan holding why the pick moved and the task holding what the tree now has, rather than two records to keep in step.
+
 This contract inverts the one an intake folder keeps, where an empty slot means unread and acceptance is typed out. A plan is written and read in one sitting with every question already surfaced, so silence is a usable default here and is not one there. Both files state the inversion, since a contract read on only one side of a boundary is the one that gets applied to the wrong document.
 
 ## Lifecycle
 
 - Write the plan before implementation starts, and treat it as the scope of the run that executes it.
 - Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
-- Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current.
+- Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current. An execution-time deviation from a suggestion is one such amendment, and the contract above fixes which line takes it.
 - Move the plan to `.claude/plans-archive/` when the work it describes ships. Never delete it, because the plan is where the rejected alternative is written down and nothing else records it.
 - Write the plan in the same session that opens the task it serves. The session executing it later inherits reasoning it would otherwise re-derive.
 
@@ -109,6 +122,7 @@ This contract inverts the one an intake folder keeps, where an empty slot means
 - **The bundled plan.** Two concerns under one slug cannot be split later without rewriting both halves.
 - **The question with no suggestion.** It reads as thoroughness and lands as a blocked run.
 - **The answer filled in by the author.** A slot holding the writer's own pick destroys the only signal that anyone else agreed.
+- **The deviation recorded off the plan.** The reasoning lands in a pull request description no later reader of the plan opens, and the archived plan reads as though its suggestion held.
 - **The count carried in.** A figure quoted from an earlier session survives the change that invalidated it, and the scope built on it is quietly wrong.
 - **The plan deleted on ship.** The considered-and-dropped reasoning goes with it, and the next session re-proposes what this one rejected.
 

package/standards/tasks.md

@@ -79,9 +79,9 @@ description: One line on what the board covers
 
 ## Needs a plan
 
-| Task                            | Waiting on                              |
-| ------------------------------- | --------------------------------------- |
-| [vXX.Y <slug>](vXX.Y-<slug>.md) | <the collision or the task it waits on> |
+| Task                            | Waiting on                                     |
+| ------------------------------- | ---------------------------------------------- |
+| [vXX.Y <slug>](vXX.Y-<slug>.md) | <what the task needs before it can be planned> |
 ```
 
 The tests live here so the board does not carry them. Writing them as a sentence under each heading produces the paragraph the rule above deletes, and a criterion with no home gets restated from memory every time the board is touched.
@@ -171,6 +171,7 @@ The line is what lets a merge close its own task. Every merge on `main` is a squ
 - Task entries describing observable behavior, one outcome per line
 - A test strategy line naming the mechanism and what it verifies
 - Findings stating what constrains the task, including blockers and dependencies
+- A deviation from the plan's suggestion, in one line naming what moved the pick. The plan is archived at ship and holds the reasoning, so this register carries what shipped.
 
 ## What does not go in