@erclx/aitk 3.12.0 → 3.13.0

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

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

package/claude/skills/claude-groundwork/REQUIREMENT.md

@@ -14,6 +14,7 @@ Two failure modes cost more than the rest. A track that fans out to subagents re
 ## Must
 
 - Detect open, resume, and close from the folder itself, matching the topic against tracks already there before deriving a slug
+- Name a newly opened folder with a two-digit ordinal ahead of the slug, taken from the highest one already present across groundwork and intake
 - Apply the qualifying test in open mode alone, so a track already measured is not refused by the test that admitted it
 - Measure the current state now rather than carrying a figure from a previous session
 - Carry a lean and the finding that would overturn it on every open question, or admit that a measurement is missing

package/claude/skills/claude-groundwork/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: claude-groundwork
-description: Opens and runs a numbered groundwork folder under `.claude/groundwork/<slug>/` for a topic that has to be measured before it can be planned. Detects open, resume, and close from the folder itself. Use when asked to "research X", "dig into X", "work out what we should do about X", "measure this before we commit", or "open a groundwork folder". Do NOT use to write a feature plan or to implement. That is `claude-feature`.
+description: Opens and runs a numbered groundwork folder under `.claude/groundwork/<nn>-<slug>/` for a topic that has to be measured before it can be planned. Detects open, resume, and close from the folder itself. Use when asked to "research X", "dig into X", "work out what we should do about X", "measure this before we commit", or "open a groundwork folder". Do NOT use to write a feature plan or to implement. That is `claude-feature`.
 ---
 
 # Claude groundwork
@@ -19,10 +19,10 @@ Read `${CLAUDE_SKILL_DIR}/../../standards/groundwork.md` before writing any file
 
 ## Write scope
 
-- Write only inside `.claude/groundwork/<slug>/`. A feature plan, source changes, a standard, a rule, and a reference doc all live outside that folder, so this one rule forbids every one of them.
+- Write only inside `.claude/groundwork/<nn>-<slug>/`. A feature plan, source changes, a standard, a rule, and a reference doc all live outside that folder, so this one rule forbids every one of them.
 - One exception, at close only: write one task file recording what the track concluded.
 - A second exception, for what a spike reads: write an input under `.claude/.tmp/groundwork-fixtures/<slug>/`. Keep it out of `.claude/groundwork/` so mode detection never matches a fixture as a track. A fixture a headless run is pointed at goes outside the repository instead, per the rule in `## Running a spike`.
-- What a spike produces stays inside the track rather than joining the two exceptions above: write evidence a spike file cites under `.claude/groundwork/<slug>/evidence/`, which the first rule already permits. Mode detection matches entries at the top level of the tracks directory, so the sibling the fixtures rule guards against cannot be a folder nested inside a track, and the scratch path holds only what can be deleted without loss, which a recording a finding rests on is not.
+- What a spike produces stays inside the track rather than joining the two exceptions above: write evidence a spike file cites under `.claude/groundwork/<nn>-<slug>/evidence/`, which the first rule already permits. Mode detection matches entries at the top level of the tracks directory, so the sibling the fixtures rule guards against cannot be a folder nested inside a track, and the scratch path holds only what can be deleted without loss, which a recording a finding rests on is not.
 - Reading is not restricted. External research is in scope, so read documentation, comparable projects, and papers whenever a live question needs them.
 - Every claim about a source outside the project carries a link to it. A source found and not read is listed as a lead and is never cited.
 - Treat the folder as gitignored and unbacked. It dies with the machine, so `07-next-session.md` repeats what it needs instead of pointing at its siblings.
@@ -41,11 +41,11 @@ Record method, result, measured cost, and caveats in `08-spikes.md`. Put whateve
 
 ## Step 1: detect the mode
 
-List `.claude/groundwork/` from the project root and match the topic against the tracks already there before deriving anything. A resume pass rarely phrases the topic the way the folder was named, so a fresh slug derived from the wording would miss a live track and restart it.
+List `.claude/groundwork/` from the project root and match the topic against the slug half of each `<nn>-<slug>` folder already there before deriving anything. A resume pass rarely phrases the topic the way the folder was named, so a fresh slug derived from the wording would miss a live track and restart it.
 
 Never match against `.claude/` itself. That directory holds every other workflow surface, so a topic matched there lands on a folder that was never a track.
 
