ai-runtime-kit 0.5.0

package/runtime/RUNTIME_MODE.md

@@ -0,0 +1,109 @@
+# Runtime Mode
+
+## Purpose
+
+Define the current engineering operating mode.
+
+AI agents should adapt behavior based on runtime mode.
+
+---
+
+## Available Modes
+
+### FEATURE_DEVELOPMENT
+
+Focus:
+
+- feature delivery
+- execution speed
+- additive work
+
+Behavior:
+
+- prioritize executable feature tasks
+- prefer small incremental changes
+- preserve contracts
+
+---
+
+### BUG_FIX
+
+Focus:
+
+- corrective change (observed vs documented behavior)
+- minimal scope
+- regression-test-first execution
+
+Behavior:
+
+- follow `.ai/runtime/workflows/bug-fix.md` strictly
+- require Root Cause / Reproduction / Regression Test sections in spec
+- write the regression test before the fix; confirm red → green
+- prefer the smallest fix that addresses the named root cause
+- preserve contracts; treat fixes as additive when possible
+
+This mode is for non-incident corrective work. Production
+incidents escalate to `INCIDENT` per
+`RUNTIME_TRANSITIONS.md` § Any Mode → INCIDENT.
+
+---
+
+### GOVERNANCE_RECOVERY
+
+Focus:
+
+- workflow consistency
+- verification coverage
+- contract integrity
+- runtime health
+
+Behavior:
+
+- prioritize maintenance tasks
+- prioritize review coverage
+- prioritize workflow repair
+
+---
+
+### REFACTOR
+
+Focus:
+
+- architecture consistency
+- module boundaries
+- technical debt reduction
+
+Behavior:
+
+- prioritize safe migrations
+- minimize behavior changes
+- prefer small refactor tasks
+
+---
+
+### INCIDENT
+
+Focus:
+
+- runtime stability
+- rollback safety
+- production recovery
+
+Behavior:
+
+- avoid unnecessary changes
+- prioritize verification
+- minimize scope
+- avoid refactors
+
+---
+
+## Runtime Health Interaction
+
+Runtime mode should adapt to runtime health.
+
+Examples:
+
+- YELLOW health limits risky refactors.
+- RED health pauses feature expansion.
+- GREEN health allows normal feature development.

package/runtime/RUNTIME_TRANSITIONS.md

@@ -0,0 +1,141 @@
+# Runtime Transition Rules
+
+## Purpose
+
+Define how runtime state changes in response to governance conditions.
+
+---
+
+## Health Transitions
+
+### GREEN → YELLOW
+
+Trigger conditions:
+
+- governance drift detected
+- stale runtime metadata
+- missing review coverage
+- inconsistent lifecycle state
+- runtime audit warnings
+
+Behavior changes:
+
+- prioritize maintenance
+- reduce risky changes
+- increase governance focus
+
+---
+
+### YELLOW → RED
+
+Trigger conditions:
+
+- verification failure
+- active contract violation
+- failing build
+- runtime instability
+- broken bootstrap
+
+Behavior changes:
+
+- stop feature expansion
+- prioritize recovery
+- minimize execution scope
+
+---
+
+### RED → YELLOW
+
+Trigger conditions:
+
+- verification restored
+- runtime stable
+- critical failures resolved
+
+Behavior changes:
+
+- allow governance repair
+- continue limited execution
+
+---
+
+### YELLOW → GREEN
+
+Trigger conditions:
+
+- governance stabilized
+- runtime consistency restored
+- verification healthy
+- no active runtime drift
+
+Behavior changes:
+
+- allow feature development
+- allow runtime evolution
+- reduce governance overhead
+
+---
+
+## Mode Transitions
+
+### FEATURE_DEVELOPMENT → GOVERNANCE_RECOVERY
+
+Trigger conditions:
+
+- runtime audit detects governance drift
+- workflow inconsistencies accumulate
+- verification coverage degrades
+
+---
+
+### GOVERNANCE_RECOVERY → FEATURE_DEVELOPMENT
+
+Trigger conditions:
+
+- governance stabilized
+- runtime health GREEN
+- workflow consistency restored
+
+---
+
+### FEATURE_DEVELOPMENT → BUG_FIX
+
+Trigger conditions:
+
+- a defect is observed in shipped behavior
+- the change is corrective, not additive
+- production incident has NOT been declared
+
+---
+
+### BUG_FIX → FEATURE_DEVELOPMENT
+
+Trigger conditions:
+
+- the fix is DONE per `bug-fix.md` § Definition of done
+- no further corrective work is queued
+- runtime health is GREEN
+
+---
+
+### Any Mode → INCIDENT
+
+Trigger conditions:
+
+- RED runtime health
+- contract breach
+- failed verification
+- runtime instability
+
+---
+
+## Runtime Principle
+
+Runtime state should evolve conservatively.
+
+Prefer:
+
+- gradual escalation
+- explicit recovery
+- observable transitions
+- reversible operations

package/runtime/RUNTIME_VERSION.md

@@ -0,0 +1,17 @@
+# Runtime Version
+
+## Version
+
+v1
+
+## Status
+
+Frozen
+
+## Focus
+
+Use the runtime to build real product features.
+
+## Rule
+
+Do not add new runtime core files unless real product development proves they are necessary.

package/runtime/SAFETY.md

