@erclx/aitk 0.108.0 → 0.110.0

package/src/audits/run.ts

@@ -0,0 +1,202 @@
+import { join } from 'node:path'
+import { execa } from 'execa'
+import type { Delta } from '@/audits/baseline'
+import { type AuditResult, type AuditSpec, classify } from '@/audits/catalog'
+import { gitEnv } from '@/git-env'
+import { PROJECT_ROOT } from '@/project-root'
+
+/** At least one audit reported a finding that is a fact. */
+export const EXIT_FINDING = 2
+
+/** At least one audit did not report, so the run measured less than the set. */
+export const EXIT_UNMEASURED = 3
+
+export type Verdict =
+  /** Every audit reported and every count it produced was zero. */
+  | 'clean'
+  /** Every audit reported and at least one carries a judgment finding. */
+  | 'reported'
+  /** At least one audit carries a finding that is a fact. */
+  | 'findings'
+  /** At least one audit did not report, so this is not a pass. */
+  | 'incomplete'
+
+export interface SpawnResult {
+  readonly exitCode: number
+  readonly stdout: string
+}
+
+export type Spawn = (spec: AuditSpec) => Promise<SpawnResult>
+
+/**
+ * Runs each verb out of the checkout this CLI is executing from.
+ *
+ * `process.execPath` and the resolved `cli.ts` rather than a bare `aitk`, for
+ * the reason `verify.sh` already names: a globally installed binary resolves to
+ * the main checkout no matter which worktree is running, so the aggregate would
+ * measure the wrong tree and report a pass over a branch it never read.
+ *
+ * `reject: false` because a findings exit is the ordinary outcome for half of
+ * these verbs, and a throw there would be an error path for a working check.
+ */
+export function spawnAudit(root: string): Spawn {
+  const cli = join(PROJECT_ROOT, 'src', 'cli.ts')
+
+  return async (spec) => {
+    const result = await execa(process.execPath, [cli, ...spec.argv], {
+      cwd: root,
+      reject: false,
+      // `gitEnv` already returns the whole ambient environment minus git's
+      // resolution variables, so it replaces the environment rather than
+      // extending it. Spreading `process.env` alongside would put back the very
+      // variables it strips, and a hook's `GIT_DIR` would then point every
+      // history-reading verb at a repository nobody asked about.
+      env: { ...gitEnv(), AITK_NON_INTERACTIVE: '1' },
+      extendEnv: false,
+    })
+
+    return { exitCode: result.exitCode ?? 1, stdout: result.stdout }
+  }
+}
+
+/**
+ * Runs every audit and reads each one's own record shape.
+ *
+ * The verbs walk separate trees and share no state, so they run together
+ * rather than in sequence. Serially, the aggregate would be the slowest thing
+ * in the verify pipeline for no reason beyond the order they were written in.
+ *
+ * A spawn that throws becomes an `unmeasured` result rather than a rejection.
+ * One absent binary would otherwise take the whole aggregate down and report
+ * nothing about the audits that did run.
+ */
+export async function runAudits(
+  specs: readonly AuditSpec[],
+  spawn: Spawn,
+): Promise<AuditResult[]> {
+  return Promise.all(
+    specs.map(async (spec) => {
+      try {
+        const { exitCode, stdout } = await spawn(spec)
+        return classify(spec, exitCode, stdout)
+      } catch (error) {
+        return {
+          id: spec.id,
+          label: spec.label,
+          status: 'unmeasured' as const,
+          tracked: spec.corpus === 'tracked',
+          exitCode: 1,
+          reason: `could not be started: ${error instanceof Error ? error.message : String(error)}`,
+        }
+      }
+    }),
+  )
+}
+
+/**
+ * The single verdict over the set.
+ *
+ * `incomplete` outranks a quiet set on purpose. An aggregate reporting a pass
+ * over a tree it did not finish measuring is the failure this whole command
+ * exists against, and an empty set takes it for the same reason: nothing ran,
+ * so nothing passed.
+ *
+ * An `absent` per-machine corpus does not reach it. That folder is gitignored
+ * and missing on every fresh clone, so folding it in would pin the verdict at
+ * `incomplete` on every CI run and leave the word meaning nothing.
+ */
+export function verdictOf(results: readonly AuditResult[]): Verdict {
+  if (results.length === 0) return 'incomplete'
+  if (results.some((result) => result.status === 'finding')) return 'findings'
+  if (results.some((result) => result.status === 'unmeasured')) {
+    return 'incomplete'
+  }
+  if (results.some((result) => result.status === 'reported')) return 'reported'
+  return 'clean'
+}
+
+/**
+ * Exits non-zero only on a fact, which is the split this aggregate inherits
+ * rather than moves. A growing judgment count reports as a delta and fails
+ * nothing, because the standards behind those measures set no hard cap.
+ *
+ * An audit that did not report takes its own code rather than the findings one.
+ * The two mean opposite things to whoever reads the exit: a fact is a defect in
+ * the tree, and an unmeasured audit is a defect in the run.
+ */
+export function exitCodeFor(results: readonly AuditResult[]): number {
+  const verdict = verdictOf(results)
+  if (verdict === 'findings') return EXIT_FINDING
+  if (verdict === 'incomplete') return EXIT_UNMEASURED
+  return 0
+}
+
+export interface Summary {
+  readonly verdict: Verdict
+  /** Audits that reported, out of the whole set. */
+  readonly audited: number
+  /** Audits carrying a finding that is a fact. */
+  readonly facts: number
+  /** Audits that did not report at all. */
+  readonly unmeasured: number
+  /**
+   * Audits whose per-machine folder is not on this disk.
+   *
+   * Published rather than folded into `audited`, so a run stating twelve
+   * audits never implies twelve corpora were read.
+   */
+  readonly absent: number
+  /** Tracked counts that rose against the recorded floor. */
+  readonly grown: number
+  /** Tracked counts that fell against the recorded floor. */
+  readonly shrunk: number
+  /** Tracked audits with no recorded floor to compare against. */
+  readonly unrecorded: number
+}
+
+/**
+ * The flat reading a shell stage takes without parsing the nested record.
+ *
+ * Published rather than left to a consumer to derive, for the reason the
+ * context audit already gives about its own join: deriving it means restating
+ * which question each number answers, and one wrong restatement is growth
+ * reported against a measure that never moved. Every key here is unique across
+ * the whole record, so a grep for one reaches the top level alone.
+ */
+export function summarize(
+  results: readonly AuditResult[],
+  deltas: readonly Delta[],
+): Summary {
+  let grown = 0
+  let shrunk = 0
+  let unrecorded = 0
+
+  for (const delta of deltas) {
+    if (delta.kind === 'unrecorded') {
+      unrecorded += 1
+      continue
+    }
+    if (delta.kind !== 'compared') continue
+
+    for (const moved of delta.moved) {
+      if (moved.delta > 0) grown += 1
+      else shrunk += 1
+    }
+  }
+
+  const counting = (status: AuditResult['status']) =>
+    results.filter((result) => result.status === status).length
+
+  return {
+    verdict: verdictOf(results),
+    audited: results.filter(
+      (result) => result.status !== 'unmeasured' && result.status !== 'absent',
+    ).length,
+    facts: counting('finding'),
+    unmeasured: counting('unmeasured'),
+    absent: counting('absent'),
+    grown,
+    shrunk,
+    unrecorded,
+  }
+}