-With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `ts-migration` over `migration-research`. Then route on `.claude/groundwork/<slug>/`:
+With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `ts-migration` over `migration-research`. Also list `.claude/intake/` and take `<nn>` as the highest ordinal present across both listings, incremented, per `${CLAUDE_SKILL_DIR}/../../standards/groundwork.md`. Then route on `.claude/groundwork/<nn>-<slug>/`:
 
 - Folder absent: open
 - Folder present without `06-decision.md`: resume
@@ -72,7 +72,7 @@ The standard sets the open question format and requires it inside a topic file a
 
 ## Open mode
 
-1. Create `.claude/groundwork/<slug>/`.
+1. Create `.claude/groundwork/<nn>-<slug>/`, with `<nn>` and `<slug>` as derived in Step 1.
 2. Write `README.md` first. Writing it first forces the question of what the track is for.
 3. Write `01-current-state.md` by measuring now. Never carry a figure from a previous session or from recall without re-measuring it. Measure only what an open question in the folder needs. A number with no question attached is how groundwork turns into the work.
 4. Write `00-scope.md` when the track is large enough to run away. Skip it on a small track.
@@ -103,12 +103,12 @@ Emit the full relative path from the project root for every file written or upda
 Open and resume:
 
 ```plaintext
-📂 Opened .claude/groundwork/<slug>/
+📂 Opened .claude/groundwork/<nn>-<slug>/
 
 **Written:**
 
-- `.claude/groundwork/<slug>/README.md`
-- `.claude/groundwork/<slug>/01-current-state.md`
+- `.claude/groundwork/<nn>-<slug>/README.md`
+- `.claude/groundwork/<nn>-<slug>/01-current-state.md`
 
 **Open questions:**
 
@@ -122,12 +122,12 @@ Use `📂 Resumed` in place of `📂 Opened` on a resume pass.
 Close:
 
 ```plaintext
-✅ Closed .claude/groundwork/<slug>/
+✅ Closed .claude/groundwork/<nn>-<slug>/
 
 **Written:**
 
-- `.claude/groundwork/<slug>/06-decision.md`
-- `.claude/groundwork/<slug>/07-next-session.md`
+- `.claude/groundwork/<nn>-<slug>/06-decision.md`
+- `.claude/groundwork/<nn>-<slug>/07-next-session.md`
 
 **Uncited external claims:** <count, or none>
 

package/claude/skills/claude-intake/REQUIREMENT.md

@@ -22,6 +22,7 @@ A session with no numbering convention re-decides the folder shape per dump, so
 - Close every item with a verdict, and pair every open question with a suggested pick
 - Treat an empty operator slot as unread rather than as agreement
 - Reserve the index number and carry the domain in every other filename, leaving the rest of the numbering as read order
+- Name a newly opened folder with a two-digit ordinal ahead of the slug, taken from the highest one already present across intake and groundwork
 - Keep answers on items alone, with the index pointing at them
 - Name the heading and the act beside every path the pass wrote
 - Confine writes to the intake folder

package/claude/skills/claude-intake/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: claude-intake
-description: Files a raw brain dump into a numbered intake folder under `.claude/intake/<slug>/`, one item per finding carrying a measured problem, a proposed fix, and a verdict. Use when asked to "file this dump", "triage my notes", "work through this list", "sort out this brain dump", or "run an intake pass". Do NOT use for one question that has to be measured before anyone can plan it. That is `claude-groundwork`.
+description: Files a raw brain dump into a numbered intake folder under `.claude/intake/<nn>-<slug>/`, one item per finding carrying a measured problem, a proposed fix, and a verdict. Use when asked to "file this dump", "triage my notes", "work through this list", "sort out this brain dump", or "run an intake pass". Do NOT use for one question that has to be measured before anyone can plan it. That is `claude-groundwork`.
 ---
 
 # Claude intake
@@ -29,7 +29,7 @@ Using the wrong one fails in two shapes. Intake on a question that needs measuri
 
 ## Write scope
 
-- Write only inside `.claude/intake/<slug>/`. A plan file, a task file, a source change, a standard, and a rule all live outside that folder, so this one rule forbids every one of them.
+- Write only inside `.claude/intake/<nn>-<slug>/`. A plan file, a task file, a source change, a standard, and a rule all live outside that folder, so this one rule forbids every one of them.
 - There is no exception. Promoting an item onto the board runs through `claude-tasks` after the operator has answered, which is a separate invocation.
 - Reading is unrestricted inside the project. Measuring is the work.
 - Treat the folder as gitignored and unbacked. No check reaches its contents, so every rule stated here holds only while a session reads it.
@@ -38,11 +38,11 @@ Nothing outside this body carries the write-scope floor, and no path-scoped rule
 
 ## Step 1: detect open or resume
 
