ai-runtime-kit 0.5.0

package/runtime/hooks/README.md

@@ -0,0 +1,163 @@
+# Runtime Hooks
+
+This directory hosts **agent-pipeline transition hooks**. Each hook
+is a single `HOOK.md` describing one boundary contract between two
+agents in the recommended agent flow
+(`INDEX.md` § "Recommended Agent Flow").
+
+## Hooks vs Skills vs Rules vs Events
+
+| | Skill | Rule | Event | Hook |
+| --- | --- | --- | --- | --- |
+| Trigger | Task type | File scope | Runtime state change | Agent transition |
+| Loaded when | Task matches the skill's purpose | Task touches files in scope | Something happened | Pipeline reaches a transition matching `appliesWhen` |
+| Tense | "How to do X" | "Always do X in scope Y" | "X just happened" | "Before/after agent N runs, do X if condition" |
+| Example | "How to add an Express endpoint" | "Never use `any` in `.ts` files" | `VERIFICATION_FAILED` | "Before Executor starts on a runtime-scoped spec, snapshot baseline tests" |
+
+If a guideline is task-conditional, it's a `skill`.
+If it applies whenever code in a language is touched, it's a `rule`.
+If it's a post-fact narration of state change, it's an `event`.
+If it gates the handoff between two agents, it's a `hook`.
+
+## Hooks vs Git hooks
+
+This directory is **unrelated** to the Husky pre-commit / pre-push /
+commit-msg hooks documented in `ADR-0006` and
+`.ai/project/memory/core/tech-stack.md`. Those are git-level
+toolchain hooks; these are agent-pipeline orchestration hooks. The
+two systems do not interact.
+
+## Directory layout
+
+```txt
+.ai/runtime/hooks/
+├── _template/
+│   └── HOOK.md                                # template — copy from here
+├── pre-architect/    <hook-name>/HOOK.md
+├── post-architect/   <hook-name>/HOOK.md
+├── pre-planner/      <hook-name>/HOOK.md
+├── post-planner/     <hook-name>/HOOK.md
+├── pre-executor/     <hook-name>/HOOK.md
+├── post-executor/    <hook-name>/HOOK.md
+├── pre-verifier/     <hook-name>/HOOK.md
+├── post-verifier/    <hook-name>/HOOK.md
+├── pre-reviewer/     <hook-name>/HOOK.md
+└── post-reviewer/    <hook-name>/HOOK.md
+```
+
+Naming:
+
+- `<hook-name>` is a short noun phrase in lowercase kebab-case
+  (`baseline-snapshot`, `contract-change-followup`,
+  `runtime-edit-followup`).
+- One hook per directory; one `HOOK.md` per hook. If a transition
+  has multiple distinct concerns, split into multiple hook
+  directories under the same `<phase>-<agent>/` parent.
+- Phase-agent directories are created lazily — do not pre-seed empty
+  directories.
+
+## Trigger taxonomy
+
+A hook attaches to exactly one transition. Transitions are:
+
+| Phase | Agent | Meaning |
+| --- | --- | --- |
+| `pre` | architect | Before spec drafting begins |
+| `post` | architect | After spec is drafted but before plan |
+| `pre` | planner | Before task graph is produced |
+| `post` | planner | After plan exists but before execution |
+| `pre` | executor | Before code edits begin |
+| `post` | executor | After edits but before verification |
+| `pre` | verifier | Before verification commands run |
+| `post` | verifier | After verification result is known |
+| `pre` | reviewer | Before review file is written |
+| `post` | reviewer | After review file is written |
+
+There are no hooks for `INCIDENT` or `GOVERNANCE_RECOVERY` agents
+because those modes follow `SAFETY.md` directly and bypass the
+recommended flow; introducing hooks for them is out of scope here.
+
+## Gate behavior
+
+Three levels, in increasing strictness:
+
+- **ADVISORY** — the hook's action runs; its outcome is logged in
+  the review file. The transition proceeds regardless.
+- **GATE** — if the action fails or is skipped, the downstream
+  agent MUST NOT start. The blocking condition must be recorded in
+  the review file (or, if review is downstream of this hook, in the
+  task/spec file).
+- **MUTATION** — the action produces a required artifact (file,
+  status update, log). The transition is blocked until the artifact
+  exists. The artifact path is named in the hook's `## Outputs`
+  section.
+
+Pick the weakest level that captures the contract. Inflation to GATE
+or MUTATION requires a documented incident or contract risk.
+
+## When to create a hook
+
+A new hook is worth authoring when ANY of:
+
+- a review has caught the same boundary-handoff mistake across 2+
+  specs (e.g. "Executor began before Verifier captured a baseline"),
+- a runtime-protection rule (`SAFETY.md`) needs a checkable handoff
+  contract to actually be observable in practice,
+- a recurring agent-orchestration pattern emerges that is too
+  structural to live in a workflow file's prose.
+
+Do NOT create a hook for:
+
+- a one-off boundary concern (note it in the spec's §11 Resolved
+  Decisions instead),
+- something a workflow file's prose already enforces clearly
+  (`feature-development.md` § "Verify"),
+- a project-specific convention (those belong in
+  `.ai/project/memory/`),
+- a code-pattern concern (that's a skill or rule).
+
+## How hooks get loaded
+
+Three loading paths, mirroring the skills system:
+
+1. **Workflow file** — `.ai/runtime/workflows/feature-development.md`
+   tells each agent step to load relevant hooks for its phase.
+   Strongest current path.
+2. **Context-loading rule** —
+   `.ai/runtime/memory/runtime/context-loading.md` lists hooks under
+   Feature Implementation and Review.
+3. **Frontmatter signals (declarative)** — the hook's
+   `appliesWhen.pathPatterns` / `specSignals` / `runtimeModes` are
+   read by the agent during context-loading to judge applicability.
+   No runtime tooling reads or enforces these; they exist to help
+   agents filter. Weakest path.
+
+A spec whose work falls into a hook's `appliesWhen` does NOT need to
+reference the hook in §2 Scope explicitly — context-loading paths 1
+and 2 handle discovery. A spec that AUTHORS or MODIFIES a hook MUST
+list the hook's path in §2 Scope (runtime-scoped governance per
+`SAFETY.md` § Runtime Tree Protection).
+
+## Authoring a new hook — the workflow
+
+1. **Open a spec** under `.ai/project/specs/YYYY-MM-DD-<name>/` whose
+   §2 Scope lists the new hook's path. Runtime-scoped governance
+   per `SAFETY.md` § Runtime Tree Protection.
+2. **Copy the template**: `cp .ai/runtime/hooks/_template/HOOK.md
+   .ai/runtime/hooks/<phase>-<agent>/<hook-name>/HOOK.md`. Create
+   parent dirs.
+3. **Fill in frontmatter and body sections.** Pick the weakest gate
+   level that captures the contract. Cite a concrete "why" with at
+   least one incident or anti-pattern.
+4. **Register the hook** by adding a bullet to `INDEX.md`'s
+   `## Hooks` section.
+5. **Verify**: `npm run verify`.
+6. **Review**: standard review file under
+   `.ai/project/reviews/`.
+
+## Modifying an existing hook
+
+Same as authoring: a runtime-scoped spec, with §2 Scope listing the
+modified `HOOK.md` path. If the modification changes gate behavior
+(e.g. ADVISORY → GATE), the spec must list which in-flight specs
+would have been blocked by the new gate and budget for that impact.

