ai-runtime-kit 0.5.0

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

@@ -0,0 +1,120 @@
+# Bug Fix Spec: <Short Name>
+
+## Status
+
+DRAFT
+<!-- Allowed: DRAFT | APPROVED | REJECTED | SUPERSEDED.
+     See .ai/runtime/workflows/bug-fix.md for lifecycle rules. -->
+
+## 1. Goal
+
+Describe the corrective outcome in one paragraph. Focus on what
+behavior changes, not how. Reference the affected user or system
+behavior, not the implementation.
+
+## 2. Scope
+
+<!-- If any in-scope path is under .ai/runtime/**, this is a
+     runtime-scoped governance change. Flag it explicitly and
+     follow .ai/runtime/SAFETY.md § Runtime Tree Protection. -->
+
+### In scope
+
+-
+
+### Out of scope
+
+-
+
+## 3. Root Cause
+
+Name the underlying defect, not the symptom.
+
+- **Cause:** <smallest accurate description of why the bug occurred>
+- **Origin:** <commit hash, spec path, or design decision that
+  introduced the cause; "unknown" if not traceable>
+- **Locality:** local | systemic
+  <!-- Systemic causes require a follow-up spec; link in §10. -->
+
+If the root cause is genuinely unknown after investigation, write
+"Unknown — best hypothesis: <X>" and state what evidence would
+confirm or refute it.
+
+## 4. Reproduction
+
+Minimum steps a reviewer can run to observe the bug BEFORE the fix.
+
+### Preconditions
+
+-
+
+### Steps
+
+```bash
+# exact commands or HTTP calls
+```
+
+### Observed (wrong) output
+
+```
+```
+
+### Expected (correct) output
+
+```
+```
+
+If the bug only reproduces in production, document the
+trace/log/event ID and the time window here, and state explicitly
+that local reproduction is not available.
+
+## 5. Regression Test
+
+The test that fails before the fix and passes after.
+
+- **File:** `<path>` (new | modified)
+- **Test name(s):** `<test name>`
+- **Catching assertion:** <one line: which assertion fails before
+  the fix>
+- **Red proof:** <paste failing output OR link the commit that
+  demonstrates red state>
+
+Exception: pure documentation fixes (no behavior change) may write
+"No regression test — documentation fix; §Acceptance Criteria greps
+serve as the regression check".
+
+## 6. Fix Strategy
+
+One paragraph. The minimal change that addresses §3 Root Cause,
+not the symptom.
+
+## 7. Risks
+
+-
+
+## 8. Acceptance Criteria
+
+- Regression test from §5 is present in the diff and passes.
+- §4 Reproduction steps no longer reproduce the bug after the fix
+  is applied.
+- `npm run verify` passes.
+
+## 9. Verification Commands
+
+```bash
+npm run verify
+# plus any spec-specific assertions
+```
+
+## 10. Related Specs
+
+-
+
+## 11. Related ADRs
+
+-
+
+## 12. Rollback Plan
+
+1.
+2.

package/runtime/tasks/TASK_STATUS.md

@@ -0,0 +1,58 @@
+# Task Status System
+
+## Purpose
+
+Define task lifecycle states for local AI engineering workflow.
+
+## Status Values
+
+### TODO
+
+Task is defined but not started.
+
+### IN_PROGRESS
+
+Task is currently being implemented.
+
+### BLOCKED
+
+Task cannot proceed because it needs clarification, dependency completion, or external input.
+
+### IN_REVIEW
+
+Implementation is complete and waiting for review.
+
+### DONE
+
+Task is implemented, verified, reviewed if needed, and committed.
+
+## Status Rules
+
+- New tasks start as TODO.
+- Executor changes TODO to IN_PROGRESS before implementation.
+- Executor changes IN_PROGRESS to IN_REVIEW after implementation and verification.
+- Reviewer changes IN_REVIEW to DONE after approval.
+- If verification fails, task remains IN_PROGRESS.
+- If scope is unclear, task becomes BLOCKED.
+
+## Required Task Fields
+
+Each task should include:
+
+- Goal
+- Related Spec
+- Related Plan
+- Dependencies
+- Files Likely Affected
+- Constraints
+- Acceptance Criteria
+- Verification
+- Status
+
+## Dependency Rules
+
+- A task cannot start until all dependencies are DONE.
+- BLOCKED tasks must explain the blocking dependency.
+- Parallelizable tasks may run independently if they do not modify overlapping files.
+
+<!-- Active task-set tables live in .ai/project/tasks/TASK_STATUS.md. -->

package/runtime/tasks/_template.md

@@ -0,0 +1,73 @@
+# Task: <TASK_NAME>
+
+## Goal
+
+Describe the specific engineering goal.
+
+---
+
+## Related Spec
+
+-
+
+---
+
+## Dependencies
+
+-
+
+---
+
+## Blocks
+
+-
+
+---
+
+## Parallelizable With
+
+-
+
+---
+
+## Files Likely Affected
+
+-
+
+---
+
+## Constraints
+
+-
+
+---
+
+## Acceptance Criteria
+
+-
+
+---
+
+## Verification
+
+```bash
+npm run verify
+```
+
+---
+
+## Status
+
+TODO
+
+## Owner
+
+executor
+
+## Blocked By
+
+None.
+
+## Review Required
+
+Yes

package/runtime/workflows/branching.md

@@ -0,0 +1,128 @@
+# Branching Workflow
+
+## Purpose
+
+Define when feature work must be done on a branch and how branches map onto the spec / plan / task / ADR lifecycle.
+
+This workflow exists because `feature-development.md` previously specified commit conventions but said nothing about branching. The `user-system` feature exposed the gap: roadmap-scale features need long-lived branches and per-spec sub-branches to keep `main` deployable and reviewable.
+
+---
+
+## Branching Rules
+
+Pick the smallest tier that fits the work.
+
+### Tier 1 — Commit directly on `main`
+
+Allowed for:
+
+- ~20 lines of additive code or fewer
+- no new dependencies
+- no public API surface change beyond a single new additive route or field
+- no ADR required
+- no contract change beyond an additive endpoint section
+- runtime mode does not change
+
+Examples: `feat(readyz)`, `docs: ...`, `chore: ...` that touches only runtime metadata.
+
+### Tier 2 — Single feature branch
+
+Required for:
+
+- any spec whose plan has more than one task
+- any spec that introduces a new dependency
+- any spec that changes existing response shapes
+- any spec that requires an ADR (see Tier 3 if the ADR itself introduces architecture)
+- any refactor that touches more than one module
+
+Branch naming:
+
+```
+feat/<spec-id>
+fix/<spec-id>
+refactor/<spec-id>
+chore/runtime-<topic>
+```
+
+`<spec-id>` is the spec directory name without the date prefix when unambiguous, or the full spec directory name when ambiguous.
+
+Workflow:
+
+1. Open the branch from latest `main`.
+2. Commit per task or per coherent unit (executor + verifier + reviewer chain stays intact).
+3. Merge to `main` only when all of the following are DONE: tasks, plan, review file, contract updates, `npm run verify`.
+4. Use `--no-ff` merges so the feature boundary is preserved.
+
+### Tier 3 — Roadmap feature with sub-spec branches
+
+Required for any **roadmap spec** (a spec that decomposes into multiple child specs).
+
+Structure:
+
+```
+main
+ └── feat/<roadmap-id>                          ← long-lived branch
+      ├── feat/<roadmap-id>--<sub-spec-1>       ← sub-branch, merges into long-lived
+      ├── feat/<roadmap-id>--<sub-spec-2>
+      └── feat/<roadmap-id>--<sub-spec-N>
+```
+
+**Sub-branch naming uses `--` (double dash) as the separator between the roadmap id and the sub-spec id**, not `/`. Git stores refs hierarchically: once `feat/<roadmap-id>` exists as a branch (a file under `.git/refs/heads/`), creating `feat/<roadmap-id>/<sub>` would require the same name to also be a directory, which git rejects with `cannot lock ref … exists`. The `--` separator keeps the visual hierarchy without colliding with the ref store.
+
+Workflow:
+
+1. Open `feat/<roadmap-id>` from latest `main`. The roadmap spec, the ADRs that justify the roadmap, and the roadmap plan land here as the first commit.
+2. For each child spec, open `feat/<roadmap-id>--<sub-spec>` from the long-lived branch.
+3. Each child sub-branch follows the full Spec → Plan → Tasks → Execute → Verify → Review → Commit lifecycle from `feature-development.md`.
+4. Merge child branches into the long-lived branch with `--no-ff`. The long-lived branch must always pass `npm run verify`.
+5. Merge the long-lived branch into `main` only when every child spec is DONE and the roadmap spec itself is marked DONE (or SUPERSEDED if scope evolved).
+6. Rebase the long-lived branch on `main` if `main` advances during the roadmap, to keep history linear.
+
+---
+
+## Governance Rule Branches
+
+Changes to `.ai/runtime/**` files (mode, health, workflows, capabilities, safety, priorities, lifecycle, agents, commands, templates, generic memory) are governance changes per `SAFETY.md` § Runtime Tree Protection. These must:
+
+- live on a branch named `chore/runtime-<topic>`
+- include a review file under `.ai/project/reviews/`
+- be authorized by a spec under `.ai/project/specs/YYYY-MM-DD-<name>/` whose §2 Scope explicitly lists the touched `.ai/runtime/**` paths
+- if introducing a new constraint, land on `main` BEFORE any feature work that relies on the new constraint
+- never be combined with feature code in the same commit
+
+Exception: trivial typo or wording fixes inside a single doc file may be Tier 1.
+
+---
+
+## Branch Hygiene
+
+- Never force-push `main`.
+- Never force-push a long-lived roadmap branch shared with other contributors.
+- Force-push within an unmerged single-author feature branch is allowed if it improves review.
+- Do not skip pre-commit or pre-push hooks unless explicitly authorized.
+- Delete sub-spec branches after merge into the long-lived branch.
+- Delete feature branches after merge into `main`.
+
+---
+
+## Mapping to runtime artifacts
+
+| Branch tier | Required artifacts before merge |
+|---|---|
+| Tier 1 | conventional commit; updated task/plan/spec statuses if applicable |
+| Tier 2 | spec APPROVED · plan DONE · all tasks DONE · review file · contracts updated · `npm run verify` passes |
+| Tier 3 — sub-branch | same as Tier 2 |
+| Tier 3 — long-lived | every child spec DONE; roadmap spec DONE or SUPERSEDED; aggregated review file optional |
+| Governance branch | review file |
+
+---
+
+## Verification
+
+`npm run verify` must pass:
+
+- before merging any branch into `main`
+- before merging any sub-spec branch into the long-lived roadmap branch
+- on the long-lived branch after every sub-spec merge
+
+If verification fails on the long-lived branch after a sub-spec merge, runtime health transitions to YELLOW or RED per `RUNTIME_TRANSITIONS.md`, and no further sub-spec merges are allowed until recovery.

package/runtime/workflows/bug-fix.md

@@ -0,0 +1,169 @@
+# Bug Fix Workflow
+
+## Purpose
+
+Use this workflow to ship one corrective change safely with AI
+assistance. A "bug fix" here means a change whose primary intent is
+to bring observed behavior in line with documented or expected
+behavior, not to extend functionality.
+
+## When this workflow applies
+
+This workflow applies when ANY of the following is true:
+
+- the spec directory is named `YYYY-MM-DD-fix-<name>/`,
+- the spec includes a `## Root Cause` section,
+- the change is committed with a `fix:` prefix per
+  `feature-development.md` § Commit conventions.
+
+When in doubt, prefer this workflow over `feature-development.md`.
+Production incidents (`INCIDENT` runtime mode) are out of scope;
+follow `SAFETY.md` for those.
+
+## Roles
+
+Same as `feature-development.md`:
+
+- ChatGPT: define, design, review, summarize
+- Claude Code: implement, refactor, verify
+
+## Spec lifecycle
+
+Same lifecycle as feature specs (`DRAFT → APPROVED → REJECTED →
+SUPERSEDED`). Use the bug-fix-specific template at
+`.ai/runtime/specs/_template-bug-fix/spec.md`, which augments the
+feature spec shape with three required sections (see §Required spec
+sections below).
+
+## Required spec sections
+
+A bug-fix spec MUST include all sections of the feature spec
+template, PLUS the following three sections:
+
+### `## Root Cause`
+
+Name the underlying defect, not the symptom. Required content:
+
+- the smallest accurate description of why the bug occurred (e.g.
+  "validator middleware ran after the route handler that threw"),
+- the commit, spec, or design decision that introduced the cause
+  if knowable (link the commit hash or spec path),
+- whether the cause is local (one module) or systemic (pattern
+  repeated across modules) — systemic causes require a follow-up
+  spec and must be linked in `## 10. Related Specs`.
+
+If the root cause is genuinely unknown after investigation, write
+"Unknown — best hypothesis: <X>" and explain what evidence would
+confirm or refute it. Do not skip the section.
+
+### `## Reproduction`
+
+The minimal steps a reviewer can run to observe the bug BEFORE the
+fix is applied. Required content:
+
+- preconditions (env vars, fixtures, branch),
+- exact commands or HTTP calls,
+- the observed (wrong) output,
+- the expected (correct) output.
+
+If the bug only reproduces in production, document the
+trace/log/event ID and the time window instead of commands, and
+state explicitly that local reproduction is not available.
+
+### `## Regression Test`
+
+The test that fails before the fix and passes after. Required
+content:
+
+- the test file path (new or modified),
+- the test name(s) added,
+- a one-line statement of which assertion catches the bug,
+- proof that the test was red before the fix (paste the failing
+  output, or note the commit that demonstrates the red state).
+
+Exception: pure documentation fixes (no behavior change) may state
+"No regression test — documentation fix; spec §Acceptance Criteria
+greps serve as the regression check" and rely on the spec's grep
+assertions instead.
+
+## Workflow
+
+### 1. Define spec
+
+Copy `.ai/runtime/specs/_template-bug-fix/spec.md` into
+`.ai/project/specs/YYYY-MM-DD-fix-<name>/spec.md`. Fill in every
+required section, including the three above.
+
+Pick the spec name to describe the cause when possible, not the
+symptom (`fix-validator-after-handler`, not `fix-500-on-login`).
+
+### 2. Plan
+
+Same as `feature-development.md` § Workflow. Bug-fix plans are
+typically smaller (1–2 tasks) but the structure is identical.
+
+### 3. Execute with Claude Code
+
+Claude Code must read the same context as feature work
+(`feature-development.md` § Execute), plus:
+
+- the spec's `## Root Cause` section (drives the fix shape),
+- the spec's `## Reproduction` (drives the regression test shape),
+- the spec's `## Regression Test` (drives the test file edit).
+
+Executor order:
+
+1. Write the regression test first; confirm it fails.
+2. Apply the minimal fix that addresses the named root cause.
+3. Re-run the test; confirm it passes.
+4. Run `npm run verify`.
+
+This order is mandatory unless the spec's `## Regression Test`
+invokes the documentation exception above.
+
+### 4. Verify
+
+Same as `feature-development.md` § Verify, plus:
+
+- the new regression test must be present in the diff and passing,
+- the spec's `## Reproduction` steps must no longer reproduce the
+  bug (reviewer confirms by re-running them post-fix).
+
+### 5. Review
+
+Same as `feature-development.md` § Review. The review file MUST
+explicitly state whether the three required sections (Root Cause,
+Reproduction, Regression Test) are present and adequate.
+
+### 6. Commit
+
+Use `fix:` as the conventional commit prefix.
+
+## Definition of done
+
+A bug fix is done only when:
+
+- spec exists with all three required sections filled,
+- regression test exists and passes,
+- fix is implemented,
+- `npm run verify` passes,
+- review exists and confirms the three required sections,
+- changes are committed with `fix:` prefix.
+
+## Branching
+
+Same as `branching.md`. No bug-fix-specific tier; the existing Tier
+1 / Tier 2 / Tier 3 / Governance rules apply unchanged.
+
+## Relationship to feature-development.md
+
+This workflow is a strict superset of `feature-development.md` for
+the spec/plan/task/review pipeline. Differences are limited to:
+
+- spec template (bug-fix template adds three required sections),
+- executor order (regression test first),
+- review file must explicitly check the three required sections,
+- commit prefix (`fix:` instead of `feat:`).
+
+For any topic not covered here, defer to
+`feature-development.md`.