-List `.claude/intake/` from the project root and match the topic against the folders already there before deriving a slug. A second pass over the same subject rarely phrases the topic the way the folder was named, so a fresh slug would open a duplicate beside a live folder.
+List `.claude/intake/` from the project root and match the topic against the slug half of each `<nn>-<slug>` folder already there before deriving a slug. A second pass over the same subject rarely phrases the topic the way the folder was named, so a fresh slug would open a duplicate beside a live folder.
 
 Never match against `.claude/` itself. That directory holds every other workflow surface, so a topic matched there lands on a folder that was never an intake.
 
-With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `toolkit-overview` over `august-triage`. An absent folder opens, and a present one resumes by appending items and revising verdicts the tree has moved under.
+With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `toolkit-overview` over `august-triage`. Also list `.claude/groundwork/` and take `<nn>` as the highest ordinal present across both listings, incremented, per `${CLAUDE_SKILL_DIR}/../../standards/intake.md`. An absent folder opens, and a present one resumes by appending items and revising verdicts the tree has moved under.
 
 ## Step 2: orient
 
@@ -90,12 +90,12 @@ Emit the full relative path from the project root for every file written, and na
 A file the pass only read gets no line, which is what keeps the block short.
 
 ```plaintext
-📂 Opened .claude/intake/<slug>/
+📂 Opened .claude/intake/<nn>-<slug>/
 
 **Filed:**
 
-- `.claude/intake/<slug>/05-coverage.md` gains items 6 to 8 under a new `## What the merge gate covers`
-- `.claude/intake/<slug>/00-overview.md` cluster rows and verdict counts updated
+- `.claude/intake/<nn>-<slug>/05-coverage.md` gains items 6 to 8 under a new `## What the merge gate covers`
+- `.claude/intake/<nn>-<slug>/00-overview.md` cluster rows and verdict counts updated
 
 **Routing:** <N> plan-ready, <N> groundwork candidates, <N> already settled
 

package/docs/agents/install-and-sync.md

@@ -16,6 +16,15 @@ is left alone regardless of its name, since that subfolder is project-authored
 by location. It also removes a stale `.claude/GOV.md`
 from the retired build. Use `aitk gov install` to add rules.
 
+When the target's install recorded a stack, `aitk gov sync` also reports a
+rule that stack lists and `.claude/rules/` does not hold, as a `missing` entry
+carrying no change. This is what makes a target whose recorded sync point
+postdates a rule joining its stack still see that rule: the report reads the
+target's current entitlement against its current tree rather than diffing
+from an anchor a later sync could advance past the rule's own commit. A
+target whose install predates the recorded chain falls back to the same
+band-inference `newRules` uses in `aitk sync --check`.
+
 There is no `aitk standards sync` and no `aitk standards install`. The corpus
 installs into no project, so the domain has nothing in a target to reconcile.
 `aitk standards <name>` prints one, resolving `standards/` at the working root
@@ -94,16 +103,23 @@ It also refuses a target whose working tree is dirty, so commit or stash first.
 and is safe to run at any time. Each file is classified as `stale` when it still
 matches what the toolkit installed, `customized` when the project edited it,
 `stranded` when it sits at a path the toolkit no longer installs to, `orphaned`
-when the project authored it, or `drifted` when no stamp covers it.
+when the project authored it, or `drifted` when no stamp covers it. Governance
+also reports `missing`, for a rule the target's recorded stack lists that its
+tree does not hold at all.
 
 Use `--json` for the machine-readable report and `--exit-code` to fail a CI job. Orphaned
-files are excluded from that exit code, since a project-authored rule never
-converges. Attribution reads `.claude/aitk/config.json`, which every install and
-sync writes.
-
-A target installed before stamping shipped has no such file, and neither does one
-stamped before the file moved into `.claude/aitk/`, which is read as absent
-rather than migrated. Both fall back to the toolkit's own git history.
+and missing files are both excluded from that exit code: a project-authored
+rule never converges, and a sync that added a missing one silently changes
+what the project is governed by, which stays a separate command an operator
+chooses to run. Attribution reads `.claude/aitk/config.json`, which every
+install and sync writes.
+
+A target installed before stamping shipped has no such file, and neither does
+that fallback do anything to migrate it. A target stamped before the file
+moved into `.claude/aitk/` still carries it at the retired
+`.claude/aitk.json`, and `aitk sync --check` reads that path when the current
+one is absent, reporting it rather than moving it. Only a target carrying
+neither path falls back to the toolkit's own git history.
 Installed content matching any
 version that history ever published proves the file is untouched, so it reports
 `stale` naming the commit it came from, and content matching no published
