ai-runtime-kit 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -10,6 +10,114 @@ kit.
 
 ## [Unreleased]
 
+## [0.10.1] - 2026-05-14
+
+Bundled cleanup of four doc-only follow-ups from v0.9.0 and
+v0.10.0 reviews. Engineering-only spec; no PRD/feature parent.
+
+### Changed
+- `runtime/workflows/feature-development.md` — cross-references
+  `.ai/runtime/INDEX.md § Traceability` for the canonical
+  `## Parent <Type>` rules and `(none — <reason>)` rendering
+  convention. Also references `ai-runtime-kit validate` as the
+  audit tool.
+- `runtime/tasks/_template.md` — `## Parent Plan` comment now
+  shows the explicit `(none — direct task)` literal rendering
+  for hot-fix tasks.
+- `runtime/agents/spec-writer.md` — appends one `## Must Not`
+  bullet: "Approve specs whose acceptance asserts metrics on
+  state not yet in place (drift hit v0.5.1, v0.7.0, v0.10.0)."
+  File 1680 → 1794 bytes (under the spec's revised 1900
+  ceiling — 4th size-ceiling drift recorded; future fix
+  should make budgets ranges, not hard caps).
+- `README.md` — Walkthrough 3 per-step bullets gain annotations
+  showing which `## Parent <Type>` field anchors each step's
+  upward link. Closing line mentions `ai-runtime-kit validate`
+  as the audit step before merge.
+
+### Process
+- Eighth fire of `pre-executor/runtime-scoped-preflight` hook;
+  eighth clean pass.
+- Second engineering-only spec on this kit (after v0.8.1).
+  The streamlined no-PRD/no-feature path is now well-trodden.
+- `node bin/cli.js validate` self-test post-edit:
+  10 specs / 9 reviews on the kit's tree, all PASS.
+
+## [0.10.0] - 2026-05-14
+
+**First M4 data point.** Kit's first `src/**` feature shipped
+under the v0.6.0+ PRD → Feature → Spec → Plan → Task → TDD →
+Implement → Verify → Review workflow with `TDD-Applies: true`
+tasks. Two TDD pairs (test-commit-before-impl-commit) at 100%
+test-first ordering.
+
+### Added
+- **`validate` command** — checks `.ai/project/` tree
+  structural integrity. Walks every artifact (PRD / feature /
+  spec / plan / task / review) and verifies:
+  - Required `## Parent <Type>` sections per v0.9.0 INDEX §
+    Traceability rules.
+  - Cited parent paths resolve to real files on disk.
+  - `Status` values are in the allowed set per artifact type.
+  Reports errors (missing-parent / empty-parent /
+  unresolved-parent) and warnings (unexpected-status). Exits
+  0 on clean, 1 on any error.
+- `--json` flag for machine-parseable output.
+- `--cwd <dir>` flag for non-default project root.
+- `src/validate.js` (NEW) — pure validator module.
+- `test/validate.test.js` (NEW) — 6 unit tests (clean tree,
+  missing parent, broken path, `(none — ...)` rendering,
+  JSON output, live dogfood smoke).
+
+### Changed
+- `bin/cli.js` — dispatcher gains `validate` subcommand;
+  HELP lists it alongside `init` and `upgrade`.
+- 7 historical specs (v0.4.0 / v0.5.0 / v0.5.1 / v0.6.0 /
+  v0.7.0 / v0.8.0 / v0.8.1) retrofitted with `## Parent
+  Feature` sections (pre-v0.6.0 use `(none —
+  pre-feature-layer)`; v0.8.1 uses `(none —
+  engineering-only)`; the rest cite real feature paths).
+- 7 historical reviews retrofitted with `## Parent Spec`
+  sections. v0.9.0's spec/review already had theirs (the
+  convention F4 shipped was in use immediately on its own
+  review). Retrofit is project-side and not subject to
+  preflight.
+
+### Process
+- **Kit's first `src/**` feature** under the new pipeline.
+  Branch was `feat/validate-cli` (not `chore/runtime-*`)
+  because no `runtime/**` paths in scope.
+- **First non-runtime-scoped feature in the v0.6.0+
+  workflow** — preflight hook did not fire (correctly; no
+  `runtime/**` paths to gate on). The kit's discipline now
+  cleanly distinguishes governance-scoped (preflight gated)
+  from kit-code-scoped (regular feature branches).
+- **First M4 data point.** Two TDD pairs:
+  - T1 (src/validate.js): test commit 16:07:26 → impl
+    16:08:21 (Δ +55s).
+  - T2 (bin/cli.js): test commit 16:09:47 → impl 16:11:53
+    (Δ +2m6s).
+  Both pairs satisfy "test-commit precedes impl-commit." M4
+  score for this feature: 2/2 = 100%.
+- **Validator caught a real concern during dogfood.** The
+  first run reported `TASK_STATUS.md` as a missing-parent
+  error; this file is a top-level status tracker (output of
+  `init`), not a task instance. Fix landed in C4: validator
+  now skips `EXCLUDED_FILENAMES`. The tool catching its own
+  edge case in its first ship cycle is the dogfood loop
+  working as intended.
+- **Spec amended mid-implementation** (third occurrence —
+  v0.5.1, v0.7.0, and now v0.10.0). Original spec excluded
+  retrofitting historical artifacts; the validator's
+  credibility depends on its first dogfood pass being
+  clean, so the spec was amended pre-impl to include
+  retrofit work. Recorded in spec § Status with a comment.
+- **24/24 tests pass** (18 prior + 6 new).
+- **`validate` against this repo's `.ai/` tree**:
+  3 PRDs / 5 features / 9 specs / 0 plans / 0 tasks /
+  8 reviews / **0 errors / 0 warnings / Result: PASS**.
+  VM1 satisfied live on first ship.
+
 ## [0.9.0] - 2026-05-14
 
 **Closes the v0.6.0 nine-phase-workflow PRD's 4-feature