package/runtime/hooks/_template/HOOK.md

@@ -0,0 +1,87 @@
+<!--
+  Hook template. Copy this file to
+  `.ai/runtime/hooks/<phase>-<agent>/<hook-name>/HOOK.md` and fill it
+  in. <phase> is `pre` or `post`; <agent> is one of architect /
+  planner / executor / verifier / reviewer.
+
+  The YAML frontmatter below is DECLARATIVE: no runtime tool reads or
+  enforces it. Agents read it during context-loading to judge whether
+  this hook applies. See `.ai/runtime/hooks/README.md` § "How hooks
+  get loaded" for the loading paths.
+-->
+---
+name: <hook-name-kebab-case>
+description: <one sentence: which transition this attaches to and what it enforces>
+metadata:
+  phase: pre | post
+  agent: architect | planner | executor | verifier | reviewer
+  gate: ADVISORY | GATE | MUTATION
+  appliesWhen:
+    pathPatterns:
+      - "<glob: e.g. .ai/runtime/**>"
+    specSignals:
+      - "<phrase that appears in spec §2 Scope, e.g. 'contract change'>"
+    runtimeModes:
+      - "<FEATURE_DEVELOPMENT | REFACTOR | INCIDENT | GOVERNANCE_RECOVERY>"
+---
+
+# <Hook Name>
+
+<One paragraph stating the transition contract: at this transition,
+under these conditions, this action must happen.>
+
+## Trigger
+
+- **Phase**: pre | post
+- **Agent transition**: e.g. `Planner → Executor` (for `pre-executor`)
+- **Applies when**: <condition that activates the hook — e.g. spec
+  §2 Scope lists `.ai/runtime/**`, or the diff touches a contract>
+
+## Action
+
+What the activating agent (or operator) must do when the hook fires.
+Imperative form. Concrete enough to be checkable.
+
+## Gate behavior
+
+One of:
+
+- **ADVISORY** — log the action's outcome; do not block the transition.
+- **GATE** — if the action fails or is skipped, the transition is
+  blocked. The downstream agent MUST NOT start.
+- **MUTATION** — the action produces a required artifact (file, log,
+  status update). The transition is blocked until the artifact exists.
+
+State which one and why.
+
+## Inputs
+
+What the hook reads: spec sections, prior agent outputs, git diff,
+contracts, etc.
+
+## Outputs
+
+What the hook produces: artifact path, status field update, log line,
+or "advisory note only".
+
+## Failure mode
+
+What happens if the action cannot be completed. For ADVISORY: how the
+failure is recorded. For GATE / MUTATION: who is notified and what
+manual override looks like (e.g. spec §11 Resolved Decisions note).
+
+## Why
+
+Cite a concrete failure mode or prior incident the hook prevents.
+Without a documented "why", the hook has no defense when a future
+contributor challenges it.
+
+## Examples
+
+### When this hook fires
+
+<a short scenario where the hook's `appliesWhen` matches>
+
+### When this hook does not fire
+
+<a near-miss scenario showing the boundary>