@@ -207,10 +223,10 @@ file and proposes relocating the lot.
 
 #### Rules the target never received
 
-`newRules` names a rule the toolkit authored after this target last synced
-governance. A sync refreshes the files a target already holds and adds none, so
-without this section a project's rule set freezes at its install date while every
-file it does hold reports as current. That is the report's most confident wrong
+`newRules` names a rule the target could receive and its tree does not hold. A
+sync refreshes the files a target already holds and adds none, so without this
+section a project's rule set freezes at its install date while every file it
+does hold reports as current. That is the report's most confident wrong
 answer, since a clean result reads as a target holding everything the toolkit
 publishes.
 
@@ -225,11 +241,22 @@ installs, nothing counts toward `--exit-code`, and a target can read the list an
 act on none of it. The value stops at an operator reading it, which is the same
 contract the skills list already sets.
 
-The measurement anchors on governance's own stamp rather than on the oldest
-anchor across domains, since rules are domain-scoped and a shared anchor would
-let a snippets sync move the revision rules are measured from. A target carrying
-no governance anchor reports nothing at all: it has no date to measure against,
-and diffing from the start of history would read the whole catalog as new.
+Since `aitk gov install` records the stack it resolved, a target carrying that
+record answers this by comparing its current entitlement against its current
+tree, with no anchor and no git diff involved. That is what lets the section
+name a rule that shipped before the target's last sync: the anchor a sync
+advances plays no part in the read, where an anchor-bound diff can never see a
+rule on the far side of a window a later sync moved past it. The per-file
+`missing` state `aitk gov sync` reports comes from the same comparison, so a
+rule the chain lists reaches both surfaces the same way.
+
+A target stamped before governance recorded a chain falls back to the older
+band-inference read below. The measurement there anchors on governance's own
+stamp rather than on the oldest anchor across domains, since rules are
+domain-scoped and a shared anchor would let a snippets sync move the revision
+rules are measured from. A target carrying no chain and no governance anchor
+reports nothing at all: it has no date to measure against, and diffing from the
+start of history would read the whole catalog as new.
 
 An anchor this toolkit cannot resolve reports nothing by the same route, and that
 one is not visible. A stamp naming a revision the running clone has never seen,
@@ -238,22 +265,22 @@ fails the read and yields an empty list rather than a stated absence. It looks
 identical to a target holding every rule the toolkit publishes. `newSkills`
 behaves the same way, and neither carries the `historyUnavailable` flag the
 per-domain scan uses to separate the two. Treat an empty section on a toolkit
-that is not a full clone as unmeasured rather than clean.
+that is not a full clone as unmeasured rather than clean. This gap does not
+reach the chain-based read above, since it consults no anchor at all.
 
-Entitlement is filtered, because a stack does not receive every rule. The base
-stack takes the `core` and `claude` folders whole and every other stack extends
-it with individually named rules, so an unfiltered list would tell a base
-consumer about rules it can never receive and train the reader to skip the
-section.
+In the fallback, entitlement is filtered, because a stack does not receive
+every rule. The base stack takes the `core` and `claude` folders whole and
+every other stack extends it with individually named rules, so an unfiltered
+list would tell a base consumer about rules it can never receive and train the
+reader to skip the section.
 
 The filter accepts a band on either of two grounds. A folder the base stack takes
 whole is entitled to every target, read from the stack file so a folder added to
 base later needs no code change. Every other band is read off the folders the
-target already carries, since `aitk gov install` records file hashes and never
-the stack it resolved, which leaves the installed tree as the only evidence of
-what a chain reached. One band can be reached by more than one stack, so the test
-over-reports inside a folder the target holds, which costs a line where
-under-reporting would cost the section its point.
+target already carries, which is the fallback's only evidence of what a target
+was entitled to before it recorded a chain. One band can be reached by more than
+one stack, so the test over-reports inside a folder the target holds, which
+costs a line where under-reporting would cost the section its point.
 
 A rule the target already holds is dropped by name. That is what keeps a rule the
 toolkit moved between band folders out of the list, since a rename reaches this

package/docs/agents/intake.md

@@ -9,6 +9,8 @@ description: Reading intake folder counts and items, the three read states an it
 
 `aitk intake list` reports the intake folders under `.claude/intake/`, or the items one folder holds. It reads and never writes, because an answer belongs to the operator and a verb that filled one would decide what the folder exists to ask.
 