package/src/cli.ts

@@ -27,6 +27,7 @@ import { register as context } from '@/commands/context'
 import { register as markdown } from '@/commands/markdown'
 import { register as records } from '@/commands/records'
 import { register as sessions } from '@/commands/sessions'
+import { register as audits } from '@/commands/audits'
 import { PROJECT_ROOT } from '@/project-root'
 
 const GREY = '\x1b[0;90m'
@@ -63,6 +64,7 @@ function showHelp(): void {
     `${GREY}│${NC}    markdown [cmd]     ${GREY}# Report markdown against the attribute standards (audit)${NC}`,
     `${GREY}│${NC}    records [cmd]      ${GREY}# Session records under .claude/ (validate, push, pull)${NC}`,
     `${GREY}│${NC}    sessions [cmd]     ${GREY}# Resolve live sessions to worktree and branch (list)${NC}`,
+    `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
     `${GREY}│${NC}`,
     `${GREY}│${NC}  ${WHITE}Sandbox:${NC}`,
     `${GREY}│${NC}    aitk sandbox             ${GREY}# Interactive scenario picker${NC}`,
@@ -101,6 +103,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk records validate plans`,
     `${GREY}│${NC}    aitk records push --json`,
     `${GREY}│${NC}    aitk sessions list --json`,
+    `${GREY}│${NC}    aitk audits run --json`,
     `${GREY}└${NC}`,
   ]
   console.log(lines.join('\n'))
@@ -159,5 +162,6 @@ context(program)
 markdown(program)
 records(program)
 sessions(program)
+audits(program)
 
 program.parse()

package/src/commands/audits.ts

@@ -0,0 +1,342 @@
+import { execa } from 'execa'
+import type { Command } from 'commander'
+import {
+  BASELINE_REL,
+  type Baseline,
+  baselineFrom,
+  compareBaseline,
+  type Delta,
+  readBaseline,
+  writeBaseline,
+} from '@/audits/baseline'
+import { AUDITS, type AuditResult } from '@/audits/catalog'
+import {
+  exitCodeFor,
+  runAudits,
+  spawnAudit,
+  type Summary,
+  summarize,
+} from '@/audits/run'
+import { gitEnv } from '@/git-env'
+import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+import { currentWorktreeRoot } from '@/worktree'
+
+interface RunCommandOptions {
+  readonly json?: boolean
+  readonly record?: boolean
+  readonly root?: string
+}
+
+interface ListCommandOptions {
+  readonly json?: boolean
+}
+
+export function register(program: Command): void {
+  const audits = program
+    .command('audits')
+    .description('Run every health check this repository owns as one set')
+    .helpOption('-h, --help', 'Show this help message')
+
+  audits
+    .command('run')
+    .description(
+      'Run every audit, report per check under one verdict, and compare each count to the recorded baseline',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--root <path>',
+      'Tree to measure, defaulting to the current worktree',
+    )
+    .option(
+      '--record',
+      `Write this run's tracked counts to ${BASELINE_REL} as the new baseline`,
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  every audit reported and none carried a finding that is a fact',
+        '  1  refused, with the reason on stderr',
+        '  2  an audit carries a finding that is a fact',
+        '  3  an audit did not report, so the run measured less than the set',
+        '',
+        'It gates on exactly what already gates a push and on nothing new:',
+        'an unresolved context citation, a banned character, word, or spelling,',
+        'and a skill folder carrying no REQUIREMENT.md. Every other measure is a',
+        'judgment a reader settles, and failing a push on one teaches',
+        'contributors to route around the stage.',
+        '',
+        'Exit 3 is a defect in the run rather than in the tree. An aggregate that',
+        'reports a pass over a set it did not finish measuring is the failure this',
+        'command exists against, so a verb that did not report takes its own code.',
+        '',
+        `The baseline at ${BASELINE_REL} holds the counts from the last recorded`,
+        'run, so a measure that reports rather than gates still costs something',
+        'when it grows. Only a tracked corpus is retained: a gitignored record',
+        "folder holds one machine's scratch, and its counts answer nobody else.",
+        '',
+        'Examples:',
+        '  aitk audits run',
+        '  aitk audits run --json',
+        '  aitk audits run --record',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RunCommandOptions) => {
+      process.exitCode = await runAll(opts)
+    })
+
+  audits
+    .command('list')
+    .description(
+      'List every audit this command runs and what each one gates on',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit JSON with the id, invocation, corpus, and gate')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the catalog was listed',
+        '',
+        'Examples:',
+        '  aitk audits list',
+        '  aitk audits list --json',
+        '',
+      ].join('\n'),
+    )
+    .action((opts: ListCommandOptions) => {
+      process.exitCode = runList(opts)
+    })
+}
+
+function runList(opts: ListCommandOptions): number {
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        audits: AUDITS.map((audit) => ({
+          id: audit.id,
+          label: audit.label,
+          command: `aitk ${audit.argv.join(' ')}`,
+          corpus: audit.corpus,
+          gates: audit.gatingExits.length > 0,
+        })),
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('aitk audits list')
+  for (const audit of AUDITS) {
+    logStep(audit.label)
+    logInfo(`aitk ${audit.argv.join(' ')}`)
+    logInfo(
+      `${audit.corpus} corpus, ${audit.gatingExits.length > 0 ? 'gates on a fact' : 'reports only'}`,
+    )
+  }
+  outro()
+  return 0
+}
+
+/**
+ * The day a record is stamped with, as `YYYY-MM-DD`.
+ *
+ * Local rather than UTC, because the stamp is read beside a commit date in a
+ * context entry and a run taken in the evening should not record tomorrow.
+ */
+function today(): string {
+  const now = new Date()
+  return [
+    now.getFullYear(),
+    String(now.getMonth() + 1).padStart(2, '0'),
+    String(now.getDate()).padStart(2, '0'),
+  ].join('-')
+}
+
+/**
+ * The commit the counts were read at, or `unknown` outside a repository.
+ *
+ * A target project can install this CLI without a git history behind it, and
+ * refusing there would withhold the whole report over a field that only makes
+ * the record reproducible.
+ */
+async function headCommit(root: string): Promise<string> {
+  const result = await execa('git', ['-C', root, 'rev-parse', 'HEAD'], {
+    reject: false,
+    env: gitEnv(),
+    extendEnv: false,
+  })
+  return result.exitCode === 0 ? result.stdout.trim() : 'unknown'
+}
+
+async function runAll(opts: RunCommandOptions): Promise<number> {
+  const emitJson = opts.json ?? false
+  const root = opts.root ?? (await currentWorktreeRoot())
+
+  let baseline: Baseline | undefined
+  try {
+    baseline = await readBaseline(root)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    if (emitJson) {
+      process.stderr.write(`${message}\n`)
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: 'bad-baseline', message })}\n`,
+      )
+      return 1
+    }
+    intro('aitk audits run')
+    logStep('Refused')
+    logError(message)
+    outro()
+    return 1
+  }
+
+  const results = await runAudits(AUDITS, spawnAudit(root))
+  const deltas = compareBaseline(baseline, results)
+  const summary = summarize(results, deltas)
+
+  let recorded: string | undefined
+  if (opts.record) {
+    const next = baselineFrom(results, {
+      recordedAt: today(),
+      commit: await headCommit(root),
+    })
+    recorded = await writeBaseline(root, next)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        // Flat scalars, so a shell stage greps one out without a JSON parser.
+        // The nested arrays below carry the detail behind each number.
+        summary,
+        baseline: baseline
+          ? { recordedAt: baseline.recordedAt, commit: baseline.commit }
+          : undefined,
+        recorded,
+        audits: results,
+        deltas,
+      })}\n`,
+    )
+  } else {
+    report(results, deltas, baseline, recorded, summary)
+  }
+
+  return exitCodeFor(results)
+}
+
+/** The counts of one result, rendered as `key n` pairs a reader can scan. */
+function countLine(counts: Record<string, number>): string {
+  return Object.entries(counts)
+    .map(([key, value]) => `${key} ${value}`)
+    .join(', ')
+}
+
+/**
+ * The delta line for one audit, or nothing when there is no comparison to
+ * report. A first run says so rather than showing a delta of zero, since zero
+ * against an absent baseline says the same as a corpus that did not move.
+ */
+function deltaLine(delta: Delta): string | undefined {
+  if (delta.kind === 'per-machine' || delta.kind === 'unmeasured') {
+    return undefined
+  }
+  if (delta.kind === 'unrecorded') return 'No recorded baseline to compare'
+
+  const parts = [
+    ...delta.moved.map(
+      ({ key, from, to, delta: moved }) =>
+        `${key} ${from} to ${to} (${moved > 0 ? '+' : ''}${moved})`,
+    ),
+    ...delta.added.map(({ key, to }) => `${key} ${to}, newly measured`),
+    ...delta.dropped.map(({ key, from }) => `${key} was ${from}, not measured`),
+  ]
+
+  return parts.length === 0 ? undefined : parts.join(', ')
+}
+
+function report(
+  results: readonly AuditResult[],
+  deltas: readonly Delta[],
+  baseline: Baseline | undefined,
+  recorded: string | undefined,
+  summary: Summary,
+): void {
+  const byId = new Map(deltas.map((delta) => [delta.id, delta]))
+
+  intro('aitk audits run')
+
+  logStep('Baseline')
+  if (baseline === undefined) {
+    logWarn(`None recorded. Take one with aitk audits run --record.`)
+  } else {
+    logInfo(`${baseline.recordedAt} at ${baseline.commit.slice(0, 8)}`)
+  }
+
+  for (const result of results) {
+    logStep(result.label)
+
+    if (result.status === 'absent') {
+      logInfo(`No corpus on this machine: ${result.reason ?? 'not found'}`)
+      continue
+    }
+
+    if (result.status === 'unmeasured') {
+      logWarn(`Did not report: ${result.reason ?? 'no reason given'}`)
+      continue
+    }
+
+    const counts = result.counts ?? {}
+    const line = countLine(counts)
+    if (result.status === 'finding') {
+      logError(line === '' ? 'A finding that is a fact' : line)
+    } else {
+      logInfo(line === '' ? 'Reported' : line)
+    }
+
+    if (!result.tracked) {
+      logInfo('Per-machine corpus, so no baseline is kept')
+      continue
+    }
+
+    const moved = deltaLine(
+      byId.get(result.id) ?? { id: result.id, kind: 'unrecorded' },
+    )
+    if (moved !== undefined) logInfo(moved)
+  }
+
+  if (recorded !== undefined) {
+    logStep('Recorded')
+    logInfo(recorded)
+  }
+
+  logStep('Verdict')
+
+  if (summary.verdict === 'findings') {
+    logError(
+      `${plural(summary.facts, 'audit')} carrying a finding that is a fact. Fix what each names.`,
+    )
+  } else if (summary.verdict === 'incomplete') {
+    logError(
+      `${plural(summary.unmeasured, 'audit')} did not report, so this run measured less than the set.`,
+    )
+  } else if (summary.verdict === 'reported') {
+    logInfo('No fact. Every other finding is a judgment a reader settles.')
+  } else {
+    logInfo('Every audit reported and every count is zero.')
+  }
+
+  // Stated on every run, including a clean one. A count of what passed reads as
+  // a verdict on the whole set unless the run also says what it never reached.
+  logInfo(
+    `${summary.audited} of ${results.length} corpora measured, ${summary.absent} absent on this machine`,
+  )
+
+  outro()
+}