package/runtime/hooks/pre-executor/runtime-scoped-preflight/HOOK.md

@@ -0,0 +1,189 @@
+---
+name: runtime-scoped-preflight
+description: Pre-Executor GATE — when a spec touches .ai/runtime/**, verify branch, scope, and spec path preconditions before code edits begin.
+metadata:
+  phase: pre
+  agent: executor
+  gate: GATE
+  appliesWhen:
+    pathPatterns:
+      - ".ai/runtime/**"
+    specSignals:
+      - "runtime-scoped"
+      - "Runtime Tree Protection"
+    runtimeModes:
+      - FEATURE_DEVELOPMENT
+      - BUG_FIX
+      - REFACTOR
+      - GOVERNANCE_RECOVERY
+---
+
+# Runtime-Scoped Preflight
+
+At the `Planner → Executor` transition, if the spec's §2 Scope
+lists any path under `.ai/runtime/**`, the Executor MUST verify
+three preconditions before applying any file edit. Failing the
+check blocks the transition; the Executor stops and surfaces the
+failure to the operator.
+
+This hook is the agent-pipeline complement to `SAFETY.md` §
+Runtime Tree Protection. Where SAFETY.md states the rule,
+this hook makes the rule observable at the moment of
+violation — i.e. before any change is written.
+
+## Trigger
+
+- **Phase**: pre
+- **Agent transition**: `Planner → Executor`
+- **Applies when**: the spec's §2 Scope lists at least one path
+  matching `.ai/runtime/**`. Examples of qualifying scope
+  entries:
+  - `.ai/runtime/SAFETY.md`
+  - `.ai/runtime/workflows/feature-development.md`
+  - any new file under `.ai/runtime/hooks/`, `rules/`,
+    `skills/`, or `specs/_template/`.
+
+## Action
+
+Before the Executor opens an edit tool, confirm ALL three:
+
+1. **Scope contract.** Every runtime path the task will touch
+   appears verbatim in §2 Scope's `Includes` list (not just in
+   `§3 Requirements`). Implicit touches via subdirectory
+   wildcards (`.ai/runtime/**`) are not sufficient; each file
+   must be named.
+2. **Branch name.** The current branch name starts with
+   `chore/runtime-` per
+   `.ai/runtime/workflows/branching.md` § Governance Rule
+   Branches. Bare descriptive names (`fix/x`,
+   `feat/x`) do not satisfy this.
+3. **Spec home.** A spec file exists at
+   `.ai/project/specs/YYYY-MM-DD-<name>/spec.md` whose §2 Scope
+   was the source of (1). Out-of-band edits to runtime/ (no
+   spec, no review) are not permitted.
+
+If ANY check fails, STOP. Do not write files. Report the failed
+precondition to the operator and request remediation.
+
+## Gate behavior
+
+**GATE**. A failed precondition blocks the transition. The
+Executor MUST NOT start. The operator must either:
+
+- correct the precondition (rename branch, expand §2 Scope, or
+  add the missing spec), or
+- record in the spec's §11 Resolved Decisions why the
+  precondition does not apply (rare — almost always indicates
+  the change should not be made here).
+
+Manual override requires the spec's §11 to explicitly cite this
+hook by path (`.ai/runtime/hooks/pre-executor/runtime-scoped-preflight/HOOK.md`).
+Silent override is forbidden and constitutes a Forbidden
+Operation under `SAFETY.md`.
+
+## Inputs
+
+- The spec file's §2 Scope content (§ Includes specifically).
+- Current `git rev-parse --abbrev-ref HEAD` value.
+- Existence of the spec file on disk at the named path.
+
+## Outputs
+
+Advisory note recorded in the review file under
+`.ai/project/reviews/<spec-name>-review.md`'s § Verification
+subsection, even on success, of the form:
+
+```
+Runtime-scoped preflight (HOOK pre-executor/runtime-scoped-preflight):
+  - Scope contract: PASS — listed paths: <paths>
+  - Branch name: PASS — `<branch-name>`
+  - Spec home: PASS — `<spec-path>`
+```
+
+On failure: no review file is written (the Executor blocked
+before reaching the Review phase). The operator's response
+appears in the spec body itself.
+
+## Failure mode
+
+GATE failure halts the pipeline. The Executor must:
+
+1. State which of the three preconditions failed and why.
+2. Surface the relevant rule citation (SAFETY.md § Runtime
+   Tree Protection, branching.md § Governance Rule Branches).
+3. Wait for operator remediation. No silent retry.
+
+If the operator chooses to override via §11 Resolved Decisions,
+the override block must:
+
+- name this hook by path,
+- name the specific precondition being bypassed,
+- justify why the bypass is safer than the bypassed
+  precondition.
+
+## Why
+
+`SAFETY.md` § Runtime Tree Protection is one of the most-cited
+governance rules in this repo. Multiple specs land per day that
+touch runtime/. Without an observable handoff contract, the
+rule depends entirely on each Executor invocation remembering
+to check.
+
+Specific anti-patterns this hook prevents:
+
+- **Runtime edits in project-scoped branches.** A feature-spec
+  branch like `feat/notes-module` quietly edits `RUNTIME_MODE.md`
+  because the executor noticed a tangentially related drift.
+  No spec authorisation, no review, no governance trail.
+  `2026-05-12-workflow-maintenance` (the retrospective)
+  documents the kind of out-of-band edit this pattern produces.
+- **Wildcard scope.** A spec lists `.ai/runtime/**` in §2 Scope
+  to mean "I might touch a few files here" — and then the
+  executor touches a dozen. The hook forces enumeration.
+- **Missing spec.** A direct edit to `.ai/runtime/BOOTSTRAP.md`
+  with no spec at all. The hook fails check (3).
+
+`feedback_governance_bootstrap_order` (this repo's lived
+memory note: "write the rule on trunk before applying it") is
+strengthened by check (1) and (3) acting before any code is
+written.
+
+## Examples
+
+### When this hook fires
+
+Spec `2026-05-13-add-bug-fix-mode` lists in §2 Scope:
+
+```
+- `.ai/runtime/RUNTIME_MODE.md` — modify ...
+- `.ai/runtime/BOOTSTRAP.md` — modify ...
+- `.ai/runtime/RUNTIME_TRANSITIONS.md` — modify ...
+```
+
+Three runtime paths. The hook fires at `pre-executor`. The
+Executor verifies:
+
+1. ✅ Scope contract — all three paths listed by name.
+2. ✅ Branch — `chore/runtime-bug-fix-mode`.
+3. ✅ Spec home — exists.
+
+Pass. Executor proceeds.
+
+### When this hook does not fire
+
+Spec `2026-05-13-claudemd-runtime-paths` lists in §2 Scope only
+`CLAUDE.md` and `.ai/project/...` files. No `.ai/runtime/**`
+path appears. The hook's `appliesWhen.pathPatterns` does not
+match. The hook does not fire; the Executor proceeds without
+preflight.
+
+### Near-miss: the bypass case
+
+Spec body says "as a one-time exception, also patch
+`.ai/runtime/CAPABILITIES.md` to align labels." But §2 Scope
+only lists project files. The hook fires anyway because
+the **intent** (visible in §3 Requirements or §11 narrative)
+touches runtime/. Check (1) fails on "not in Includes list".
+The Executor must either move the runtime touch into §2 Scope
+formally (running the proper spec workflow) or split it into a
+follow-up spec.

package/runtime/memory/architecture/principles.md

@@ -0,0 +1,107 @@
+# Architecture Principles
+
+Generic architectural guidance for projects using this runtime.
+Project-specific conventions (concrete `src/` tree, ADR references,
+persistence stack) live in
+`.ai/project/memory/architecture/conventions.md`.
+
+## Goals
+
+- maintainability
+- modularity
+- testability
+- backward compatibility
+
+---
+
+## Preferred Structure (general shape)
+
+Recommended top-level layering:
+
+- composition root (app construction)
+- entry point (process startup only)
+- feature modules (vertical, owning a domain end-to-end)
+- cross-module middleware
+- shared infrastructure
+- framework-agnostic shared helpers
+
+Concrete directory layout for this project lives in
+`.ai/project/memory/architecture/conventions.md`.
+
+---
+
+## App Structure
+
+- composition root file:
+  - middleware registration
+  - route registration
+
+- entry file:
+  - process startup only
+
+---
+
+## Module Rules
+
+A feature module owns a feature end-to-end. Conventional files inside
+a module:
+
+- routes file — HTTP boundary
+- service file — orchestration / use cases (optional)
+- repository file — persistence access (optional)
+- module-private domain helpers
+- co-located tests
+
+Module internals are private. A module's public surface is what the
+composition root (and any other consuming module) imports — prefer a
+small set of exports.
+
+---
+
+## Layer Rules
+
+- **shared layer** — pure helpers, framework-agnostic. Depends on
+  nothing else inside the source tree.
+- **infrastructure layer** — shared runtime infrastructure (DB pool,
+  schema, migrations). Depends only on shared.
+- **middleware layer** — cross-module HTTP middleware. Depends on
+  infrastructure and shared.
+- **module layer** — feature modules. May depend on middleware,
+  infrastructure, shared, and the *public surface* of another module.
+  Must not reach into another module's internal files.
+- **composition root** — wires everything; the only place that imports
+  every module.
+
+Forbidden:
+
+- infrastructure importing from modules.
+- shared importing from anywhere inside source.
+- A module reaching into another module's internal files.
+
+---
+
+## Refactor Principles
+
+- prefer behavior-preserving refactors
+- prefer small migrations
+- avoid large rewrites
+- preserve contracts
+
+---
+
+## Service Design
+
+- services should avoid HTTP concerns
+- routes should remain thin
+- utilities should remain pure
+
+---
+
+## Middleware Design
+
+- middleware should be composable
+- avoid hidden side effects
+- prefer explicit registration
+- middleware that only serves one module belongs inside that module;
+  only middleware shared across modules lives in the cross-module
+  middleware layer

package/runtime/memory/engineering/principles.md

@@ -0,0 +1,102 @@
+# Engineering Principles
+
+Generic engineering principles for projects using this runtime.
+Project-specific conventions (Biome configuration, commit-message
+contract, persistence patterns) live in
+`.ai/project/memory/engineering/conventions.md`.
+
+## General Principles
+
+- Keep implementations simple.
+- Prefer readability over cleverness.
+- Preserve backward compatibility for public APIs.
+- Avoid unnecessary dependencies.
+- Prefer small focused changes.
+- Tests are required for public API changes.
+
+---
+
+## Project Structure
+
+The project structure pattern in this runtime follows a composition
+root + entry separation:
+
+- One file owns app construction and route registration.
+- One file owns process startup only.
+
+Do not place route logic inside the startup file.
+
+---
+
+## API Design
+
+- Responses must be JSON.
+- Public API changes require contract updates.
+- Breaking API changes require ADR approval.
+- Additive changes are preferred over destructive changes.
+
+---
+
+## Testing
+
+Requirements:
+
+- Tests must not bind real network ports.
+- Tests should validate response structure.
+- Existing tests must continue passing.
+
+(Specific test framework choices belong in project conventions.)
+
+---
+
+## Verification
+
+Minimum required checks:
+
+```bash
+npm test
+npm run build
+```
+
+---
+
+## Contracts
+
+Before modifying public APIs:
+
+- read `.ai/project/contracts/**`
+- preserve required fields
+- preserve field types
+- preserve backward compatibility
+
+---
+
+## ADR Rules
+
+Create ADRs for:
+
+- architecture changes
+- breaking API changes
+- major dependency decisions
+- structural refactors
+
+---
+
+## Review Expectations
+
+Reviews should check:
+
+- correctness
+- maintainability
+- compatibility
+- testing coverage
+- architecture consistency
+
+---
+
+## Preferred Engineering Style
+
+- explicit over implicit
+- modular over monolithic
+- stable over clever
+- testable over tightly coupled