+A folder carries a two-digit ordinal ahead of its slug, as in `21-toolkit-overview`, so a listing sorts by when each opened. A bare slug still resolves: passing `toolkit-overview` matches the one folder whose name is an ordinal ahead of it, and the folder's real name is what every command reports back.
+
 ```bash
 aitk intake list
 aitk intake list toolkit-overview --unread --json
@@ -58,7 +60,7 @@ One call writes one cluster. A call per selection is the alternative, and severa
 
 An item already carrying an answer refuses rather than being overwritten, and one filled item refuses the whole batch, so a partly applied write never lands. Drop the named item and send the rest.
 
-Exit codes: `0` every named item now carries its answer, `1` refused. The `reason` field carries `no-intake`, `no-folder`, `no-cluster`, `no-item`, `answered`, or `bad-input`.
+Exit codes: `0` every named item now carries its answer, `1` refused. The `reason` field carries `no-intake`, `no-folder`, `ambiguous-slug`, `no-cluster`, `no-item`, `answered`, or `bad-input`. A bare slug matching more than one ordinal-prefixed folder refuses as `ambiguous-slug` rather than `no-folder`, naming every match in `detail`.
 
 An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's `reason` rather than the exit when a skill consumes this, which matters most here because the verb writes.
 

package/docs/ai-workflow.md

@@ -44,8 +44,8 @@ One session works for most features. Prefer splitting across two sessions only w
 
 Work in Claude Code directly. It reads `CLAUDE.md` automatically and has full file access, no pasting needed.
 
-- When the input is a pile of findings rather than one feature, invoke `aitk:claude-intake` first. It files the dump into `.claude/intake/<slug>/`, one item per finding carrying a problem measured against the tree, a proposed fix, and a verdict, then names which items are plan-ready, which need measuring, and which are already settled.
-- When the current state is unmeasured and more than one approach is live, invoke `aitk:claude-groundwork` first. It opens a track folder under `.claude/groundwork/<slug>/` and ends in a decision, which may be to do nothing. Skip it when the approach is already settled.
+- When the input is a pile of findings rather than one feature, invoke `aitk:claude-intake` first. It files the dump into `.claude/intake/<nn>-<slug>/`, one item per finding carrying a problem measured against the tree, a proposed fix, and a verdict, then names which items are plan-ready, which need measuring, and which are already settled.
+- When the current state is unmeasured and more than one approach is live, invoke `aitk:claude-groundwork` first. It opens a track folder under `.claude/groundwork/<nn>-<slug>/` and ends in a decision, which may be to do nothing. Skip it when the approach is already settled.
 - Invoke `aitk:claude-feature` to scan for code-level conflicts and ambiguities, confirm approach before proceeding
 - Implement the feature, then Claude Code runs the commands defined in `CLAUDE.md`, fixes failures, and iterates until all pass
 - For UI changes, invoke `aitk:claude-ui-test` to generate and run Playwright e2e tests

package/docs/target-projects.md

@@ -124,7 +124,7 @@ The report opens by naming the binary running it. The installed version reads ag
 
 A `stale` file still matches what the toolkit installed, so the update is mechanical. A `customized` file carries local edits, so taking the upstream version is a decision and `aitk:claude-seed-sync` is the tool for it. A `stranded` file sits where an older toolkit installed it and the toolkit has since moved, which is what `aitk:migration-standards` handles.
 
-That attribution comes from `.claude/aitk/config.json`, a stamp every install and sync writes. Snippets and governance record a hash per installed file. Tooling records the stack chain it resolved instead, since its install runs no per-file walk to attribute.
+That attribution comes from `.claude/aitk/config.json`, a stamp every install and sync writes. A target stamped before that path shipped is read from the retired `.claude/aitk.json` instead, reported rather than migrated. Snippets and governance record a hash per installed file. Governance also records the stack `aitk gov install` was given, and tooling records the stack chain it resolved instead of any file hash, since its install runs no per-file walk to attribute.
 
 Each domain holds its own toolkit commit, so syncing governance today does not move the revision snippets measures against, and each domain reports the upstream commits touching its own source path. Running any sync stamps that domain, and the report names the ones still unstamped.
 
@@ -136,13 +136,15 @@ That third one matters most on an older project. Before it existed, a target hol
 
 #### Rules you never received
 
-A sync refreshes the files you already hold and adds none, so your rule set is frozen at the date you installed governance while every file in it reports as current. `newRules` names the rules the toolkit has authored since then, which is the one section that reads your absence rather than your contents.
+A sync refreshes the files you already hold and adds none, so your rule set is frozen at the date you installed governance while every file in it reports as current. `newRules` names a rule you could receive that your tree does not hold, which is the one section that reads your absence rather than your contents. `aitk gov sync` reports the same rules per file, marked `missing`, so you see them either way you check.
 
 Take a clean section as reporting rather than as delivering. Nothing here installs, and it counts toward nothing, so pick the rules up with `aitk gov install <stack>` or take one with `--add <rule>`. That separation is deliberate: adopting a rule changes what your project is governed by, which is a choice a sync has no business making for you.
 
-The list is filtered to what your stack can receive, read off the rule folders you already carry plus the folders the base stack takes whole. A rule under `lang/` or `ui/` belongs to some stacks and not others, so an unfiltered list would name rules you can never install. A target that has never stamped governance reports nothing at all, since there is no date to measure against.
+Since `aitk gov install` records the stack you gave it, the list is read by comparing that stack's current rules against what you hold right now, with no date involved at all. That is what lets it name a rule the toolkit shipped before you last synced: nothing here depends on when you installed. A target stamped before this recording shipped falls back to the older read below.
 
-An empty section is not proof either way when the toolkit running the check is not a full git clone. The read needs history to reach your anchor, and an install from the registry ships none, so the section goes quiet rather than saying it could not measure. Run the check from a clone before reading a clean result as a complete one.
+The fallback filters to what your stack can receive, read off the rule folders you already carry plus the folders the base stack takes whole. A rule under `lang/` or `ui/` belongs to some stacks and not others, so an unfiltered list would name rules you can never install. A target with neither a recorded stack nor a governance anchor reports nothing at all, since there is no date to measure against either.
+
+In the fallback, an empty section is not proof either way when the toolkit running the check is not a full git clone. The read needs history to reach your anchor, and an install from the registry ships none, so the section goes quiet rather than saying it could not measure. Run the check from a clone before reading a clean result as a complete one. The stack-based read above is untouched by this, since it consults no history.
 
 This also closes the case where a rule arrives citing a sibling you do not have. A sync refreshing a rule can land a version pointing at a file it never installs, and the section names the missing sibling rather than the broken citation, which is enough to act on.
 
@@ -177,7 +179,7 @@ Standards take no part in that run. Nothing installed them, so there is no copy
 ### Targeted
 
 - Claude seed docs such as `CLAUDE.md` and `.claude/REQUIREMENTS.md`: invoke `aitk:claude-seed-sync`. The skill splits each file into a preamble (between the H1 and the first H2) plus one part per `##` section, then diffs part by part and proposes per-part edits. User customizations are preserved.