package/standards/requirements.md

@@ -14,7 +14,7 @@ Governs the product-scope document at `.claude/REQUIREMENTS.md`: problem, goals,
 Does not govern:
 
 - Rationale for a technical choice: `architecture.md`
-- Sequencing the scope into ordered versions: `roadmap.md`
+- Execution order across the work the scope generates: `tasks.md`
 - Per-domain structure and narrative: `context.md`
 
 ## What goes in
@@ -39,7 +39,7 @@ Use `## Problem`, `## Goals`, `## Non-goals`, `## MVP features`, `## Tech stack`
 
 The MVP list is a historical record of the original scope. Once those features ship it stays as written. Do not renumber it, do not append to it, and do not annotate entries with status. A reader telling the original scope apart from what followed depends on the first one staying legible.
 
-Later scope arrives as a new section rather than as an extension of the MVP list. Name the section for what it delivers and state its entries as outcomes, the same way the goals are stated. A roadmap sequences the MVP list alone, so a later scope section is sequenced by a fresh pass rather than folded into the roadmap that already shipped. The roadmap standard sends a project here once its last version ships, and this is the pass it means.
+Later scope arrives as a new section rather than as an extension of the MVP list. Name the section for what it delivers and state its entries as outcomes, the same way the goals are stated. Nothing sequences either list into versions. Work reaches the board as discrete tasks under `tasks.md`, which orders them by readiness, so a section here states what is wanted and never when it lands.
 
 ## Distribution
 

