@erclx/aitk 0.51.0 → 0.52.0

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

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

package/docs/agents/context-audit-checks.md

@@ -13,7 +13,9 @@ The required-section check reports what does not declare `## Overview` and `## L
 
 Which unit answers depends on the folder. Entries of the folder named under `.claude/` are one domain each, so each answers for itself and a finding names the entry. Entries of a folder a domain split into describe that one domain between them, so any sibling answers and a finding names the folder. Holding a split folder to the rule per file would report every child beside its `overview.md`, and rolling the named folder up would let one conforming entry stand in for every other domain sitting next to it.
 
-It reports rather than gates, the closer call because a missing section reads more like a fact than the other judgments. What settles it is that the standard sanctions omitting `## Layout` from a domain owning no paths in the repo, and no measure separates that from an entry that forgot it. A domain covering only external tools is that case, and it reports on every run. The JSON record carries the findings as `missingSections` and the list as `checkpoints.requiredSections`.
+It reports rather than gates by default, the closer call because a missing section reads more like a fact than the other judgments. What settles it is that the standard sanctions omitting `## Layout` from a domain owning no paths in the repo, and no measure separates that from an entry that forgot it. A domain covering only external tools is that case, and it reports on every run. The JSON record carries the findings as `missingSections` and the list as `checkpoints.requiredSections`.
+
+`--gate` promotes the finding to a failing exit code, which the seed stage runs and no other caller does. That mode needs an answer to the sanctioned omission above, so a file declaring `stub: true` in its frontmatter is dropped before the check and reported nowhere. Both are described in `context-audit.md`.
 
 ## Length and depth
 

package/docs/agents/context-audit.md

@@ -1,6 +1,6 @@
 ---
 title: Context audit
-description: Running the audit, its flags and folder scope, the exit codes, and the citation gate that is the only failing one
+description: Running the audit, its flags and folder scope, the exit codes, the citation gate, and the widened gate the seed stage runs
 ---
 
 # Context audit
@@ -13,6 +13,7 @@ aitk context audit --json
 aitk context audit --citations-only
 aitk context audit --folder context,diagrams
 aitk context audit --folder docs