-- Governance rules already installed: `aitk gov sync <path>` diffs and applies, and never adds new rules
+- Governance rules already installed: `aitk gov sync <path>` diffs and applies, and never adds new rules. A rule your recorded stack lists reports as `missing` instead.
 - Tooling configs and seeds: `aitk tooling <stack> <path>` overwrites golden configs and merges seeds
 - Reference docs for a stack: `aitk tooling ref <stack> <path>`
 - Index regeneration after markdown edits: `aitk indexes regen`

package/governance/rules/claude/556-groundwork.md

@@ -1,11 +1,15 @@
 ---
-description: Route .claude/groundwork/ edits to the groundwork standard for numbering, frontmatter, and required file contents
+description: Route .claude/groundwork/ edits to the groundwork standard for ordinal naming, numbering, frontmatter, and required file contents
 paths:
   - '.claude/groundwork/**'
 ---
 
 # Groundwork standards
 
+## Folder name
+
+- Name a new track `.claude/groundwork/<nn>-<slug>/`, a two-digit zero-padded ordinal followed by a kebab-case slug. Take the ordinal from the highest one already present across both `.claude/groundwork/` and `.claude/intake/`, incremented, or `01` when neither folder holds an entry. Never renumber an existing folder.
+
 ## Measuring and closing
 
 - Never carry a figure from an earlier session without re-measuring it. Mark an inference as an inference.

package/governance/rules/claude/557-intake.md

@@ -1,11 +1,15 @@
 ---
-description: Route .claude/intake/ edits to the intake standard for the item format, the answer contract, and numbering
+description: Route .claude/intake/ edits to the intake standard for the item format, the answer contract, and ordinal naming
 paths:
   - '.claude/intake/**'
 ---
 
 # Intake standards
 
+## Folder name
+
+- Name a new dump `.claude/intake/<nn>-<slug>/`, a two-digit zero-padded ordinal followed by a kebab-case slug. Take the ordinal from the highest one already present across both `.claude/intake/` and `.claude/groundwork/`, incremented, or `01` when neither folder holds an entry. Never renumber an existing folder.
+
 ## The answer contract
 
 - Never fill a `You:` slot and never infer a disposition from an empty one. Empty means unread, never agreement.