package/standards/tasks.md

@@ -19,7 +19,6 @@ Does not govern:
 
 - The plan file a task cites, its sections, and its answer contract: `plan.md`
 - Phase-label format and which surfaces a label may appear on: `versioning.md`
-- Sequencing across versions and why the order is what it is: `roadmap.md`
 - Architectural reasoning that outlives a task: `architecture.md`
 - The pre-compaction handoff sitting in the folder, its filename and its sections: `session.md`
 - When a project opens a task at all, which is project policy rather than a shape rule
@@ -52,7 +51,9 @@ The `claude-tasks` skill creates and archives task files. `claude-docs` marks ou
 
 ## Ordering
 
-`priority.md` carries execution order and what each task is waiting on. The generated index sorts by filename and says nothing about order, so without this file board state gets reconstructed by hand every session. Why one version sequences against another belongs in `.claude/ROADMAP.md`, which is committed because that rationale has no substitute record. Why a row sits where it does inside its group is stated on the row itself, in the column that already carries what the task is waiting on.
+`priority.md` carries execution order and what each task is waiting on. The generated index sorts by filename and says nothing about order, so without this file board state gets reconstructed by hand every session. Why a row sits where it does inside its group is stated on the row itself, in the column that already carries what the task is waiting on, one line per row.
+
+That cell is the only home sequencing rationale has. Rationale spanning several rows, why one group of work runs before another, is carried by nothing and reaches a later session only through whoever remembers it. Naming the gap is deliberate: a second document holding it would be the version-sequencing surface this board replaced, and a row already states what it waits on, which is the part of the reasoning a reader acts on.
 
 Group tasks by readiness rather than by status, one row per task, under the columns each group fixes below. Keep it to links and blockers: tables, plus at most one sentence per section. A paragraph in `priority.md` is a defect whatever it says. Stating the shape this way is what lets a single diff fail, since a size cap only trips after the fact and every addition looks defensible on its own.
 