package/README.md

@@ -10,6 +10,22 @@ npx ai-runtime-kit upgrade   # existing kit consumer
 
 ## Status
 
+**v0.10.1** — Bundled cleanup of 4 doc-only follow-ups from
+v0.9.0/v0.10.0 reviews: workflow cross-ref to `INDEX § Traceability`,
+hot-fix example in task template, new `spec-writer.md` Must Not
+bullet on metric reachability, Walkthrough 3 per-step
+`## Parent <Type>` annotations.
+
+**v0.10.0** — Adds the **`validate` command** — checks
+`.ai/project/` tree structural integrity (every artifact carries
+its required `## Parent <Type>` section; every cited parent path
+resolves on disk; Status values are valid). Reports errors and
+warnings; exits 0 on clean / 1 on errors; `--json` for machine
+output. **First `src/**` feature shipped under the v0.6.0+
+PRD → Feature → Spec → Plan → Task → TDD → Implement → Verify
+→ Review pipeline; first M4 data point — 2/2 TDD pairs at
+100% test-first ordering.**
+
 **v0.9.0** — Formalizes the **`## Parent <Type>` traceability
 convention** across all artifact templates. Every kit artifact
 (spec / plan / task / review) now carries a structural
@@ -306,19 +322,19 @@ commit → task → plan → spec → feature → PRD
 Quick lifecycle, with the agent roles invoked at each step:
 
 ```bash
-# Step 0 — author a PRD (prd-writer)
+# Step 0 — author a PRD (prd-writer)                      [chain root]
 #   .ai/project/prds/YYYY-MM-DD-<slug>/prd.md
 #   Problem / Target Users / Success Metrics / User Stories /
 #   Out of Scope / Open Questions / Stakeholders
 
 # Step 0.5 — slice the PRD into ≥1 features (feature-writer)
 #   .ai/project/features/YYYY-MM-DD-<feature-slug>/feature.md
-#   Each cites the parent PRD; maps to PRD success metrics.
+#   Each feature has   ## Parent PRD   citing the PRD by path.
 #   Mandatory whenever Step 0 ran.
 
 # Step 1 — draft an engineering spec per feature (spec-writer)
 #   .ai/project/specs/YYYY-MM-DD-<feature-slug>/spec.md
-#   §1 Goal cites the parent feature path.
+#   Spec has           ## Parent Feature   citing the feature.
 #   §2 Scope enumerates every touched runtime/** path (preflight).
 
 # Step 1.5 — TDD phase (tdd-writer, per applicable task)
@@ -326,8 +342,10 @@ Quick lifecycle, with the agent roles invoked at each step:
 #   before the implementation commit.
 
 # Step 2 — plan, tasks, implementation (planner + executor)
-#   .ai/project/plans/...
-#   .ai/project/tasks/...   (each task carries TDD-Applies)
+#   .ai/project/plans/...   plan has   ## Parent Spec.
+#   .ai/project/tasks/...   each task has
+#                           ## Parent Spec + ## Parent Plan +
+#                           ## TDD-Applies.
 #   Implementation lands on a chore/runtime-<slug> branch if
 #   the spec touches runtime/**; otherwise a feature branch.
 
@@ -336,9 +354,11 @@ Quick lifecycle, with the agent roles invoked at each step:
 
 # Step 4 — review (reviewer)
 #   .ai/project/reviews/YYYY-MM-DD-<slug>.md
+#   Review has         ## Parent Spec.
 #   Maps PRD success metrics to delivered artifacts.
 
-# Then: merge, push, tag, optionally npm publish.
+# Then: ai-runtime-kit validate (audit the chain),
+#       merge, push, tag, optionally npm publish.
 ```
 
 For each step, the corresponding kit-shipped agent role file