package/governance/rules/lang/120-bash.md

@@ -0,0 +1,18 @@
+---
+description: Route bash script authoring to the interactive or non-interactive skill, and name the lint gate
+paths:
+  - '**/*.sh'
+---
+
+# Bash standards
+
+## Skill routing
+
+- Use `bash-script` for an interactive or human-facing script: prompts, a visual timeline UI, framed terminal output.
+- Use `cli-script` for a non-interactive script: automation, CI, cron, a pipeline helper, or anything run by an agent rather than watched by a person.
+- Load the matched skill's own reference templates rather than hand-rolling interactivity or logging patterns outside them.
+
+## Lint gate
+
+- Format with `shfmt --write --indent 2` and lint with `shellcheck --severity=warning` before committing a script.
+- Fix a shellcheck finding at the source. Suppress one with a directive comment only for a genuine false positive, and state why beside the suppression.

package/governance/rules/lib/305-e2e-reliability.md

@@ -0,0 +1,34 @@
+---
+description: Enforce settled waits and falsifiable guards in end-to-end tests
+paths:
+  - 'e2e/*.ts'
+  - 'e2e/**/*.ts'
+---
+
+# End-to-end reliability standards
+
+## Waiting
+
+- Settle on the condition a step waits for. Use `expect.poll` or a web-first assertion ahead of any read.
+- Reserve a fixed duration for an assertion that nothing happened across a window.
+- Bound every settle with an explicit timeout.
+- Do not raise a timeout to clear a failure that reproduces under load. Replace the wait with a settle.
+- Do not read a value once after a pause. Poll it.
+
+## Falsifiable guards
+
+- Assert the set under test is non-empty before asserting a property over its members.
+- Raise from an instrument that was refused rather than returning a value a passing assertion accepts.
+- Run a new guard against the defect it was written for, and see it fail, before trusting it.
+- Do not weaken an assertion to clear a failure. Narrow the wait instead.
+
+## Reproducing a failure that only appears in CI
+
+- Reproduce under `Emulation.setCPUThrottlingRate` rather than by rerunning the gate.
+- Read the state the assertion does not: which markers were set, which listeners fired, how far a transition ran.
+- Vary the condition under suspicion deliberately. Do not compare counts across runs that differed in something uncontrolled.
+- Read the check conclusion as its own act. A green diff review reports nothing about the gate.
+
+## Authority
+
+- Follow `.claude/rules/lib/300-testing-ts.md` for framework choice, file placement, and test naming.

package/governance/rules/lib/306-test-scope.md

@@ -0,0 +1,25 @@
+---
+description: Enforce which specs and which engines an end-to-end run covers at each point in the loop
+paths:
+  - 'e2e/*.ts'
+  - 'e2e/**/*.ts'
+---
+
+# Test scope standards
+
+## Selecting a run
+
+- Narrow an end-to-end run by spec path or by test name. Never narrow it by engine.
+- Run one named test while iterating on a behavior: `bun run test:e2e -- -g '<name>'`.
+- Run one surface while iterating on that surface: `bun run test:e2e -- e2e/<area>.spec.ts`.
+- Run `bun run test:e2e:changed` to select specs from the import graph.
+- Run the whole suite before pushing.
+- Pass `--project` in a local run only to reproduce a failure that engine has already reported. The CI matrix passes it on every job, one engine per leg, which is the gate rather than a narrowed run.
+- Do not add a script that pins a default run to one engine.
+
+## Instruments
+
+- Answer a question about the running page with a script against the dev server rather than with the suite.
+- Do not enable `fullyParallel` in `playwright.config.ts`.
+- Follow `.claude/rules/ui/440-surface-capture.md` for capture scope.
+- Follow `.claude/rules/lib/305-e2e-reliability.md` for waits and guards.

package/governance/rules/lib/350-security-web.md

@@ -4,6 +4,7 @@ paths:
   - '**/*.tsx'
   - '**/*.jsx'
   - '**/*.html'
+  - '**/*.astro'
 ---
 
 # Web security standards

package/governance/rules/ui/450-link-behavior.md

@@ -0,0 +1,19 @@
+---
+description: Enforce the same-tab default for an outbound link and for a mail link
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.astro'
+  - '**/*.html'
+---
+
+# Link behavior standards
+
+## Default target
+
+- Open a link in the same tab. Reserve `target="_blank"` for a destination that would discard in-progress work if it replaced the current page, such as a document a user is midway through elsewhere.
+- Do not add `target="_blank"` as a default for every external link.
+
+## mailto: links
+
+- Open a `mailto:` link in the same tab. It hands off to the mail client rather than replacing page content, so a new tab leaves an empty tab behind.

