ai-runtime-kit 0.10.0 → 0.10.2

package/CHANGELOG.md

@@ -10,6 +10,58 @@ kit.
 
 ## [Unreleased]
 
+## [0.10.2] - 2026-05-14
+
+Doc-only addition for agent orientation.
+
+### Added
+- `runtime/INDEX.md` § Workflow Overview — new section between
+  § Purpose and § Agents. Synthesizes the 9-step pipeline +
+  8 agents + 6 artifact types + traceability chain +
+  governance boundary into a single big-picture orientation.
+  92 lines; cross-references the existing § Agents,
+  § Traceability, § Workflows, § Recommended Agent Flow,
+  and § Hooks sections for detail.
+
+### Process
+- Ninth fire of `pre-executor/runtime-scoped-preflight` hook,
+  ninth clean pass.
+- Smallest scope of any runtime-scoped ship this session
+  (1 runtime path).
+
+## [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

package/README.md

@@ -10,6 +10,12 @@ 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
@@ -316,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)
@@ -336,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.
 
@@ -346,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-runtime-kit",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "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/INDEX.md

@@ -13,6 +13,97 @@ AI agents should use this file to understand:
 
 ---
 
+## Workflow Overview
+
+The kit ships a 9-step pipeline for product-driven features
+(engineering-only changes skip Steps 0 and 0.5). Each step
+has a kit-shipped role-definition file under
+`.ai/runtime/agents/` and produces a structurally-linked
+artifact in `.ai/project/`.
+
+### Pipeline
+
+```txt
+Step 0    PRD          (optional · product-driven only)
+   ↓
+Step 0.5  Feature      (mandatory if Step 0 ran; N features per PRD)
+   ↓
+Step 1    Spec         (1 per feature; engineering details)
+   ↓
+Step 1.5  TDD          (per task with TDD-Applies: true)
+   ↓
+Step 2    Execute      (plan + task + implementation umbrella)
+   ↓
+Step 3    Verify
+   ↓
+Step 4    Review
+   ↓
+Steps 5+6 Fix + Commit
+```
+
+### Agents and artifacts per phase
+
+| Step | Agent (role file) | Artifact (project path) |
+|---|---|---|
+| 0     | `prd-writer`     | `.ai/project/prds/<slug>/prd.md` |
+| 0.5   | `feature-writer` | `.ai/project/features/<slug>/feature.md` |
+| 1     | `spec-writer`    | `.ai/project/specs/<slug>/spec.md` |
+| 2-plan| `planner`        | `.ai/project/plans/<slug>/plan.md` |
+| 2-task| `planner`        | `.ai/project/tasks/<slug>/...` |
+| 1.5   | `tdd-writer`     | failing-test git commit |
+| 2-impl| `executor`       | implementation git commit |
+| 3     | `verifier`       | (verification report, usually inline) |
+| 4     | `reviewer`       | `.ai/project/reviews/<slug>.md` |
+
+Notes: `task` is a transition concept consumed by the next
+role, not a separate authoring role; `architect` is replaced
+by `spec-writer` (see § Agents below).
+
+### Traceability chain
+
+Every artifact carries a structural upward-citation link in a
+`## Parent <Type>` section:
+
+```txt
+commit → task → plan → spec → feature → PRD
+```
+
+For per-artifact required sections and the
+`(none — <reason>)` rendering convention for skipped paths,
+see § Traceability.
+
+### Governance boundary
+
+Which changes require what depends on which paths they touch:
+
+| Touched paths | Branch convention | Preflight hook | Spec required |
+|---|---|---|---|
+| `runtime/**` | `chore/runtime-<topic>` | **GATE** fires (3 preconditions) | yes, §2 Scope enumerates each path |
+| `src/`, `test/`, `bin/` (kit code) | `feat/<topic>` / `fix/<topic>` | does not fire | yes (or simple feature workflow) |
+| `.ai/project/**` (project tree) | any | does not fire | depends on complexity |
+| `README` / `CHANGELOG` / `package.json` | any | does not fire | typically bundled with ship metadata |
+
+Per `branching.md § Governance Rule Branches`, runtime/
+governance changes MUST NOT be combined with feature code in
+the same commit — split into separate commits even on the
+same branch.
+
+### Where to read more
+
+- § Agents — the 8 role files and what each does.
+- § Traceability — the `## Parent <Type>` rules per artifact.
+- § Workflows — the canonical
+  `.ai/runtime/workflows/feature-development.md` step-by-step
+  (this Overview is a synthesis; the workflow doc is the
+  source of truth for the steps).
+- § Recommended Agent Flow — the same 8 roles listed as a
+  pipeline (separate from this Overview for readers arriving
+  at INDEX.md from a different entry point).
+- § Hooks — the `pre-executor/runtime-scoped-preflight` GATE
+  and other agent-transition hooks.
+
+---
+
 ## Agents
 
 Location:

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