@@ -0,0 +1,156 @@
+# Runtime Safety Rules
+
+## Purpose
+
+Define repository safety boundaries for AI agents.
+
+AI agents must follow these rules before modifying the repository.
+
+---
+
+## Safe Operations
+
+Allowed without additional approval:
+
+- additive feature work
+- behavior-preserving refactors
+- test additions
+- review additions
+- documentation updates
+- task status updates
+- plan updates
+- review updates
+
+---
+
+## Protected Operations
+
+Require explicit review or approval:
+
+- contract changes
+- breaking API changes
+- runtime governance changes
+- bootstrap changes
+- priority system changes
+- task lifecycle changes
+- runtime mode changes
+- verification policy changes
+
+---
+
+### Runtime Tree Protection
+
+The path scope `.ai/runtime/**` is a protected zone. It holds reusable
+framework content (protocols, schemas, role definitions, generic
+memory, workflows, templates) that other projects consume verbatim
+once Phase 2 of the runtime extraction ships
+(`ai-runtime-kit`).
+
+#### What counts as a runtime edit
+
+Any of the following actions targeting `.ai/runtime/**`:
+
+- modifying an existing file
+- adding a new file
+- renaming or moving a file
+- deleting a file
+
+#### Rule
+
+Runtime edits are governance changes. Each runtime edit requires:
+
+- a spec under `.ai/project/specs/YYYY-MM-DD-<name>/` whose §2 Scope
+  lists the touched runtime paths explicitly, and
+- a review file under `.ai/project/reviews/`.
+
+Runtime edits MUST NOT be folded into feature work whose scope is a
+project module (e.g. `src/modules/auth/`).
+
+#### Exemptions
+
+- The Phase 2 `ai-runtime-kit init` / `upgrade` flow operates outside
+  this rule — those commands materialize or replace the entire
+  `.ai/runtime/` subtree as a unit and are the canonical source of
+  truth. They do not constitute "edits" in the sense above.
+- Pure read access (any agent loading a runtime file as context) is
+  unconstrained.
+
+#### Why
+
+- Phase 2 upgrades reset `.ai/runtime/` to the kit's canonical state;
+  edits made outside the spec-driven flow are lost.
+- Project-specific knowledge that leaks into `runtime/` makes the
+  framework non-reusable across other projects.
+- Spec-driven flow is how the rest of this governance system catches
+  regressions; runtime edits must use the same path.
+
+---
+
+## High-Risk Operations
+
+Require ADR approval:
+
+- deleting public APIs
+- changing API response shapes
+- removing contracts
+- changing runtime architecture
+- changing verification requirements
+- removing governance artifacts
+- changing task graph semantics
+
+---
+
+## Forbidden Operations
+
+AI agents must NOT:
+
+- bypass verification
+- skip governance rules
+- ignore contract violations
+- silently change runtime behavior
+- delete `.ai/` runtime structure
+- remove reviews/verifications without reason
+- execute destructive repository operations without approval
+
+---
+
+## Verification Safety
+
+Before marking work DONE:
+
+- verification must pass
+- contracts must remain valid
+- reviews must exist if required
+- runtime health must not degrade
+
+---
+
+## Runtime Protection Priority
+
+Priority order:
+
+```txt
+Safety
+↓
+Governance
+↓
+Contracts
+↓
+Verification
+↓
+Execution Speed
+```
+
+Safety always overrides convenience.
+
+---
+
+## Runtime Philosophy
+
+The runtime should prefer:
+
+- safe incremental change
+- explicit governance
+- observable workflow state
+- reversible operations
+- minimal surprise

package/runtime/adr/0000-template.md

@@ -0,0 +1,55 @@
+# ADR <NUMBER>: <TITLE>
+
+## Status
+
+Proposed | Accepted | Rejected | Deprecated
+
+---
+
+## Context
+
+Describe the problem, constraints, and background.
+
+---
+
+## Decision
+
+Describe the chosen solution.
+
+---
+
+## Alternatives Considered
+
+### Option 1
+
+Pros:
+-
+
+Cons:
+-
+
+### Option 2
+
+Pros:
+-
+
+Cons:
+-
+
+---
+
+## Consequences
+
+### Positive
+
+-
+
+### Negative
+
+-
+
+---
+
+## Notes
+
+Additional implementation notes if needed.

package/runtime/agents/executor.md

@@ -0,0 +1,19 @@
+# Executor Agent
+
+## Role
+
+You implement features according to specs.
+
+## Responsibilities
+
+- Read the provided spec
+- Modify code safely
+- Keep implementation simple
+- Run build verification
+- Report changed files
+
+## Must Not
+
+- Change unrelated code
+- Add unnecessary dependencies
+- Ignore build failures

package/runtime/agents/verifier.md

@@ -0,0 +1,83 @@
+# Verifier Agent
+
+## Role
+
+You are responsible for implementation verification and regression detection.
+
+You do NOT implement features.
+
+You verify:
+- correctness
+- compatibility
+- contracts
+- tests
+- build integrity
+
+---
+
+## Responsibilities
+
+- Run verification commands
+- Compare implementation against contracts
+- Detect regressions
+- Detect missing tests
+- Detect API breaking changes
+- Detect contract violations
+- Detect missing verification coverage
+
+---
+
+## Verification Areas
+
+### Build
+
+- TypeScript build passes
+- No new type errors
+
+### Tests
+
+- Existing tests still pass
+- New functionality is covered
+
+### API Contracts
+
+- Response fields are unchanged
+- Field types are unchanged
+- Required fields still exist
+
+### Architecture
+
+- Existing app structure remains consistent
+- No unnecessary coupling introduced
+
+---
+
+## Output Format
+
+### Summary
+
+Short verification summary.
+
+### Passed Checks
+
+List successful checks.
+
+### Failed Checks
+
+List failed checks.
+
+### Risks
+
+Potential future risks or weak areas.
+
+### Verdict
+
+PASS | FAIL
+
+---
+
+## Must Not
+
+- Implement features
+- Change feature scope
+- Ignore failing checks