package/governance/stacks/astro.toml

@@ -1,2 +1,2 @@
 extends = "node"
-rules = ["210-astro", "350-security-web", "400-ui", "410-a11y", "430-ux-completeness", "440-surface-capture"]
+rules = ["210-astro", "350-security-web", "400-ui", "410-a11y", "430-ux-completeness", "440-surface-capture", "450-link-behavior"]

package/governance/stacks/base.toml

@@ -1,4 +1,4 @@
 extends = ""
 # Both folders whole. Every rule authored under them ships to a base consumer,
 # so adding one is a single edit rather than a file and a name here.
-rules = ["core", "claude"]
+rules = ["core", "claude", "120-bash"]

package/governance/stacks/react.toml

@@ -1,2 +1,2 @@
 extends = "node"
-rules = ["200-react", "230-nextjs", "250-tailwind", "300-testing-ts", "310-zod", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture"]
+rules = ["200-react", "230-nextjs", "250-tailwind", "300-testing-ts", "305-e2e-reliability", "306-test-scope", "310-zod", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior"]

package/package.json

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

package/src/commands/gov.ts

@@ -35,6 +35,7 @@ import {
   type TestOrderReport,
 } from '@/gov/test-order'
 import { recordStamp, runDomainSync } from '@/sync/engine'
+import { writeChainStamp } from '@/sync/stamp'
 import { resolveTarget } from '@/target'
 import {
   intro,
@@ -757,7 +758,15 @@ async function runInstall(
 
   logStep('Installing rules')
   for (const rel of await installRules(found, resolved)) logAdd(rel)
-  await recordStamp(createGovAdapter(PROJECT_ROOT), resolved, new Date())
+
+  const now = new Date()
+  await recordStamp(createGovAdapter(PROJECT_ROOT), resolved, now)
+  await writeChainStamp(
+    resolved,
+    { domain: 'governance', toolkitRoot: PROJECT_ROOT },
+    [selected],
+    now,
+  )
 
   const { GREEN, NC } = palette(process.stderr)
   outro()

package/src/commands/sync.ts

@@ -99,6 +99,12 @@ function renderCheck(report: CheckReport): void {
 
   renderSkew(report)
 
+  if (report.stampAtLegacyPath) {
+    logWarn(
+      'Stamp found at the retired .claude/aitk.json. Move it to .claude/aitk/config.json.',
+    )
+  }
+
   if (!report.managed) {
     logStep('Not a toolkit project')
     logWarn('No .claude/ directory and no CLAUDE.md at the target.')
@@ -124,13 +130,20 @@ function renderCheck(report: CheckReport): void {
 
     for (const entry of domain.entries) {
       if (entry.state === 'matching' || entry.state === 'orphaned') continue
-      logWarn(`${entry.rel} (${entry.state})`)
+      logWarn(entry.notice ?? `${entry.rel} (${entry.state})`)
     }
 
-    const { stale, customized, drifted, stranded, orphaned } = domain.counts
+    const { stale, customized, drifted, stranded, orphaned, missing } =
+      domain.counts
     if (stale + customized + drifted + stranded === 0) {
       logInfo(orphaned === 0 ? 'up to date' : `up to date (${orphaned} local)`)
     }
+    // A local file is not a deficiency and a missing rule is, so this never
+    // shares the up-to-date line's parenthetical. It prints on its own,
+    // regardless of whether anything above needs a sync.
+    if (missing > 0) {
+      logWarn(`${missing} listed by the stack, not installed`)
+    }
 
     for (const commit of domain.upstream) {
       logInfo(`${commit.sha} ${commit.subject}`)
@@ -168,10 +181,10 @@ function renderCheck(report: CheckReport): void {
   if (report.newRules.length > 0) {
     logStep('New rules, never installed')
     for (const name of report.newRules) logWarn(name)
-    // Names the stack as the reader's to supply, since no target records one
-    // and `--add` layers onto a resolved stack rather than standing in for it.
+    // `install` re-resolves the whole stack rather than adding one rule, so
+    // the remedy names both routes rather than assuming the reader wants all.
     logInfo(
-      'Run `aitk gov install <stack>`, naming the stack yourself since no target records it. Add `--add <rule>` to take one.',
+      'Run `aitk gov install <stack>` to take the whole stack again, or `--add <rule>` to take one.',
     )
   }