@erclx/aitk 0.72.0 → 0.74.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.72.0",
+  "version": "0.74.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -21,6 +21,8 @@ The last failure is writing without re-checking. A domain sync brought a stricte
 - Map the stated intent to one lifecycle phase, then either run the simplest command that satisfies it or hand off
 - Resolve every stack, rule, snippet, and standard name from a catalog at runtime
 - Run the CLI non-interactively and report the command run, what changed, and the full path of anything written
+- Read the reverse walk beside the forward sections, so a folder the toolkit stopped shipping and a migration with a live case both reach the user
+- Hand off a named migration to the skill the report names, the way an unmigrated domain reaches `migration-standards`
 - Offer every audit whose surface the target carries, and offer none whose surface it lacks
 - Re-check the target after any operation that wrote, and report what those writes changed against the state read before acting
 
@@ -29,6 +31,7 @@ The last failure is writing without re-checking. A domain sync brought a stricte
 - Edit a managed file by hand instead of running the CLI that owns it
 - Reimplement a flow another skill owns
 - Hardcode a catalog name
+- Move, delete, or name a command against a folder in `unclaimed`. The toolkit stopped claiming the path and only the user knows whether the project owns what sits there
 - Run an audit the user did not pick, which turns a front door into a full sweep
 - Refuse to finish an operation over an audit finding, since every audit reports judgments beside facts and a router that stops on one is a router a target works around
 - Auto-trigger. It is a door the user opens, and a router that fires on its own routes requests nobody made.
@@ -38,6 +41,7 @@ The last failure is writing without re-checking. A domain sync brought a stricte
 - An intent matching a deep flow hands off rather than running a shallow version of it, since a partial scaffold is harder to recover from than none
 - An ignore-only fix on an unmeasured tooling report stops, names which cause applies, and names the command answering that cause. Unmeasured has several causes and they do not share a remedy, so one suggested command is wrong for at least one of them. No cause asks the user to supply a stack name, and none reads the zero counts under an unmeasured report as a clean target.
 - A re-check with no earlier report to compare against says the write ran without a baseline, rather than describing the target from scratch
+- A report missing a field this skill reads names the CLI version as the cause and reports that section as unread. Neither an absent key nor a hand-rolled substitute for it may be reported as a finding, since the first reads as a clean target and the second reaches a verdict only the field's attribution can make
 
 ## Out of scope
 

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

@@ -22,23 +22,28 @@ Load a domain doc with `aitk docs <topic>` only when the intent touches that dom
 
 Run `aitk sync --check . --json` before routing. It reports what a target is behind on across every surface, so the intent comes from the project state rather than from the user having to know it already. Skip only when the user named a single operation to run.
 
-Read six fields off the report and carry each to `## Route`:
+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
 - `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
-- `historyUnavailable` on a domain or on `seeds`: attribution failed, so treat every difference as unverified and say so rather than reporting a file as untouched
+- `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
+- `historyUnavailable` on a domain, on `seeds`, or on `reverse`: nothing could be dated, so treat every difference as unverified and say so rather than reporting a file as untouched. It is set on `reverse` when the toolkit itself ships without history, which is the registry-install case, so the walk found nothing rather than finding a clean target
 - `tooling`: read `measured` first. Every count under it is zero when it is false, which is an absence of measurement rather than a measured zero. Past that, `chain` names the stacks the install resolved, nearest first, and `counts.gitignore` counts the managed ignore entries the target is missing.
 
 State what the report found in one line per finding before acting on any of it.
 
+A `reverse` key the report does not carry at all is a CLI predating the field rather than a target with nothing unclaimed. Say the walk did not run and name the CLI version as the cause. Reading the absent key as an empty answer reports a clean target to a project nobody has looked at, and answering it from a filesystem walk of your own is worse, since that reaches a verdict the attribution the field carries is the only thing entitled to make.
+
 ## Route
 
 Map the stated intent, or what `## Diagnose` found, to one lifecycle phase, then act:
 
 - 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
+- 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`
 - Governance rules for the project stack: hand off to `setup-gov`

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

@@ -210,6 +210,12 @@ code change. Scoping to those roots is what keeps the walk useful: walking the
 whole tree reports every project folder as unclaimed, which is true and says
 nothing.
 
+The managed gate above applies here too, and it is the one place it surprises.
+A directory holding a dropped folder and nothing else reports an empty `reverse`
+rather than the folder, because it carries none of the three markers. Read an
+empty section on an unmanaged target as a walk that never ran rather than as a
+clean result.
+
 Each entry carries `rel`, a file count, and an `attribution` of `dropped`,
 `project`, or `unattributed`. A dropped folder and one the project wrote are the
 same bytes at the same path, so the verdict is traced from history rather than

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.72.0",
+  "version": "0.74.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/lib/sandbox-fixtures.sh

@@ -99,6 +99,67 @@ stage_toolkit_markdown() {
   done < <(find "$src" -maxdepth 1 -type f -name "*.md" ! -name "index.md" | sort | head -n "$count")
 }
 
+# The newest top-level path history records a deletion under that the toolkit no
+# longer ships. Read from history rather than hardcoded, so an arm stages a root
+# the walk will actually recognize instead of a name that has since come back.
+# `prompts` is preferred because it is the case measured in a real target, and
+# any other dropped root exercises the same walk.
+pick_dropped_root() {
+  local preferred="prompts"
+  local first=""
+  local candidate
+
+  while IFS= read -r candidate; do
+    [ -e "$PROJECT_ROOT/$candidate" ] && continue
+    [ "$candidate" = "$preferred" ] && {
+      echo "$preferred"
+      return 0
+    }
+    [ -n "$first" ] || first="$candidate"
+  done < <(git -C "$PROJECT_ROOT" log --all --diff-filter=D --name-only --format= |
+    awk -F/ 'NF > 1 { print $1 }' | sort -u)
+
+  echo "$first"
+}
+
+# Restores one file's exact published bytes from the commit before it was
+# deleted. Content is what the attribution matches on, so a file written by hand
+# would report unattributed and an arm would assert the wrong verdict.
+#
+# Both reads take the whole listing through a process substitution rather than a
+# pipeline ending in an early exit. `set -o pipefail` is on, and a `grep -m 1`
+# that matches the first line closes the pipe while git is still writing, so the
+# substitution returns git's SIGPIPE status and the arm fails on a listing it
+# actually read.
+restore_dropped_file() {
+  local root="$1"
+  local rel="" commit="" line
+
+  while IFS= read -r line; do
+    case "$line" in
+    "$root"/*)
+      rel="$line"
+      break
+      ;;
+    esac
+  done < <(git -C "$PROJECT_ROOT" log --all --diff-filter=D --name-only \
+    --format= -- "$root/")
+
+  [ -n "$rel" ] || return 1
+
+  while IFS= read -r line; do
+    commit="$line"
+    break
+  done < <(git -C "$PROJECT_ROOT" log --all --diff-filter=D --format=%H -- "$rel")
+
+  [ -n "$commit" ] || return 1
+
+  mkdir -p "$(dirname "$rel")"
+  git -C "$PROJECT_ROOT" show "$commit^:$rel" >"$rel" || return 1
+
+  echo "$rel"
+}
+
 # Stages one step of a scenario arm into the sandbox working directory.
 # Scenarios call this once per step so their own git operations stay between
 # the steps, where they are visible.

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