@@ -240,7 +241,7 @@ The line is what lets a merge close its own task. Every merge on `main` is a squ
 - Architectural reasoning that outlives the task. A finding explains why this task is shaped as it is. A decision the system keeps after the task closes belongs in `.claude/ARCHITECTURE.md`.
 - Narrative of the session that produced the task. A finding states what constrains the task, so what was probed, what it cost, and who decided belongs in the groundwork folder the `Groundwork:` line names. A task with no groundwork folder cuts the narrative rather than relocating it, since the board is not the fallback destination for it.
 - "In progress" or "Blocked" headings. Note status inline on the outcome instead.
-- Sequencing rationale or which version is active. Why this task is planned before its neighbors goes on its row in `priority.md`, in the cell that already carries what it is waiting on. Why one version sequences against another belongs in `.claude/ROADMAP.md`, which is committed because that reasoning has no substitute record.
+- Sequencing rationale or which version is active. Why this task is planned before its neighbors goes on its row in `priority.md`, in the cell that already carries what it is waiting on. Rationale wider than one row has no home at all, so cut it rather than filing it here.
 
 ## Archiving
 

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

@@ -1,41 +0,0 @@
----
-name: claude-roadmap
-description: Why versions are sequenced from the MVP list alone, what makes a version a usable increment, and the lifecycle gate that stops a second pass
----
-
-# Claude roadmap requirement
-
-## Gap
-
-Without this skill, versions are invented from a sense of what should come next rather than sequenced from the scope the requirements already fixed. Each one reads as a milestone nobody can use, because the ordering follows what feels foundational instead of what a user can then do, and a version that de-risks nothing sits ahead of the subsystem the whole plan rests on. The roadmap then drifts into task-level steps, which duplicates the plan folder and goes stale the first time a file moves.
-
-An update is where the file quietly breaks. Rewriting rows that never changed hides the one line that moved, so a reader diffing the roadmap learns nothing from it. And a project whose MVP already shipped gets its later scope sequenced here, which puts a fresh requirements pass's work into a file that only ever sequenced the MVP.
-
-## Must
-
-- Sequence from the MVP list in the requirements file and name it as the source
-- Make every version a usable increment, stated as what the user can then do
-- Order by dependency and by de-risking, placing an unproven subsystem inside the version that first needs it
-- Preserve rows that still hold when updating, resequencing or splitting only where scope shifted
-- Follow the reference for the document shape and version format rather than inventing one
-- Report which versions changed on an update
-
-## Must not
-
-- Break a version into task-level steps or a file list
-- Rewrite a row that did not change
-- Sequence a later scope section without an explicit override from the caller
-- Stage or commit the file, which is tracked but belongs to the git skills
-
-## Guards
-
-- Requirements file absent or carrying no MVP features: stop, because there is nothing to sequence
-- A later scope section present after the MVP list: stop and name the override, since that scope belongs to a fresh requirements pass
-- Neither copy of the requirements standard resolves: draft without the lifecycle gate. Refusing on a rule that could not be read stops more than it protects.
-
-## Out of scope
-
-- Task-level steps and file lists, which `claude-feature` and the task board own
-- Writing the requirements being sequenced
-- Committing the file, which the git skills own
-- Deciding what to build next once the MVP list has shipped