@erclx/aitk 0.73.0 → 0.75.0

package/README.md

@@ -62,7 +62,7 @@ Two limits worth knowing before you install. Claude Code is the only agent runti
 Each domain has a canonical source in this repo and a thin install or sync CLI on your side. The links run to internal narrative, written for someone maintaining the toolkit rather than installing it, so skip them on a first pass.
 
 - [Claude Code plugin](.claude/context/claude-plugin/index.md): skills for planning, review, docs sync, and the git ship chain
-- [Governance rules](.claude/context/governance.md): Cursor rules and stacks, installable per project
+- [Governance rules](.claude/context/governance/index.md): Claude rules and stacks, installable per project
 - [Standards](.claude/context/standards/index.md): shared authoring conventions, synced to projects
 - [Snippets](.claude/context/snippets.md): reusable prompts for Claude and Gemini chat
 - [Tooling stacks](.claude/context/tooling.md): golden configs, seeds, and references per framework

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

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

package/claude/skills/migration-superseded/REQUIREMENT.md

@@ -0,0 +1,45 @@
+---
+name: migration-superseded
+description: Why a retired file's split ships as a proposal read from the destination standard, and why detection stops rather than falling back to a listing
+---
+
+# Migration superseded requirement
+
+## Gap
+
+Without this skill, a target holding a retired `.claude/` file is told what replaced it and nothing else. The drift report names both halves and no command touches either, so the user hand-splits one file into a folder answering to a standard they have not read. The destination files land with frontmatter fields missing and filenames that sort out of order, which is the step the toolkit exists to remove.
+
+A second failure comes from the ordering nobody gets right unaided. A retired file committed before its ignore entry was written is tracked and ignored at once, and removing the entry first leaves the file tracked with nothing naming it. No report catches that state, so the mistake is discovered by whoever next wonders why a gitignored path keeps appearing in diffs.
+
+Two more follow from where a session looks when the report is thin. An uppercase stem under `.claude/` is not the test for a superseded file, so a session substituting a folder listing reaches `ARCHITECTURE.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and `DESIGN.md`, each a single file the layout intends to stay one, and proposes shredding four documents. A session falling back to the plugin's own copy of the destination standard proposes a shape the project never adopted, against content only the user can place.
+
+The last is the two-speed release skew arriving as a confident wrong answer. `superseded` reached a release in `0.46.0`, and an older CLI exits zero with a well-formed report that never mentions the field. A session reading that absent key as an empty array reports a clean layout to exactly the population holding the retired files.
+
+## Must
+
+- Take detection from the report's `superseded` array alone, and stop when the key is absent rather than treating it as empty
+- Resolve the governing standard by matching the replacement folder against the `appliesTo` the standards catalog declares, so a seed folder added later resolves without an edit to the body
+- Read the destination shape from the project's own installed standard, and propose nothing for a folder whose standard is absent or unshipped
+- Separate a folder no standard governs from one whose governing standard could not be read, since the catalog derives `appliesTo` from prose and answers an unparsed scope statement with an empty array
+- Name the untrack command ahead of the ignore entry whenever a retired file is both tracked and ignored, and say when the check could not run
+- Report what the destination standard leaves open, such as a phase label the retired file never recorded, rather than supplying a value for it
+- Report the measured empty case as a pass, since the guard is what proves the section ran
+
+## Must not
+
+- Write, move, or delete the retired file or its replacement, or create the destination folder
+- Run `git rm --cached` or edit the file carrying the ignore entry
+- Substitute a folder listing for the `superseded` array
+- Read the plugin's own copy of the destination standard when the target lacks that file
+
+## Guards
+
+- A directory with no `.claude/` stops, since nothing there was superseded and the report's sections would not be measured
+
+## Out of scope
+
+- Relocating root `standards/` and `snippets/` into `.claude/`: `migration-standards`
+- Classifying `CLAUDE.md` sections into the three-tier model: `migration-claude-md`
+- Relocating `docs/` files by audience: `migration-context`
+- Reconciling a seed file against its source section by section, which diffs two files rather than splitting one into a folder: `claude-seed-sync`
+- Applying the split and running the untrack, which the user does after reviewing

package/claude/skills/migration-superseded/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: migration-superseded
+description: Proposes how to split a retired `.claude/` file into the folder that replaced it, reading the destination shape from the standard that folder answers to. Use when asked to "split TASKS.md", "my .claude/DIAGRAMS.md was replaced by a folder", "migrate the superseded file", or after a drift report names a superseded artifact. Do NOT write to the retired file or to its replacement, and do NOT run the untrack command. Proposal only.
+---
+
+# Migration superseded
+
+## Guards
+
+- If `.claude/` does not exist at `pwd`, stop: `❌ No .claude/ directory. Nothing here was superseded.`
+
+The guard is also what makes the report's `superseded` section measured. Every section is gated on the target being toolkit-managed, and a `.claude/` directory satisfies that gate, so the empty case below is a measured empty rather than a section that never ran.
+
+## Step 1: read the report
+
+Run `aitk sync --check . --json` from the project root. Its `superseded` array is the detection. Each entry carries `rel`, the retired file, and `replacedBy`, the folder that took its job.
+
+An empty array is the pass: `✅ No superseded artifact. Every .claude/ file the seeds replaced is already a folder.`
+
+### When the report is unavailable
+
+Stop on any of three conditions, naming which one fired:
+
+- `aitk` is not on `PATH`: `❌ aitk is not on PATH. The superseded section is the only detection this skill has.`
+- The command exits non-zero: `❌ aitk sync --check failed. Fix the report before proposing a split.`
+- The report parses and carries no `superseded` key at all: `❌ This aitk predates the superseded field, which reached a release in 0.46.0. Upgrade, then re-run.`
+
+Test for the key rather than for emptiness. A current CLI reporting `"superseded": []` has looked and found nothing, which is the pass above, and reading an absent key as an empty answer reports a clean layout to the projects this skill exists for.
+
+No listing substitutes for the field. The pairing runs against the seed folder names the toolkit ships, and an uppercase stem is not the test, so a listing of `.claude/*.md` also reaches `ARCHITECTURE.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and `DESIGN.md`. Each of those is a single file the layout intends to stay one. A fallback that proposed splitting them would shred four documents to avoid reporting a stale CLI, which is why this skill stops where its siblings degrade.
+
+## Step 2: resolve the destination standard
+
+### Match the folder against the catalog
+
+Run `aitk standards list --json` and match each entry's `replacedBy` against the `appliesTo` array the catalog declares. Resolve from the catalog rather than from the folder stem, so a seed folder the toolkit adds later resolves without an edit here.
+
+Compare on the folder rather than on the exact string. An `appliesTo` value matches when it equals `replacedBy` or begins with `replacedBy` followed by a slash. The report spells the folder `.claude/tasks` and the catalog spells it `.claude/tasks/`, and `memory` declares a filename pattern beneath its folder rather than the folder itself, so string equality matches nothing the catalog actually carries and sends every entry to a decline below.
+
+### Search both standards roots
+
+A match resolves to that standard's `name`. Then look for that standard in the target, reading `.claude/standards/<name>.md` first and `standards/<name>.md` when the first is absent. The catalog says which standard governs the folder and only the target says whether the project holds it.
+
+Search both roots in that order, which is the order the toolkit's own standards resolution already uses. A project that has not relocated its standards keeps them at the root, and testing the installed path alone hands exactly that target a refusal plus a command that installs a second copy beside the one it already holds.
+
+A standard found at the root rather than under `.claude/` is read the same way and produces a full proposal. Say where it was read from and name `migration-standards` as the skill that relocates it, since the split is answerable either way and the layout is a note beside the proposal rather than a reason to refuse.
+
+### The states that end an entry
+
+Four states end an entry with no proposal. Name whichever one fired rather than collapsing them, because two of them are unmeasured and two are answers:
+
+- The catalog carries no `appliesTo` key: `⚠️ This aitk emits no appliesTo, so which standard governs <replacedBy> is unread.`
+- No value covers `replacedBy` and some entry carries an empty `appliesTo`: an empty array is a scope statement that did not parse, so a no-match verdict is unread rather than negative. Name the standards that did not parse.
+- No value covers `replacedBy` and every array is populated: `⚠️ The toolkit ships no standard for <replacedBy>. Nothing states the destination shape.` Installing cannot fix it, so name no command.
+- The standard resolved and neither root holds it: name it, then name `aitk standards install --only <name> .` as the command that lands it.
+
+Do not read the toolkit's own copy through `${CLAUDE_SKILL_DIR}` when the target lacks the file. Sibling skills cite that fallback for a standard they follow themselves, and this one is different: the standard here is the project's agreement about the shape of its own folder. A proposal drawn from the plugin copy hands back a shape the project never adopted, against content only the user can place.
+
+## Step 3: read the shape and map the file onto it
+
+Read the resolved standard and take four things from it: the filename convention, the required frontmatter, the required sections, and anything the folder holds that is not an item, such as a generated `index.md` no proposal may claim.
+
+Then read the retired file and split it at the boundary the standard implies, one destination file per item. Propose a filename per item from the convention, and name the frontmatter and sections each destination file owes.
+
+Report what the standard leaves open rather than inventing a value for it. A convention carrying a field the retired file never recorded, such as a phase label or a verified SHA, is the user's to supply, and a proposal that fills one in reads as a decision the split already made.
+
+## Step 4: check the ignore ordering
+
+Run both against each `rel`, in parallel:
+
+- `git ls-files --error-unmatch <rel> 2>/dev/null`: whether the file is tracked
+- `git check-ignore -v --no-index <rel> 2>/dev/null`: whether it is ignored, and which file and line names it
+
+`--no-index` is what makes the second read answer the question. `git check-ignore` consults the index by default and reports a tracked path as not ignored, so the flagless form returns nothing in exactly the tracked-while-ignored state this step exists to find, and the run reads a clean result off the one case that is not clean.
+
+A file that is both tracked and ignored carries an ignore entry added after the commit. Take it out of the index first, then remove the entry `check-ignore` named:
+
+```bash
+git rm --cached <rel>
+```
+
+Reversing the two leaves the file tracked with nothing naming it, and no report catches that state. Name both steps in that order and run neither. `git rm --cached` writes the index, which is a change to the project's own history even though no content moves.
+
+When `pwd` is not a git work tree, say the tracked check did not run rather than reporting the ordering as clear.
+
+## Step 5: output
+
+Print one block per superseded entry, then the shared reminder. Omit empty groups.
+
+```markdown
+## Split
+
+`.claude/TASKS.md` → `.claude/tasks/`, shaped by `.claude/standards/tasks.md`
+
+## Proposed files
+
+- `.claude/tasks/vXX.Y-<slug>.md` ← the "<heading>" section
+- `.claude/tasks/vXX.Y-<slug>.md` ← the "<heading>" section
+
+Each carries `title` and `description` frontmatter, an `## Outcomes` heading, and a `## Findings` heading.
+
+## You supply
+
+- The phase label on each filename. The retired file records no version.
+
+## Untrack before editing the ignore entry
+
+git rm --cached .claude/TASKS.md
+
+Then remove the `.claude/TASKS.md` line from `.gitignore:12`.
+
+## Reminder
+
+Nothing above was written or run. The retired file holds content the project authored, so the split is yours to apply and the destination folder shape is what this proposal supplies.
+```
+
+Do not create the destination folder. Do not write, move, or delete the retired file. Do not run `git rm --cached`. The user applies the split after reviewing it.

package/claude/skills/toolkit-operator/SKILL.md

@@ -25,7 +25,7 @@ Run `aitk sync --check . --json` before routing. It reports what a target is beh
 Read seven fields off the report and carry each to `## Route`:
 
 - `unmigrated`: a domain sitting at the root layout with nothing under `.claude/`. The most urgent finding, because that domain reports no drift of its own while being entirely behind
-- `superseded`: a file a newer seed folder replaced. Report it and stop. No command moves it, since the content is the project's own
+- `superseded`: a file a newer seed folder replaced. No command moves it, since the content is the project's own, so this routes to the skill that proposes the split rather than ending at the report
 - `seeds`: entries are `matching`, `stale`, `drifted`, or `missing`. Anything but `matching` needs the seed handoff
 - `domains[].entries`: per-file `stale`, `customized`, `stranded`, and `orphaned` as before
 - `reverse`: what the target holds that no live catalog claims. `unclaimed` lists folders at roots the toolkit stopped shipping, each with an `attribution` of `dropped`, `unattributed`, or `project`. Act on the first two and leave `project` alone, which history proved the project owns. `migrations` names a proposal-only skill with a live case here and the `reason` it was measured from
@@ -42,7 +42,7 @@ Map the stated intent, or what `## Diagnose` found, to one lifecycle phase, then
 
 - A domain in `unmigrated`: hand off to `migration-standards`
 - An entry in `migrations`: hand off to the skill its `skill` field names, spelled as the report spells it. Both of them propose without writing, so the handoff is where this stops
-- Anything in `superseded`: tell the user which files and what replaced them. Do not move or delete them
+- Anything in `superseded`: name which files and what replaced them, then hand off to `migration-superseded`. Both skills propose, so neither moves nor deletes the file
 - A folder in `unclaimed`: name it and the attribution it carries. No command moves it and the content may be the project's own, so the decision is the user's
 
 - First-time scaffold of a fresh project: hand off to `setup-init`

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

@@ -183,6 +183,13 @@ seed tree rather than from a fixed set of filenames, so a folder added later is
 covered without a code change. Only an exact stem matches, which leaves a
 suffixed variant such as `TASKS-ARCHIVE.md` unreported.
 
+Route it to `migration-superseded`. That skill resolves the standard governing
+`replacedBy` from the `appliesTo` the standards catalog declares, reads the
+destination shape from the target's own copy under `.claude/standards/` or at the
+root, and proposes the split without writing. Where a folder has no governing
+standard, or neither root holds the one it has, the entry earns a named refusal
+rather than a shape the project never adopted.
+
 `unmigrated` names a domain sitting at the root layout an older toolkit installed
 to, with nothing at the path the current one reads. It carries `rootPath`,
 `installPath`, and a file count. Without it a project holding `standards/` at its

package/docs/agents/markdown-audit.md

@@ -55,14 +55,16 @@ Every weight and depth measure counts the text a reader is shown. A link reduces
 
 A code span is walked around rather than through, so a path quoting link or angle-bracket syntax keeps the width the page gives it. Masking inside one takes back the decision to count it, and the placeholders this toolkit writes are where that shows.
 
-The paragraph check measures both halves of one rule. `markdown.md` caps a paragraph at four sentences, and a sentence cap on its own is satisfied by writing fewer and longer ones: 88 paragraphs in this corpus sit inside four sentences and past the weight checkpoint, and the heaviest of those runs 1121 characters. The standard therefore states a weight beside the sentence cap, and the verb reads it as its own checkpoint.
+The paragraph check measures both halves of one rule. `markdown.md` caps a paragraph at four sentences, and a sentence cap on its own is satisfied by writing fewer and longer ones: 36 paragraphs in this corpus sit inside four sentences and past the weight checkpoint, and the heaviest of those runs 1121 characters. The standard therefore states a weight beside the sentence cap, and the verb reads it as its own checkpoint.
 
-The paragraph weight sits at 600 and the bullet weight at 400. The two shapes measure one population, sharing a median near 170 characters with no gap behind either candidate, so the paragraph number was borrowed from the bullet rule when both checks shipped. They are separate checkpoints in the standard and separate patterns in the parser, and the sample below moved one and left the other untouched.
+The paragraph weight sits at 700 and the bullet weight at 400. Both shipped at 400, because the paragraph number was borrowed from the bullet rule when the two checks landed together, and each has since been read against a sample of its own. They are separate checkpoints in the standard and separate patterns in the parser, so a read that moves one leaves the other where it is.
 
 #### The sample behind the paragraph number
 
 The checkpoint shipped at 400 as a borrowed number and was decided against a read of the prose it reports. Thirty-six findings were sampled, six from each of six weight bands, drawn at even spacing through each band ordered by path and line, and each was classed as prose a reader wants split or prose the checkpoint should not have reported.
 
+Every band below was measured before the scan stopped counting link syntax as prose, so a paragraph sitting in one of these bands is heavier than a paragraph reported at the same number today. The re-sample in the section below re-reads the same range against the corrected measure and reaches the opposite verdict on it, which is the measure moving rather than the reader.
+
 | Band      | Wants the split | Reads as written |
 | --------- | --------------- | ---------------- |
 | 400 - 425 | 1               | 5                |
@@ -78,6 +80,10 @@ Nothing inside the 500 to 600 band separated the two classes by length, which is
 
 The sample is thirty-six paragraphs against a reported population in the hundreds, and one reader classed all of them. Treat a band's rate as the order of magnitude it is rather than as a measured precision, and re-sample before moving the number again.
 
+#### The re-sample that moved the number to 700
+
+That re-sample ran once the scan stopped counting link syntax as prose. Findings at 604, 633, and 677 characters each read as an ordinary four-sentence paragraph on one topic, density arrived around 760 and was plain by 860, and the move cut the weight half of the report roughly in half while leaving the sentence cap untouched.
+
 A bullet, a heading, a table row, a blockquote, a blank line, and a fence each end a paragraph, so a heavy bullet is reported by the bullet check alone and never counted twice.
 
 ## Exit codes

package/docs/target-projects.md

@@ -193,5 +193,5 @@ Sync also refuses a target whose working tree is dirty, so commit or stash befor
 
 - [agents](agents/index.md): CLI flags, exit codes, and JSON output shapes
 - [AI workflow](ai-workflow.md): feature-development loop inside a toolkit-managed project
-- [tooling](../.claude/context/tooling.md), [governance](../.claude/context/governance.md), [claude plugin](../.claude/context/claude-plugin/index.md), [indexes](../.claude/context/indexes.md), [snippets](../.claude/context/snippets.md), [standards](../.claude/context/standards/index.md): per-domain mechanics
+- [tooling](../.claude/context/tooling.md), [governance](../.claude/context/governance/index.md), [claude plugin](../.claude/context/claude-plugin/index.md), [indexes](../.claude/context/indexes.md), [snippets](../.claude/context/snippets.md), [standards](../.claude/context/standards/index.md): per-domain mechanics
 - [sandbox](../.claude/context/sandbox/index.md): scenario catalog for verifying domain flows

package/package.json

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

package/src/markdown/structure.ts

@@ -45,7 +45,7 @@ export const DEFAULT_CHECKPOINTS = {
   run: 40,
   peerBullet: 130,
   bullet: 400,
-  paragraph: 600,
+  paragraph: 700,
   sentences: 4,
   renderWidth: 80,
 } as const

package/standards/markdown.md

@@ -34,7 +34,7 @@ Does not govern:
 
 - Use prose by default. Reserve bullets for discrete, unrelated items.
 - Keep paragraphs to four sentences or fewer. Split longer blocks at the next logical boundary.
-- Past roughly 600 characters in one paragraph, folding in the lines that wrap it, split at the next logical boundary as well. A paragraph written as two long sentences satisfies the sentence cap above and still asks the reader to hold too much at once. This number sits above the bullet checkpoint because a paragraph is read straight through and a bullet is scanned.
+- Past roughly 700 characters in one paragraph, folding in the lines that wrap it, split at the next logical boundary as well. A paragraph written as two long sentences satisfies the sentence cap above and still asks the reader to hold too much at once. This number sits well above the bullet checkpoint because a paragraph is read straight through and a bullet is scanned.
 - Keep bullets tight. Past roughly 400 characters in one top-level bullet, counting the lines that continue it and excluding any bullet nested under it, the overflow belongs in prose. The number is a checkpoint rather than a cap, and a bullet reading well past it means the number is wrong rather than the rule.
 - Collapse a stack of bullets narrating one subsystem into a single `###` subsection carrying one narrative. Splitting a heavy bullet into three light ones satisfies the checkpoint above and leaves the reader no better off, and subdividing a block does not lighten the bullets inside it, so the two rules answer different defects.
 - Use dashes (`-`) not asterisks (`*`) for bulleted lists