+aitk context audit tooling/base/seeds --gate
 ```
 
 | Option             | Behavior                                                             |
@@ -20,6 +21,9 @@ aitk context audit --folder docs
 | `--json`           | Add a machine-readable record on stdout, keeping the frame           |
 | `--folder <list>`  | Comma-separated folder names (default: the three below)              |
 | `--citations-only` | Run the gating citation check alone, printing nothing when it passes |
+| `--gate`           | Fail on a missing required section or index drift as well            |
+
+`--citations-only` and `--gate` refuse together. The first runs the citation check alone, so the two findings the second adds are never measured, and a run honoring both would exit clean on a file short a required section.
 
 ## Folder scope
 
@@ -31,7 +35,36 @@ A run where no requested name resolves refuses, whichever list it read. Naming t
 
 ## Exit codes
 
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for an unresolved citation. Only the citation check sets a failing code. Required-section, length, depth, bullet weight, table, provenance, and index findings print and return `0`, because each is a judgment and failing a push on one would make the check something to route around.
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a gating finding. An unresolved citation gates under every mode. Length, depth, bullet weight, table, and provenance findings print and return `0` under every mode, because each is a judgment and failing a push on one would make the check something to route around.
+
+Required-section and index findings sit between the two. Both are answerable from the file rather than weighed, so `--gate` promotes them to failing codes while a bare run leaves them advisory. The toolkit runs the bare form against itself and the widened form against the seed tree, described below.
+
+## The seed gate
+
+`bun run check` runs `--gate` against every `tooling/<stack>/seeds/` directory carrying a `.claude/` folder, discovered per run so a new stack is covered without a script edit. The seed tree installs into every scaffolded project, so a seed breaking the standard it seeds teaches the wrong shape to each one, and no rule path reaches the tree to report it.
+
+The widened gate is correct here and wrong at the project root. A seed is authored once and read by every target, while a context entry in a live project is edited under time pressure by the people who own it. A missing section in the first is a defect shipping outward, and in the second it is a threshold worth reporting and not worth blocking a push over.
+
+Coverage follows the index-plus-entry contract, so it reaches seeded entries and the indexes beside them. Seed files sitting directly under `.claude/`, currently `ARCHITECTURE.md`, `DESIGN.md`, and `REQUIREMENTS.md`, belong to no audited folder and stay outside it.
+
+The stage prints the entries it measured per root and warns on a root that measured none. A root can resolve an audited folder and hold no entry in it, which `tooling/claude/seeds` does today, so a single pass line over the set would report coverage of a tree nothing opened.
+
+It reads the exit code rather than pass against fail, since the two failing codes mean opposite things. A root carrying a `.claude/` that resolves no audited folder refuses at 1 and warns, while a seed short a required section gates at 2 and fails the push. A new stack seeding `.claude/` alone therefore reports what it is rather than a violation it does not have.
+
+### Exempting a skeleton
+
+A seed that deliberately omits a required section sets `stub: true` in its frontmatter, and the section check then skips it. Every other measure still reads the file, since a stub is exempt from owing sections rather than from being well formed.
+
+```markdown
+---
+title: Architecture
+stub: true
+---
+```
+
+Only `true` counts. A field holding anything else reads as a seed that meant to turn the exemption off, so a typo cannot silence the gate. Both install paths strip the field on the way into a target, which keeps toolkit bookkeeping out of a project whose own tooling would never read it. A block holding nothing else is dropped whole.
+
+The exemption exists because the section check has a false-positive class. A standard may sanction omitting a section, and no measure separates that from a file that forgot it, which is why the finding stays advisory everywhere the widened gate is not running. No seed sets the field today.
 
 ## The citation gate
 

package/docs/agents/index.md

@@ -12,7 +12,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Command catalog](commands.md): Every project-level command and every domain subcommand, plus the shape each domain exposes
 - [Comments](comments.md): Comment density by language and kind, the two structural exclusions, and how the degradation sweep finds its vocabulary
 - [Context audit checks](context-audit-checks.md): What each non-gating check reports, the unit each checkpoint is measured in, and which folders each check reaches
-- [Context audit](context-audit.md): Running the audit, its flags and folder scope, the exit codes, and the citation gate that is the only failing one
+- [Context audit](context-audit.md): Running the audit, its flags and folder scope, the exit codes, the citation gate, and the widened gate the seed stage runs
 - [Docs](docs.md): How aitk docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
 - [Indexes](indexes.md): Flags, exit codes, and JSON shape for aitk indexes regen, plus when it auto-stages what it rewrote
 - [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project

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

@@ -144,6 +144,12 @@ needs a stamp and seeds carry none, so a file history cannot attribute stays
 `drifted`. Reconcile the section with `claude-seed-sync`, which merges one
 section at a time rather than replacing a file the project edits.
 
+A markdown seed installs rewritten rather than copied, since the `stub: true`
+marker the toolkit's own seed gate reads is stripped on the way in. The
+comparison above runs against what the install would write, so a marked seed a
+target never touched still reports `matching`. Every other seed copies byte for
+byte.
+
 `superseded` names a file a newer seed folder replaced, such as `.claude/TASKS.md`
 against the `.claude/tasks/` that now ships. The entry carries `replacedBy` and
 nothing else, and the file is never deleted, since the content belongs to the

package/docs/ai-workflow.md

@@ -76,7 +76,7 @@ Run one orchestrator at a time. The board is gitignored, so a second session rea
 
 Before a handoff, the orchestrator checks the plan against the tree rather than reading it: grep each construct it names and count the sites, confirm every phase label it cites is still open, and open each file it describes. A plan goes stale from whatever merged after it was written, and reading cannot catch that.
 
-`.claude/plans/`, `.claude/review/`, and `.claude/memory/` all resolve at the main worktree root, so artifacts created in any session are visible from any sibling worktree. See [Claude Code and git worktrees](../wiki/claude-worktrees.md) for the full rule and the domain-level fan-out guidance.
+`.claude/plans/`, `.claude/review/`, and `.claude/memory/` all resolve at the main worktree root, so artifacts created in any session are visible from any sibling worktree. See [Claude Code and git worktrees](../wiki/claude/claude-worktrees.md) for the full rule and the domain-level fan-out guidance.
 
 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/docs/operating-model.md

@@ -10,7 +10,7 @@ A way to build fast and reliably across parallel Claude Code sessions without a
 loop and without losing the human review gate. One warm session plans and
 reviews. Cold worker sessions build. The human launches workers and merges. This
 page covers the roles and the loop. For the worktree mechanism (isolation, merge
-order, port collisions), see [Claude Code and git worktrees](../wiki/claude-worktrees.md).
+order, port collisions), see [Claude Code and git worktrees](../wiki/claude/claude-worktrees.md).
 
 ## Two roles
 
@@ -105,11 +105,11 @@ at two or three worker tracks and split them across the stack so they do not
 collide on the same files. Unit checks run freely in many worktrees at once.
 Only fixed-port work (a dev server, an end-to-end run, a screenshot) and
 singleton resources (one local model server, one GPU) serialize. See
-[Claude Code and git worktrees](../wiki/claude-worktrees.md) for merge order and the
+[Claude Code and git worktrees](../wiki/claude/claude-worktrees.md) for merge order and the
 port-collision detail.
 
 ## Related
 
-- [Claude Code and git worktrees](../wiki/claude-worktrees.md) for the isolation and fan-out mechanics
-- [Claude Code subagents](../wiki/claude-subagents.md) for in-session parallelism without worktrees
+- [Claude Code and git worktrees](../wiki/claude/claude-worktrees.md) for the isolation and fan-out mechanics
+- [Claude Code subagents](../wiki/claude/claude-subagents.md) for in-session parallelism without worktrees
 - `.claude/context/claude-plugin/skill-strategy.md` for how the skills in the loop are categorized

package/docs/visual-design-workflow.md

@@ -8,9 +8,9 @@ category: Workflow
 
 Three tiers cover the range from prose-only design docs to a fully graphical design source of truth. Pick one per project based on how UI-heavy the work is, whether stakeholders review visuals, and whether a designer is involved. Tiers stack, so moving up does not invalidate work done at a lower tier.
 
-The tier framework sits alongside [Claude Design](../wiki/claude-design.md), [visual wireframes](../wiki/visual-wireframes.md), [community skills and plugins](../wiki/community-skills.md), and [community MCP servers](../wiki/community-mcp-servers.md). Those pages catalog the tooling. This page decides when to reach for what.
+The tier framework sits alongside [Claude Design](../wiki/claude/claude-design.md), [visual wireframes](../wiki/tools/visual-wireframes.md), [community skills and plugins](../wiki/tools/community-skills.md), and [community MCP servers](../wiki/tools/community-mcp-servers.md). Those pages catalog the tooling. This page decides when to reach for what.
 
-Two tools anchor tier 1 and tier 2. [Stitch](../wiki/stitch.md) is the agent-addressable default through its MCP server at `stitch.googleapis.com/mcp`, with a free tier of 400 daily credits that covers daily iteration. [Claude Design](../wiki/claude-design.md), released 2026-04-17 and priced inside Claude subscriptions, is the ceiling tool reserved for codebase extraction and the richly annotated handoff bundle. Each covers a different job, they are not swappable.
+Two tools anchor tier 1 and tier 2. [Stitch](../wiki/tools/stitch.md) is the agent-addressable default through its MCP server at `stitch.googleapis.com/mcp`, with a free tier of 400 daily credits that covers daily iteration. [Claude Design](../wiki/claude/claude-design.md), released 2026-04-17 and priced inside Claude subscriptions, is the ceiling tool reserved for codebase extraction and the richly annotated handoff bundle. Each covers a different job, they are not swappable.
 
 ## Tier 0: prose only
 
@@ -51,16 +51,16 @@ Impeccable, if installed, keeps its own root `DESIGN.md` and `PRODUCT.md` in the
 
 ### Tools
 
-- Stitch via MCP at `stitch.googleapis.com/mcp`. Default pick for agent-driven visual generation. Free tier of 400 daily credits. See [Stitch](../wiki/stitch.md).
-- Excalidraw canvas server on localhost plus the `yctimlin/mcp_excalidraw` MCP shim, for projects that need an agent to draw, read back, and revise a canvas. See [visual wireframes](../wiki/visual-wireframes.md) for setup and footguns.
-- Playwright MCP for browser-side verification. See [Playwright](../wiki/community-mcp-servers.md#playwright-microsoft).
-- Chrome DevTools MCP for live frontend debugging. See [Chrome DevTools](../wiki/community-mcp-servers.md#chrome-devtools-google).
-- Claude Design as the ceiling option for codebase extraction or polished handoff bundles. See [Claude Design](../wiki/claude-design.md).
+- Stitch via MCP at `stitch.googleapis.com/mcp`. Default pick for agent-driven visual generation. Free tier of 400 daily credits. See [Stitch](../wiki/tools/stitch.md).
+- Excalidraw canvas server on localhost plus the `yctimlin/mcp_excalidraw` MCP shim, for projects that need an agent to draw, read back, and revise a canvas. See [visual wireframes](../wiki/tools/visual-wireframes.md) for setup and footguns.
+- Playwright MCP for browser-side verification. See [Playwright](../wiki/tools/community-mcp-servers.md#playwright-microsoft).
+- Chrome DevTools MCP for live frontend debugging. See [Chrome DevTools](../wiki/tools/community-mcp-servers.md#chrome-devtools-google).
+- Claude Design as the ceiling option for codebase extraction or polished handoff bundles. See [Claude Design](../wiki/claude/claude-design.md).
 
 ### Skills
 
 - Everything from tier 0
-- A frontend design skill to steer visual quality. Pick one of [Impeccable](../wiki/community-skills.md#pbakausimpeccable), [UI/UX Pro Max](../wiki/community-skills.md#nextlevelbuilderui-ux-pro-max-skill), or Anthropic's `frontend-design` plugin. Impeccable is the strongest default because of its curated anti-patterns.
+- A frontend design skill to steer visual quality. Pick one of [Impeccable](../wiki/tools/community-skills.md#pbakausimpeccable), [UI/UX Pro Max](../wiki/tools/community-skills.md#nextlevelbuilderui-ux-pro-max-skill), or Anthropic's `frontend-design` plugin. Impeccable is the strongest default because of its curated anti-patterns.
 
 ### When to pick
 
@@ -91,9 +91,9 @@ Design happens in a graphical tool. `.claude/DESIGN.md` either regenerates from
 
 ### Tools
 
-- Figma desktop app with the [Figma Dev Mode MCP](../wiki/community-skills.md#figma-mcp-and-code-to-canvas) for teams with a dedicated designer already on Figma. Bidirectional sync and Code to Canvas capture.
-- Claude Design with its Claude Code handoff bundle for teams without an existing Figma investment and for solo founders or PMs driving design themselves. One-way handoff, no bidirectional sync. See [Claude Design](../wiki/claude-design.md).
-- Stitch via MCP as a low-cost complement to either, used for bulk screen generation driven by Claude Code. See [Stitch](../wiki/stitch.md).
+- Figma desktop app with the [Figma Dev Mode MCP](../wiki/tools/community-skills.md#figma-mcp-and-code-to-canvas) for teams with a dedicated designer already on Figma. Bidirectional sync and Code to Canvas capture.
+- Claude Design with its Claude Code handoff bundle for teams without an existing Figma investment and for solo founders or PMs driving design themselves. One-way handoff, no bidirectional sync. See [Claude Design](../wiki/claude/claude-design.md).
+- Stitch via MCP as a low-cost complement to either, used for bulk screen generation driven by Claude Code. See [Stitch](../wiki/tools/stitch.md).
 - Playwright and Chrome DevTools MCPs as in tier 1
 
 ### Skills
@@ -128,9 +128,9 @@ Zero or one yes: tier 0. Two or three: tier 1. Four: tier 2. Resist over-tiering
 
 ## References
 
-- [Stitch](../wiki/stitch.md): Gemini-powered design product with the MCP server that anchors tier 1
-- [Claude Design](../wiki/claude-design.md): first-party hosted design product and handoff bundle
+- [Stitch](../wiki/tools/stitch.md): Gemini-powered design product with the MCP server that anchors tier 1
+- [Claude Design](../wiki/claude/claude-design.md): first-party hosted design product and handoff bundle
 - `.claude/context/claude-plugin/skill-strategy.md`: how to decide between workflow and domain-knowledge skills
-- [Visual wireframes](../wiki/visual-wireframes.md): Excalidraw research and setup for the tier 1 wireframe companion
-- [Community skills and plugins](../wiki/community-skills.md): catalog of frontend design skills and integrations
-- [Community MCP servers](../wiki/community-mcp-servers.md): catalog of MCPs referenced across all tiers
+- [Visual wireframes](../wiki/tools/visual-wireframes.md): Excalidraw research and setup for the tier 1 wireframe companion
+- [Community skills and plugins](../wiki/tools/community-skills.md): catalog of frontend design skills and integrations
+- [Community MCP servers](../wiki/tools/community-mcp-servers.md): catalog of MCPs referenced across all tiers

package/docs/zshrc-aliases.md

@@ -56,7 +56,7 @@ Use `clp` in any other repository where you want the toolkit skills available. W
 
 Use `cls` or `clps` to save Opus usage on routine sessions. Switch mid-session with `/model` to avoid restarting.
 
-Use `clw <name>` for features that will take more than one session. A worktree isolates the branch, the transcripts, and the `/resume` history. See [Claude Code and git worktrees](../wiki/claude-worktrees.md) for fan-out rules.
+Use `clw <name>` for features that will take more than one session. A worktree isolates the branch, the transcripts, and the `/resume` history. See [Claude Code and git worktrees](../wiki/claude/claude-worktrees.md) for fan-out rules.
 
 Use `clc` to resume the last session without a picker. Use `clr` when you have several sessions and need to pick by name or recency. Outside the toolkit repo, `clpc` is the same shortcut as `clc` with the plugin loaded.
 

package/package.json

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

package/scripts/core/verify.sh

@@ -116,6 +116,28 @@ assert_hero_pair() {
   [ "$html_commit" = "$png_commit" ]
 }
 
+# Whatever stacks the repo currently carries, so a new one is covered without an
+# edit here. A seed root holding no `.claude/` seeds nothing a standard governs.
+collect_seed_roots() {
+  local dir
+  for dir in "$PROJECT_ROOT"/tooling/*/seeds; do
+    [ -d "$dir/.claude" ] || continue
+    printf '%s\n' "${dir#"$PROJECT_ROOT"/}"
+  done
+}
+
+# Entries the audit actually measured, summed across the folders it resolved.
+# `--json` carries one `"entries":<n>` per folder object, and the top-level key
+# of that name holds an array, so the numeric match reaches folders alone.
+#
+# A root can resolve a folder and measure nothing in it, which is a passing gate
+# over an empty set. The stage prints this per root rather than reporting one
+# verdict for every root, or a tree nobody measured reads as a tree that passed.
+seed_entry_count() {
+  printf '%s' "$1" | grep -o '"entries":[0-9]\+' | grep -o '[0-9]\+' |
+    awk '{ total += $1 } END { print total + 0 }'
+}
+
 assert_no_drift() {
   local paths=$1
   local err_msg=$2
@@ -183,6 +205,67 @@ main() {
   run_check "cd $PROJECT_ROOT && bun src/cli.ts context audit --citations-only" "A cited context path does not resolve. Run bun src/cli.ts context audit."
   log_info "Context citations resolve"
 
+  # The stage above audits this repository. Its seed tree ships into every
+  # scaffolded project, so a seed breaking the standard it seeds propagates
+  # instead of sitting still, and no rule path reaches the tree to report it.
+  # `--gate` fails on the two findings beside citations that are facts, a
+  # missing required section and index drift, and leaves the thresholds
+  # advisory for the reason the stage above leaves them so. A passing run stays
+  # silent because the audit prints a frame that would nest inside this one.
+  log_step "Seed standards"
+  local seed_roots seed_root seed_output seed_frame seed_entries seed_measured seed_status
+  seed_roots=$(collect_seed_roots)
+  if [ -z "$seed_roots" ]; then
+    log_info "Skipped, no seed root carries .claude/"
+  else
+    seed_measured=0
+    while IFS= read -r seed_root; do
+      # `--json` puts the record on stdout and the frame on stderr, so the
+      # passing run stays silent and the failing one is re-run for its frame
+      # rather than parsed out of a stream this script would have to strip.
+      seed_status=0
+      seed_output=$(cd "$PROJECT_ROOT" && bun src/cli.ts context audit "$seed_root" --gate --json 2>/dev/null) || seed_status=$?
+
+      # The audit separates 1 from 2 and they mean opposite things. 2 is a seed
+      # breaking the standard it seeds. 1 is the audit refusing, which a seed
+      # root carrying no audited folder produces, and reporting that as a
+      # violation sends a reader hunting one that does not exist. Discovery is
+      # what puts this in reach, since a new stack seeding `.claude/` alone
+      # arrives here with no edit to this script.
+      case $seed_status in
+      0) ;;
+      1)
+        log_warn "$seed_root: no audited folder under .claude/, nothing measured"
+        continue
+        ;;
+      *)
+        # `|| true` because the re-run exits non-zero by construction, and
+        # `set -e` would take the script down before log_error names the root.
+        seed_frame=$(cd "$PROJECT_ROOT" && bun src/cli.ts context audit "$seed_root" --gate 2>&1 || true)
+        echo "$seed_frame" | pipe_output
+        if [ "$seed_status" -eq 2 ]; then
+          log_error "A seed breaks the standard governing the folder it seeds: $seed_root"
+        else
+          log_error "The seed audit exited $seed_status against $seed_root, which is neither a pass nor a finding."
+        fi
+        ;;
+      esac
+
+      seed_entries=$(seed_entry_count "$seed_output")
+      seed_measured=$((seed_measured + seed_entries))
+
+      if [ "$seed_entries" -eq 0 ]; then
+        log_warn "$seed_root: no entry under an audited folder, nothing measured"
+      else
+        log_info "$seed_root: $seed_entries entries measured"
+      fi
+    done <<<"$seed_roots"
+
+    if [ "$seed_measured" -eq 0 ]; then
+      log_warn "No seed entry was measured. The stage covered nothing."
+    fi
+  fi
+
   # Presence of a required file is a fact, so it gates. The name, description,
   # folder, and requirement-section measures beside it report and are read from a
   # bare run. `bun src/cli.ts` for the reason the stage above uses it, and the

package/src/claude/seeds.ts

@@ -1,7 +1,8 @@
 import { existsSync } from 'node:fs'
-import { chmod } from 'node:fs/promises'
-import { join } from 'node:path'
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
 import { copyPreservingMode } from '@/copy'
+import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
 
 const SEEDS_DIR = join('tooling', 'claude', 'seeds')
 const CLAUDE_DIR = '.claude'
@@ -122,12 +123,25 @@ export function countByScope(seeds: readonly Seed[]): SeedCounts {
 /**
  * Copies each pending seed. Hooks get the executable bit the way `chmod +x`
  * granted it, added on top of whatever mode the destination already carried.
+ *
+ * A markdown seed is rewritten rather than copied, so the stub marker the seed
+ * gate reads does not reach the target. Every other seed copies byte for byte,
+ * which is what keeps the hook scripts and `settings.json` untouched.
  */
 export async function applySeeds(seeds: readonly Seed[]): Promise<string[]> {
   const applied: string[] = []
 
   for (const seed of seeds) {
-    await copyPreservingMode(seed.src, seed.dest)
+    if (rewritesOnInstall(seed.src)) {
+      await mkdir(dirname(seed.dest), { recursive: true })
+      await writeFile(
+        seed.dest,
+        stripSeedMarker(await readFile(seed.src, 'utf8')),
+      )
+    } else {
+      await copyPreservingMode(seed.src, seed.dest)
+    }
+
     if (seed.executable) await chmod(seed.dest, 0o755)
     applied.push(seed.applyLabel)
   }

package/src/commands/context.ts

@@ -21,6 +21,7 @@ import {
   presentNames,
   resolveFolders,
 } from '@/context/folders'
+import { isGating } from '@/context/gate'
 import { auditIndexes, type FolderDrift } from '@/context/index-drift'
 import {
   frameError,
@@ -34,8 +35,8 @@ import {
   plural,
 } from '@/ui'
 
-/** Returned when an unresolved citation is found, which is the gating check. */
-const EXIT_UNRESOLVED = 2
+/** Returned when a gating finding is present. */
+const EXIT_GATE = 2
 
 /** A name of dots alone is `.` or `..`, both of which escape the audit root. */
 const FOLDER_NAME = /^(?!\.+$)[A-Za-z0-9._-]+$/
@@ -44,6 +45,7 @@ interface AuditCommandOptions {
   readonly json?: boolean
   readonly folder?: string
   readonly citationsOnly?: boolean
+  readonly gate?: boolean
 }
 
 export function register(program: Command): void {
@@ -65,17 +67,23 @@ export function register(program: Command): void {
       'Comma-separated folder names, resolved under .claude/ then the project root',
     )
     .option('--citations-only', 'Run the gating citation check alone')
+    .option(
+      '--gate',
+      'Also fail on a missing required section or index drift, the findings that are facts',
+    )
     .addHelpText(
       'after',
       [
         '',
         'Exit codes:',
-        '  0  the audit completed with every cited path resolving',
+        '  0  the audit completed with no gating finding',
         '  1  refused, with the reason on stderr',
-        '  2  a cited path did not resolve',
+        '  2  a gating finding is present',
         '',
-        'Only unresolved citations set a failing exit code. Section, length,',
-        'depth, bullet, table, provenance, and index findings are advisory.',
+        'An unresolved citation always gates. --gate widens the gate to the',
+        'other two findings that are facts rather than judgments: a missing',
+        'required section and index drift. Length, depth, bullet, table, and',
+        'provenance findings are thresholds and stay advisory under both.',
         '',
         'Examples:',
         '  aitk context audit',
@@ -83,6 +91,7 @@ export function register(program: Command): void {
         '  aitk context audit --citations-only',
         '  aitk context audit --folder context,diagrams',
         '  aitk context audit --folder docs',
+        '  aitk context audit tooling/base/seeds --gate',
         '',
       ].join('\n'),
     )
@@ -118,6 +127,17 @@ async function runAudit(
   const root = resolve(path ?? process.cwd())
   const names = parseFolders(opts.folder)
   const gateOnly = opts.citationsOnly ?? false
+  const widened = opts.gate ?? false
+
+  // `--citations-only` runs the citation check alone, so the two findings
+  // `--gate` adds are never measured. Honouring both would exit 0 on a seed
+  // short a required section, which is the pass a gate exists to prevent.
+  if (gateOnly && widened) {
+    return refuse(
+      '--citations-only runs the citation check alone, so --gate would widen the gate to findings the run never measures. Pass one.',
+      gateOnly,
+    )
+  }
 
   if (typeof names === 'string') return refuse(names, gateOnly)
 
@@ -213,7 +233,14 @@ async function runAudit(
     )
   }
 
-  return citations.unresolved.length > 0 ? EXIT_UNRESOLVED : 0
+  const gating = isGating({
+    unresolvedCitations: citations.unresolved.length,
+    sections,
+    drift,
+    widened,
+  })
+
+  return gating ? EXIT_GATE : 0
 }
 
 function refuse(message: string, gateOnly: boolean): number {

package/src/context/audit.ts

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises'
 import { relative } from 'node:path'
 import type { AuditedFolder } from '@/context/folders'
+import { isStubSeed } from '@/seed-marker'
 
 /** Checkpoints quoted from `standards/context.md`. Neither is a cap. */
 export const LENGTH_CHECKPOINT = 150
@@ -166,6 +167,12 @@ export interface EntryReport {
    * is `missingSections`, since one entry answers for its siblings.
    */
   readonly sections: readonly string[]
+  /**
+   * Whether the file declares itself a skeleton, which excludes it from the
+   * section check alone. Every other measure still reads it, since a stub is
+   * exempt from owing sections rather than from being well formed.
+   */
+  readonly stub: boolean
 }
 
 export interface SectionFinding {
@@ -544,6 +551,7 @@ export function measureEntry(
     provenance: governsContent ? provenance(lines) : [],
     heavyBullets: governsContent ? heavyBullets(lines) : [],
     sections: governsContent ? declaredSections(lines) : [],
+    stub: isStubSeed(source),
   }
 }
 
@@ -615,9 +623,15 @@ export function missingSections(
   for (const folder of folders) {
     if (!governsContent(folder) || folder.entries.length === 0) continue
 
+    // A stub owes no sections, so it is dropped before either branch rather
+    // than inside them. Leaving one in the split-folder aggregate would let a
+    // skeleton answer for the siblings that do owe the sections.
     const reports = folder.entries
       .map((path) => byRel.get(relative(root, path)))
       .filter((entry) => entry !== undefined)
+      .filter((entry) => !entry.stub)
+
+    if (reports.length === 0) continue
 
     if (folder.nested) {
       const missing = shortOf(reports.flatMap((entry) => entry.sections))

package/src/context/gate.ts

@@ -0,0 +1,43 @@
+import type { SectionFinding } from '@/context/audit'
+import type { FolderDrift } from '@/context/index-drift'
+
+export interface GateInput {
+  /** Cited paths that resolved to nothing, which gate under either mode. */
+  readonly unresolvedCitations: number
+  readonly sections: readonly SectionFinding[]
+  readonly drift: readonly FolderDrift[]
+  /**
+   * Whether the caller asked for the widened gate. False leaves a missing
+   * section and a drifted index advisory, which is what the project-root stage
+   * runs so a judgment threshold never fails a push.
+   */
+  readonly widened: boolean
+}
+
+/** Whether any folder disagrees with its own index. */
+export function hasDrift(drift: readonly FolderDrift[]): boolean {
+  return drift.some(
+    (folder) => folder.unlisted.length > 0 || folder.missing.length > 0,
+  )
+}
+
+/**
+ * Whether the audit found something that should fail the caller.
+ *
+ * An unresolved citation is a broken pointer and gates unconditionally. The two
+ * findings `--gate` adds are the ones answerable from the file itself: a
+ * required section it does not declare, and an index disagreeing with its
+ * folder. Length, depth, bullet, table, and provenance findings are thresholds
+ * a reader weighs, so they stay out under both modes.
+ */
+export function isGating({
+  unresolvedCitations,
+  sections,
+  drift,
+  widened,
+}: GateInput): boolean {
+  if (unresolvedCitations > 0) return true
+  if (!widened) return false
+
+  return sections.length > 0 || hasDrift(drift)
+}

package/src/seed-marker.ts

@@ -0,0 +1,74 @@
+/**
+ * The frontmatter field exempting a seed from the section check the seed gate
+ * runs.
+ *
+ * The check has a false-positive class its own comment records: a standard may
+ * sanction omitting a section, and no measure separates that from a file that
+ * forgot it. Reporting is the right response in a live project, where the
+ * finding is advisory. The seed gate promotes the same finding to a failing
+ * exit code, so the seed tree needs a way to say the omission is deliberate.
+ */
+export const SEED_STUB_FIELD = 'stub'
+
+/**
+ * Whether an install rewrites this seed rather than copying it byte for byte.
+ *
+ * This answers what the caller branches on and not whether the file holds a
+ * marker, which is `isStubSeed` reading content. Only markdown carries
+ * frontmatter, so only markdown can hold one, and the extension decides the
+ * copy path without opening the file. Every install path and the drift report
+ * ask this one question, or the report compares a marked source against a
+ * stripped target and reads a seed nobody touched as drifted.
+ */
+export function rewritesOnInstall(src: string): boolean {
+  return src.endsWith('.md')
+}
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---(\n|$)/
+const STUB_LINE = new RegExp(`^${SEED_STUB_FIELD}:[ \\t]*true[ \\t]*$`, 'm')
+
+/**
+ * Whether the source declares itself a skeleton for the target to fill.
+ *
+ * Only `true` counts. A field set to anything else reads as a seed that meant
+ * to turn the exemption off, and treating an unparsed value as exempt would
+ * make a typo silence the gate.
+ */
+export function isStubSeed(source: string): boolean {
+  const block = source.match(FRONTMATTER)
+  if (!block) return false
+
+  return STUB_LINE.test(block[1])
+}
+
+/**
+ * Removes the marker so it reaches no target.
+ *
+ * The field is toolkit bookkeeping about the seed tree, and a project that
+ * received it would carry a field its own tooling never reads. A file whose
+ * frontmatter holds nothing else loses the block entirely rather than keeping
+ * an empty one.
+ */
+export function stripSeedMarker(source: string): string {
+  const block = source.match(FRONTMATTER)
+  if (!block) return source
+
+  const kept = block[1]
+    .split('\n')
+    .filter((line) => !STUB_LINE.test(line))
+    .join('\n')
+
+  // A function replacement, because a string one reads `$1` and `$&` in the
+  // kept fields as references to this match. A `description` naming a dollar
+  // amount would otherwise substitute the whole frontmatter into itself and
+  // carry the marker along with it.
+  if (kept.trim() !== '') {
+    const replacement = `---\n${kept}\n---${block[2] ?? ''}`
+    return source.replace(FRONTMATTER, () => replacement)
+  }
+
+  // Dropping the block takes the blank line that separated it from the body
+  // with it. Leaving that behind opens the installed file on whitespace, which
+  // is a diff every target would carry against its own formatter.
+  return source.slice(block[0].length).replace(/^\n+/, '')
+}

package/src/sync/seeds-report.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs'
 import { relative } from 'node:path'
 import { planSeeds, type Seed } from '@/claude/seeds'
+import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
 import { findInstalledOrigin, readHistoryIndex } from '@/sync/history'
 
 /**
@@ -106,6 +107,20 @@ function attribute(
   return false
 }
 
+/**
+ * Compares the target against what an install would write, not against the seed
+ * source. The two differ for a markdown seed carrying the stub marker, which the
+ * install strips, so comparing sources would report a file the target never
+ * touched as drifted for as long as the marker stays set.
+ */
 function sameContent(source: string, dest: string): boolean {
-  return readFileSync(source).equals(readFileSync(dest))
+  const installed = readFileSync(dest)
+
+  if (!rewritesOnInstall(source)) {
+    return readFileSync(source).equals(installed)
+  }
+
+  return (
+    stripSeedMarker(readFileSync(source, 'utf8')) === installed.toString('utf8')
+  )
 }

package/src/tooling/inject.ts

@@ -10,6 +10,7 @@ import {
 import { dirname, join } from 'node:path'
 import { $ } from 'bun'
 import { copyPreservingMode } from '@/copy'
+import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
 import { mergeSections, pruneSections } from '@/tooling/gitignore'
 import { ancestorsFirst, listFiles, type Manifest } from '@/tooling/manifest'
 import {
@@ -44,6 +45,21 @@ export async function injectConfigs(
   return applied
 }
 
+/**
+ * Writes a seed to a target that does not have it, dropping the stub marker on
+ * the way. The marker is toolkit bookkeeping read by the seed gate, so a target
+ * receiving it would carry a field its own tooling never reads. Only markdown
+ * carries frontmatter, and every other seed copies byte for byte.
+ */
+async function writeSeed(src: string, dest: string): Promise<void> {
+  if (!rewritesOnInstall(src)) {
+    await copyFile(src, dest)
+    return
+  }
+
+  await writeFile(dest, stripSeedMarker(await readFile(src, 'utf8')))
+}
+
 /**
  * Copies a seed when the target lacks it. When the target already has one and
  * the seed is a `.txt` word list, missing lines are appended and the file is
@@ -53,7 +69,7 @@ async function mergeSeedFile(src: string, dest: string): Promise<void> {
   await mkdir(dirname(dest), { recursive: true })
 
   if (!existsSync(dest)) {
-    await copyFile(src, dest)
+    await writeSeed(src, dest)
     return
   }