ai-runtime-kit 0.5.0 → 0.10.0

package/runtime/specs/_template-bug-fix/spec.md

@@ -6,6 +6,15 @@ DRAFT
 <!-- Allowed: DRAFT | APPROVED | REJECTED | SUPERSEDED.
      See .ai/runtime/workflows/bug-fix.md for lifecycle rules. -->
 
+## Parent Feature
+
+(none — bug-fix workflow)
+<!-- Bug-fix workflow skips Step 0.5 (no feature slicing) — the
+     fix is corrective, not a sliced PRD feature. Override with
+     a real path only if the bug fix happens to be part of a
+     larger PRD-driven effort. See .ai/runtime/INDEX.md
+     § Traceability for the full chain. -->
+
 ## 1. Goal
 
 Describe the corrective outcome in one paragraph. Focus on what

package/runtime/tasks/_template.md

@@ -6,9 +6,20 @@ Describe the specific engineering goal.
 
 ---
 
-## Related Spec
+## Parent Spec
 
--
+`.ai/project/specs/YYYY-MM-DD-<slug>/spec.md`
+<!-- Required. Single path. -->
+
+---
+
+## 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. -->
 
 ---
 
@@ -64,6 +75,18 @@ TODO
 
 executor
 
+## TDD-Applies
+
+false
+<!-- Allowed: true | false.
+     Rule: true if the task introduces or modifies runtime
+     behavior (code that runs); false for documentation, refactor
+     with no behavior change, or config / packaging / metadata
+     only. When true, follow workflow Step 1.5 — a failing-test
+     commit must precede the implementation commit. When false,
+     state a one-line reason here so the skip is explicit
+     rather than implicit. -->
+
 ## Blocked By
 
 None.

package/runtime/workflows/feature-development.md

@@ -50,6 +50,12 @@ Metrics, User Stories, Out of Scope, Open Questions,
 Stakeholders. Engineering details (architecture, data flow, code
 contracts) belong in the downstream spec, not the PRD.
 
+Read `.ai/runtime/agents/prd-writer.md` to anchor the role — it
+scopes the agent's responsibilities, inputs, outputs, and
+constraints. The procedural depth (the 11-step elicit-then-write
+flow) lives in a project-side skill referenced from the agent
+file; concept lattice is **agent = WHO, skill = HOW.**
+
 Skip this step when:
 
 - the change is corrective (use `bug-fix.md` instead — bug fixes
@@ -60,9 +66,43 @@ Skip this step when:
   intent.
 
 PRD lifecycle mirrors specs: `DRAFT → APPROVED → REJECTED →
-SUPERSEDED`. An APPROVED PRD authorizes spec drafting. The
-downstream spec MUST reference its PRD by path in §1 Goal so
-review can verify the spec satisfies the PRD.
+SUPERSEDED`. An APPROVED PRD authorizes feature slicing (Step
+0.5).
+
+### 0.5. Slice into Features
+
+When Step 0 ran (a PRD exists), slice it into **≥1 feature
+docs** under:
+
+```txt
+.ai/project/features/YYYY-MM-DD-<slug>/feature.md
+```
+
+One feature per discrete capability that can be specced and
+implemented independently. The feature doc answers "what slice
+of the PRD does this satisfy, and what does done look like" —
+mid-level between PRD ("what & why") and spec ("how").
+Engineering details (architecture, contracts, test plan) belong
+in the spec, not the feature.
+
+Use `.ai/runtime/features/_template.md` as the starting point.
+Each feature must cite its parent PRD in `## Parent PRD`; the
+PRD's `## Downstream Spec` section lists the features that
+derived from it.
+
+**Mandatory whenever Step 0 ran.** Same skip criteria as Step 0:
+bug-fix workflow and engineering-only changes skip Step 0
+entirely, so they skip Step 0.5 too.
+
+Single-feature PRDs still produce **one feature doc with the
+full template structure** — sections may contain "see parent
+PRD" pointers when the content is fully captured upstream, but
+no 5-line stub allowance (consistent shape protects
+traceability tooling and audit clarity).
+
+Feature lifecycle mirrors specs: `DRAFT → APPROVED → REJECTED →
+SUPERSEDED`. An APPROVED feature authorizes spec drafting for
+that feature.
 
 ### 1. Define Spec
 
@@ -72,9 +112,12 @@ Create a feature spec under:
 .ai/project/specs/YYYY-MM-DD-feature-name/spec.md
 ```
 
-If the spec is downstream of a PRD (Step 0), §1 Goal must cite
-the PRD path so reviewers can check that the spec covers the
-PRD's requirements without quietly expanding scope.
+If the spec is downstream of a feature (Step 0.5), §1 Goal must
+cite the feature path (the feature in turn cites its parent
+PRD, so the chain assembles upward). Reviewers walk the chain to
+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.
 
 Spec must include:
 
@@ -86,8 +129,45 @@ Spec must include:
 - Verification Commands
 - Rollback Plan
 
+### 1.5. TDD Phase (per task, when applicable)
+
+For each task produced under the spec's plan: if the task
+carries `TDD-Applies: true` (see
+`.ai/runtime/tasks/_template.md` § TDD-Applies), a **failing-
+test commit must land before** that task's implementation
+commit. The role file for this step is
+`.ai/runtime/agents/tdd-writer.md`.
+
+**Trigger.** Task's `TDD-Applies` value is `true`. The
+boundary follows parent-PRD-style rules: behavior-changing
+tasks → `true`; doc / refactor-with-no-behavior-change /
+config-only → `false`.
+
+**Required artifact.** A separate commit whose diff contains
+only the failing test(s) for the task. Verify red (test
+actually fails) before declaring the step done. The
+implementation commit lands on a distinct commit hash with a
+later timestamp, satisfying the test that was just authored.
+
+**Skip rule.** Tasks with `TDD-Applies: false` skip this step
+entirely. The skip is explicit on the task itself (the
+`## TDD-Applies` section in the task file states the boolean
+plus a one-line reason); never implicit.
+
+**Per-task semantics.** This is not a single workflow-wide
+pause. Step 1.5 runs once *per applicable task*, interleaved
+with that task's implementation. A feature with N
+TDD-applicable tasks fires Step 1.5 N times.
+
 ### 2. Execute with Claude Code
 
+> Step 1.5 is a per-task prerequisite for any task with
+> `TDD-Applies: true`. The execute step below covers plan
+> authoring, task production, implementation, and verification
+> as one umbrella; the TDD discipline runs *inside* that
+> umbrella, per applicable task, before each task's
+> implementation commit.
+
 Claude Code must read:
 
 - `.ai/runtime/agents/executor.md`

package/src/init.js

@@ -11,6 +11,7 @@ const { isPathGitignored } = require('./git');
 
 const PROJECT_SKELETON_DIRS = [
   'prds',
+  'features',
   'specs',
   'plans',
   'tasks',

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 };