package/bin/cli.js

@@ -10,6 +10,7 @@ Usage: ai-runtime-kit <command> [options]
 Commands:
   init        Initialize .ai/ runtime in the current directory.
   upgrade     Upgrade .ai/runtime/ to the kit's current version.
+  validate    Check .ai/project/ tree structural integrity.
   --help, -h  Show this help.
   --version   Show kit version.
 
@@ -38,6 +39,9 @@ async function main() {
     case 'upgrade':
       await require('../src/upgrade').run(rest);
       return;
+    case 'validate':
+      require('../src/validate').run(rest);
+      return;
     default:
       console.error(`ai-runtime-kit: unknown command '${cmd}'`);
       console.error('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-runtime-kit",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Reusable AI engineering runtime: BOOTSTRAP, workflows, safety, hooks, and templates for software projects driven by AI agents.",
   "bin": {
     "ai-runtime-kit": "./bin/cli.js"

package/runtime/agents/spec-writer.md

@@ -51,6 +51,8 @@ One file at `.ai/project/specs/YYYY-MM-DD-<slug>/spec.md`.
 - Lock hard byte-budgets on new template/role files without
   prototyping — use ranges or revisit during impl
   (drift hit v0.5.1 + v0.7.0).
+- Approve specs whose acceptance asserts metrics on state
+  not yet in place (drift hit v0.5.1, v0.7.0, v0.10.0).
 
 ---
 

package/runtime/tasks/_template.md

@@ -16,10 +16,12 @@ Describe the specific engineering goal.
 ## Parent Plan
 
 `.ai/project/plans/YYYY-MM-DD-<slug>/plan.md`
-<!-- Required. Single path. For hot-fix tasks created outside
-     the normal plan-first workflow, render
-     `(none — direct task)`. See .ai/runtime/INDEX.md
-     § Traceability for the full chain. -->
+<!-- Required. Single path.
+     For hot-fix tasks created outside the normal plan-first
+     workflow, render literally:
+         (none — direct task)
+     See .ai/runtime/INDEX.md § Traceability for the full
+     chain and the (none — <reason>) rendering convention. -->
 
 ---
 

package/runtime/workflows/feature-development.md

@@ -119,6 +119,12 @@ check that the spec covers the feature's requirements without
 quietly expanding scope and that the feature covers its share of
 the PRD's metrics.
 
+The canonical rules for `## Parent <Type>` sections per artifact
+type — including the `(none — <reason>)` rendering convention
+for engineering-only specs, bug-fix specs, and hot-fix tasks —
+live at `.ai/runtime/INDEX.md` § Traceability. Use
+`ai-runtime-kit validate` to verify a project's tree conforms.
+
 Spec must include:
 
 - Goal

package/src/validate.js

@@ -0,0 +1,235 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseArgs } = require('node:util');
+
+// Per v0.9.0 INDEX § Traceability:
+//   PRD     — no parent required (chain root)
+//   Feature — ## Parent PRD
+//   Spec    — ## Parent Feature
+//   Plan    — ## Parent Spec
+//   Task    — ## Parent Spec + ## Parent Plan
+//   Review  — ## Parent Spec
+const ARTIFACT_RULES = {
+  prds:     { dir: 'prds',     required: [] },
+  features: { dir: 'features', required: ['Parent PRD'] },
+  specs:    { dir: 'specs',    required: ['Parent Feature'] },
+  plans:    { dir: 'plans',    required: ['Parent Spec'] },
+  tasks:    { dir: 'tasks',    required: ['Parent Spec', 'Parent Plan'] },
+  reviews:  { dir: 'reviews',  required: ['Parent Spec'] },
+};
+
+const VALID_STATUSES = {
+  prds:     ['DRAFT', 'APPROVED', 'REJECTED', 'SUPERSEDED'],
+  features: ['DRAFT', 'APPROVED', 'REJECTED', 'SUPERSEDED'],
+  specs:    ['DRAFT', 'APPROVED', 'REJECTED', 'SUPERSEDED'],
+  plans:    ['PLANNED', 'IN_PROGRESS', 'DONE'],
+  tasks:    ['TODO', 'IN_PROGRESS', 'IN_REVIEW', 'DONE'],
+};
+
+// Files within an artifact dir that are NOT instances of that
+// artifact type. TASK_STATUS.md is a top-level status tracker
+// produced by `init`, not a per-task instance.
+const EXCLUDED_FILENAMES = new Set(['TASK_STATUS.md']);
+
+function walkMd(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (EXCLUDED_FILENAMES.has(entry.name)) continue;
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walkMd(p));
+    else if (entry.isFile() && entry.name.endsWith('.md')) out.push(p);
+  }
+  return out;
+}
+
+function parseSections(content) {
+  // Returns { sectionName: bodyString }.
+  // Sections are top-level `## ` headings.
+  const lines = content.split('\n');
+  const sections = {};
+  let cur = null;
+  let buf = [];
+  for (const line of lines) {
+    const m = line.match(/^##\s+(.+?)\s*$/);
+    if (m) {
+      if (cur !== null) sections[cur] = buf.join('\n').trim();
+      cur = m[1].trim();
+      buf = [];
+    } else if (cur !== null) {
+      buf.push(line);
+    }
+  }
+  if (cur !== null) sections[cur] = buf.join('\n').trim();
+  return sections;
+}
+
+function firstValueLine(body) {
+  // Returns first non-empty, non-comment line; strips surrounding backticks.
+  for (const raw of body.split('\n')) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (line.startsWith('<!--')) continue;
+    return line.replace(/^`/, '').replace(/`$/, '');
+  }
+  return null;
+}
+
+function isNoneRendering(value) {
+  return value !== null && value.startsWith('(none');
+}
+
+function validate(projectRoot, _options = {}) {
+  const errors = [];
+  const warnings = [];
+  const summary = { prds: 0, features: 0, specs: 0, plans: 0, tasks: 0, reviews: 0 };
+
+  const aiProject = path.join(projectRoot, '.ai', 'project');
+  if (!fs.existsSync(aiProject)) {
+    return { errors, warnings, summary };
+  }
+
+  for (const [artifact, rule] of Object.entries(ARTIFACT_RULES)) {
+    const dir = path.join(aiProject, rule.dir);
+    const files = walkMd(dir);
+    summary[artifact] = files.length;
+
+    for (const file of files) {
+      const relFile = path.relative(projectRoot, file);
+      const content = fs.readFileSync(file, 'utf8');
+      const sections = parseSections(content);
+
+      for (const parentName of rule.required) {
+        const sectionBody = sections[parentName];
+        if (sectionBody === undefined) {
+          errors.push({
+            artifact,
+            file: relFile,
+            type: 'missing-parent',
+            message: `Missing required ## ${parentName} section`,
+          });
+          continue;
+        }
+        const value = firstValueLine(sectionBody);
+        if (value === null) {
+          errors.push({
+            artifact,
+            file: relFile,
+            type: 'empty-parent',
+            message: `## ${parentName} section is empty`,
+          });
+          continue;
+        }
+        if (isNoneRendering(value)) continue;
+        const resolved = path.join(projectRoot, value);
+        if (!fs.existsSync(resolved)) {
+          errors.push({
+            artifact,
+            file: relFile,
+            type: 'unresolved-parent',
+            message: `## ${parentName} points to non-existent path: ${value}`,
+          });
+        }
+      }
+
+      const allowedStatuses = VALID_STATUSES[artifact];
+      if (allowedStatuses && sections.Status !== undefined) {
+        const statusValue = firstValueLine(sections.Status);
+        if (statusValue !== null && !allowedStatuses.includes(statusValue)) {
+          warnings.push({
+            artifact,
+            file: relFile,
+            type: 'unexpected-status',
+            message: `Status "${statusValue}" not in allowed values: ${allowedStatuses.join(', ')}`,
+          });
+        }
+      }
+    }
+  }
+
+  return { errors, warnings, summary };
+}
+
+function run(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: {
+        cwd: { type: 'string' },
+        json: { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      strict: true,
+      allowPositionals: false,
+    });
+  } catch (e) {
+    console.error(`validate: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (parsed.values.help) {
+    printHelp();
+    return;
+  }
+
+  const cwd = path.resolve(parsed.values.cwd ?? process.cwd());
+  const result = validate(cwd);
+  const status = result.errors.length === 0 ? 'PASS' : 'FAIL';
+
+  if (parsed.values.json) {
+    console.log(JSON.stringify({ ...result, result: status }, null, 2));
+  } else {
+    console.log(`Validating .ai/project/ at ${cwd}\n`);
+    for (const [name, count] of Object.entries(result.summary)) {
+      console.log(`  ${name.padEnd(10)} ${count}`);
+    }
+    console.log('');
+    if (result.errors.length > 0) {
+      console.log(`Errors: ${result.errors.length}`);
+      for (const e of result.errors) {
+        console.log(`  - ${e.file}: ${e.type}: ${e.message}`);
+      }
+    } else {
+      console.log('Errors:   none');
+    }
+    if (result.warnings.length > 0) {
+      console.log(`Warnings: ${result.warnings.length}`);
+      for (const w of result.warnings) {
+        console.log(`  - ${w.file}: ${w.type}: ${w.message}`);
+      }
+    } else {
+      console.log('Warnings: none');
+    }
+    console.log('');
+    console.log(
+      `Result: ${status === 'PASS' ? 'PASS (clean tree)' : `FAIL (${result.errors.length} errors)`}`,
+    );
+  }
+
+  process.exit(result.errors.length === 0 ? 0 : 1);
+}
+
+function printHelp() {
+  console.log(`ai-runtime-kit validate [options]
+
+Validate the .ai/project/ tree's structural integrity. Walks
+every artifact and checks that:
+
+  - Required ## Parent <Type> sections are present per the
+    v0.9.0 INDEX § Traceability rules.
+  - Cited parent paths resolve to real files on disk.
+  - Status values are in the allowed set per artifact type.
+
+Options:
+  --cwd <dir>   Target project root (default: process.cwd())
+  --json        Output structured JSON instead of human text
+  -h, --help    Show this help
+
+Exits 0 on no errors (warnings allowed and printed); 1 on any
+error. See .ai/runtime/INDEX.md § Traceability for the rules.`);
+}
+
+module.exports = { validate, run, printHelp };