project-iris 0.0.1

package/src/iris_bundle/.iris/aidlc/memory/memory-bank.yaml

@@ -0,0 +1,39 @@
+name: iris-memory-bank
+version: '1.0'
+root: memory-bank
+folders:
+  intents:
+    required: true
+    description: High-level problems and DoD.
+  units:
+    required: true
+    description: Work units with acceptance + approvals.
+  bolts:
+    required: true
+    description: Implementation briefs linked to units.
+  standards:
+    required: true
+    description: Project-local standards (cannot contradict doctrine).
+  logs:
+    required: true
+    description: Decisions, reviews, incidents (append-only).
+naming:
+  style: kebab-case
+  log_prefix: YYYY-MM-DD__
+  status_values:
+  - Draft
+  - Approved
+  - In Progress
+  - Done
+  - Archived
+minimum_required_by_phase:
+  Inception:
+  - intents/<intent>.md (Approved)
+  - units/<unit>/unit.md (Approved)
+  - logs/<date>__inception-kickoff.md
+  Construction:
+  - units/<unit>/unit.md (Approved)
+  - bolts/<unit>/<bolt>/bolt.md (Ready)
+  - logs/<date>__construction-start.md
+  Operations:
+  - logs/<date>__ops-handover.md

package/src/iris_bundle/.iris/aidlc/memory/unit-rules.md

@@ -0,0 +1,9 @@
+# Unit Rules
+
+## Hard Rules
+- Units MUST be testable and scoped.
+- Units MUST include: Scope, Acceptance, Test Plan, Risks, Rollback.
+- Construction MUST reference an approved unit.
+
+## Approval
+A unit is approved when `Status: Approved` is set and an approval log exists.

package/src/iris_bundle/.iris/aidlc/quick-start.md

@@ -0,0 +1,24 @@
+# Quick Start (IRIS Doctrine)
+
+## 1) Create the canonical memory bank (repo root)
+```
+memory-bank/
+  intents/
+  units/
+  bolts/
+  standards/
+  logs/
+```
+
+## 2) Work in phases
+- **Inception** → define & approve intent + units
+- **Construction** → implement approved units/bolts with evidence
+- **Operations** → maintain, monitor, respond, stabilize
+
+## 3) Use templates
+Templates live in `.iris/aidlc/templates/`. Create artifacts in `memory-bank/`.
+
+## 4) Gate everything
+Before changing phases, validate with:
+- `.iris/aidlc/validation/phase-preconditions.md`
+- `.iris/aidlc/validation/quality-checklist.md`

package/src/iris_bundle/.iris/aidlc/skills/execution/implementation.md

@@ -0,0 +1,14 @@
+# Skill: Implementation
+
+## Purpose
+Implement bolts against approved units with traceable verification.
+
+## Hard Rules
+- MUST stay within unit scope.
+- MUST run verification per unit test plan.
+- MUST log significant decisions.
+
+## Procedure
+1. Read unit + bolt.
+2. Implement smallest change set.
+3. Verify and record evidence.

package/src/iris_bundle/.iris/aidlc/skills/execution/refactoring.md

@@ -0,0 +1,13 @@
+# Skill: Refactoring
+
+## Purpose
+Improve internal quality without changing behavior unless approved.
+
+## Hard Rules
+- MUST NOT change behavior without updating intent/unit.
+- MUST re-run tests.
+
+## Procedure
+1. Define invariants.
+2. Refactor in small steps.
+3. Verify after each step.

package/src/iris_bundle/.iris/aidlc/skills/execution/scaffold-generation.md

@@ -0,0 +1,15 @@
+# Skill: Scaffold Generation
+
+## Purpose
+Create minimal structure required by the unit.
+
+## Hard Rules
+- MUST create only what the unit requires.
+- MUST NOT create speculative modules.
+- MUST keep changes reviewable.
+
+## Procedure
+1. Identify required modules and interfaces.
+2. Generate minimal files.
+3. Ensure it builds/runs (if applicable).
+4. Record created paths in the unit.

package/src/iris_bundle/.iris/aidlc/skills/governance/escalation.md

@@ -0,0 +1,13 @@
+# Skill: Escalation
+
+## Hard Rules
+Escalate to Master Agent when:
+- artifacts conflict
+- a phase transition is requested without prerequisites
+- an architectural decision is required
+
+## Procedure
+1. Summarize conflict.
+2. Provide options + tradeoffs.
+3. Request explicit decision.
+4. Log outcome.

package/src/iris_bundle/.iris/aidlc/skills/governance/quality-gates.md

@@ -0,0 +1,14 @@
+# Skill: Quality Gates
+
+## Purpose
+Fail-closed quality enforcement.
+
+## Hard Rules
+- MUST fail closed: missing evidence = gate failed.
+- MUST record pass/fail in a review/log.
+- MUST NOT proceed after a failed gate.
+
+## Procedure
+1. Run checklist.
+2. Verify artifacts exist.
+3. Record results + evidence.

package/src/iris_bundle/.iris/aidlc/skills/governance/stop-conditions.md

@@ -0,0 +1,11 @@
+# Skill: Stop Conditions
+
+## Hard Rules
+An agent MUST stop if:
+- required artifacts are missing
+- acceptance criteria are not testable
+- approvals are missing
+- a policy violation is detected
+
+## Recovery
+Create missing artifacts using templates, then continue.

package/src/iris_bundle/.iris/aidlc/skills/reasoning/decomposition.md

@@ -0,0 +1,23 @@
+# Skill: Decomposition
+
+## Purpose
+Turn intent into units/bolts that can be executed and verified.
+
+## Inputs
+- Approved intent
+- Constraints and existing context
+
+## Outputs
+- Units (`memory-bank/units/<unit>/unit.md`)
+- Bolts (`memory-bank/bolts/<unit>/<bolt>/bolt.md`) as needed
+
+## Hard Rules
+- MUST produce measurable acceptance criteria.
+- MUST keep units verifiable in one cycle.
+- MUST log decomposition decisions.
+
+## Procedure
+1. Extract goals/constraints from intent.
+2. Define units as independently testable deliverables.
+3. Create bolts for implementation slices if helpful.
+4. Record decisions in logs.

package/src/iris_bundle/.iris/aidlc/skills/reasoning/risk-analysis.md

@@ -0,0 +1,14 @@
+# Skill: Risk Analysis
+
+## Purpose
+Identify risks and define mitigations/rollback.
+
+## Hard Rules
+- MUST add rollback for risky changes.
+- MUST log architecture risks.
+
+## Procedure
+1. Identify failure modes.
+2. Add mitigations.
+3. Add rollback.
+4. Log major risks.

package/src/iris_bundle/.iris/aidlc/skills/reasoning/verification.md

@@ -0,0 +1,21 @@
+# Skill: Verification
+
+## Purpose
+Prove changes with evidence.
+
+## Inputs
+- Unit acceptance criteria + test plan
+- Code changes
+
+## Outputs
+- Evidence recorded in review/log artifacts
+
+## Hard Rules
+- MUST run specified tests or explicitly update the unit to define them.
+- MUST record evidence.
+- MUST NOT claim “verified” without evidence.
+
+## Procedure
+1. Run tests.
+2. Capture outputs.
+3. Record in review.md or log.

package/src/iris_bundle/.iris/aidlc/standards/artifacts-registry.md

@@ -0,0 +1,38 @@
+# Artifacts Registry (Canonical)
+
+## Purpose
+Define IRIS artifacts and their authoritative locations.
+
+## Artifacts
+### Intent
+- Path: `memory-bank/intents/<intent-slug>.md`
+- Template: `.iris/aidlc/templates/intent.md`
+- Owner: Inception Agent
+- Lifecycle: Draft → Approved → Archived
+
+### Unit
+- Path: `memory-bank/units/<unit-slug>/unit.md`
+- Template: `.iris/aidlc/templates/unit.md`
+- Owner: Inception (create/approve), Construction (execute)
+- Lifecycle: Draft → Approved → In Progress → Done
+
+### Bolt
+- Path: `memory-bank/bolts/<unit-slug>/<bolt-slug>/bolt.md`
+- Template: `.iris/aidlc/templates/bolt.md`
+- Owner: Construction
+- Lifecycle: Draft → Ready → Executed → Verified
+
+### Log
+- Path: `memory-bank/logs/YYYY-MM-DD__<topic>.md`
+- Template: `.iris/aidlc/templates/log.md`
+- Owner: All agents
+- Lifecycle: Immutable (append via new logs)
+
+### Review
+- Path: `memory-bank/units/<unit-slug>/review.md` (recommended) or `memory-bank/logs/`
+- Template: `.iris/aidlc/templates/review.md`
+- Owner: Master (or delegated reviewer)
+
+## Hard Rules
+- If a phase gate requires an artifact, it MUST exist at the exact path.
+- Artifacts MUST NOT be embedded inside unrelated documents.

package/src/iris_bundle/.iris/aidlc/standards/decision-logging.md

@@ -0,0 +1,16 @@
+# Decision Logging Standard
+
+## Purpose
+Prevent silent drift and preserve rationale.
+
+## Hard Rules
+- Any decision with downstream impact MUST be logged in `memory-bank/logs/` using `templates/log.md`.
+- Logs MUST include:
+  - context
+  - options considered
+  - chosen option + rationale
+  - tradeoffs/risks
+  - next actions
+
+## Quality Gate
+If a reviewer cannot explain “why”, the change is incomplete.

package/src/iris_bundle/.iris/aidlc/standards/doctrine-structure.md

@@ -0,0 +1,31 @@
+# Doctrine Structure Standard
+
+## Purpose
+Freeze the IRIS doctrine layout so it remains stable, searchable, and enforceable.
+
+## Scope
+- In scope: `.iris/aidlc/**` structure, naming, canonical locations.
+- Out of scope: tool-specific wrappers (kept outside doctrine or mirrored under `.iris/tools/` at repo root).
+
+## Hard Rules
+- Top-level directories under `.iris/aidlc/` MUST remain:
+  - `agents/`, `commands/`, `skills/`, `standards/`, `templates/`, `context/`, `memory/`, `validation/`
+- New top-level directories MUST NOT be added unless all are updated:
+  - this document
+  - `standards/file-structure.md`
+  - `context/context-map.md`
+- Rules MUST NOT be duplicated across documents:
+  - reference `standards/*` instead of re-copying.
+
+## Canonical locations
+- Agent definitions: `agents/`
+- Tool entrypoints: `commands/`
+- Procedures/playbooks: `skills/`
+- Governance: `standards/`
+- Templates: `templates/`
+- Context rules: `context/`
+- Memory rules: `memory/`
+- Validation rules: `validation/`
+
+## Quality Gate
+Any change to structure MUST include an updated tree and rationale in a decision log.

package/src/iris_bundle/.iris/aidlc/standards/documentation-rules.md

@@ -0,0 +1,15 @@
+# Documentation Rules
+
+## Purpose
+Make outputs actionable, reviewable, and enforceable.
+
+## Hard Rules
+- Any plan MUST specify:
+  - exact file paths it will create/modify
+  - acceptance criteria and verification method
+  - stop conditions (when to halt for missing inputs)
+- “Done” MUST be measurable.
+- A unit/bolt MUST be small enough to implement and verify in one cycle.
+
+## MUST NOT
+- Avoid vague verbs (“handle”, “improve”, “optimize”) without measurable criteria.

package/src/iris_bundle/.iris/aidlc/standards/file-structure.md

@@ -0,0 +1,21 @@
+# File Structure Standard
+
+## Purpose
+Define canonical repo locations used by IRIS.
+
+## Hard Rules
+- IRIS doctrine MUST live at: `.iris/aidlc/`
+- Project memory MUST live at: `memory-bank/`
+- Canonical memory-bank folders MUST exist:
+  - `memory-bank/intents/`
+  - `memory-bank/units/`
+  - `memory-bank/bolts/`
+  - `memory-bank/standards/`
+  - `memory-bank/logs/`
+
+## MUST NOT
+- Do not store project decisions only in chat history.
+- Do not introduce alternate memory roots unless doctrine is updated.
+
+## Quality Gate
+A repo is not “IRIS-ready” until the memory-bank exists.

package/src/iris_bundle/.iris/aidlc/standards/naming-conventions.md

@@ -0,0 +1,18 @@
+# Naming Conventions
+
+## Purpose
+Ensure artifacts are predictable and routable.
+
+## Hard Rules
+- Filenames and folders MUST be `kebab-case`.
+- Agent docs MUST be prefixed with `iris-` and end with `-agent.md`.
+- Commands MUST be prefixed with `iris-` and match the agent name.
+- Logs MUST be prefixed with `YYYY-MM-DD__`.
+
+## Recommended patterns
+- Unit folder: `memory-bank/units/<unit-slug>/`
+- Bolt folder: `memory-bank/bolts/<unit-slug>/<bolt-slug>/`
+
+## Failure Modes & Recovery
+- Failure: inconsistent naming prevents routing/validation.
+  - Recovery: rename to kebab-case and update references.

package/src/iris_bundle/.iris/aidlc/standards/phases-and-gates.md

@@ -0,0 +1,25 @@
+# Phases & Gates
+
+## Purpose
+Define SDLC phases and forbid phase skipping.
+
+## Phases
+1. **Inception**
+   - Output: approved intent + approved units + kickoff log
+2. **Construction**
+   - Output: implementation + verification evidence + completion log
+3. **Operations**
+   - Output: handover log + incident/runbook logs as needed
+
+## Allowed transitions
+- Inception → Construction
+- Construction → Operations
+- Operations → Inception (new intent only)
+
+## Hard Rules
+- Construction MUST NOT begin without an approved unit.
+- Operations MUST NOT begin without accepted verification evidence.
+
+## Gate authority
+- Master Agent is gatekeeper by default.
+- Delegation is allowed but MUST be logged.

package/src/iris_bundle/.iris/aidlc/standards/routes-and-routing.md

@@ -0,0 +1,35 @@
+# IRIS Routing Doctrine
+
+## Purpose
+Define how IRIS maps user intent to the correct agent command **without ambiguity** and **without hidden heuristics**.
+
+## Scope
+This standard governs:
+- `.iris/routes.yaml` format and semantics
+- Required routing metadata (rationale, exclusions, required context)
+- How tools and Navi MUST apply routing
+
+## Hard Rules
+- Routing MUST be deterministic: same input → same route selection given same routes file.
+- Routing MUST be explainable: every match MUST include a rationale.
+- Routing MUST include exclusions to prevent false positives.
+- If no route matches with high confidence, IRIS MUST fall back to **iris-master-agent** and request clarification.
+
+## Route precedence
+1. Exact phrase matches
+2. Strong keyword matches (all required keywords present)
+3. Weak keyword matches (some keywords present) — only if no strong match exists
+4. Default route: `iris-master-agent`
+
+## Output of routing
+A router MUST output:
+- `route_id`
+- selected `command`
+- `why` (the route rationale)
+- `missing_context` (if required context is absent)
+- suggested next action (which artifact to create first)
+
+## Anti-patterns
+- DO NOT route directly to Construction when Inception artifacts are missing.
+- DO NOT route to Operations for requests that change scope/architecture.
+- DO NOT invent routes at runtime; update `.iris/routes.yaml` instead.

package/src/iris_bundle/.iris/aidlc/standards/tool-wrappers.md

@@ -0,0 +1,32 @@
+# Tool Wrapper Doctrine
+
+## Purpose
+Ensure tool-specific command wrappers (Claude/Cursor/Gemini/Antigravity/Codex) invoke IRIS consistently.
+
+## Hard Rules
+- Tool wrappers MUST be thin: they MUST NOT redefine doctrine. They MUST reference `.iris/aidlc/**`.
+- Tool wrappers MUST instruct the tool to load:
+  1) the requested IRIS command entrypoint
+  2) the minimum required memory-bank artifacts for that phase
+  3) any repo-local constraints (e.g., `specs.md`, `README.md`, `package.json` if present)
+- Tool wrappers MUST forbid destructive operations unless explicitly requested.
+- Tool wrappers MUST require the agent to produce artifacts into `memory-bank/` using IRIS templates.
+
+## Minimum context set
+All wrappers MUST load:
+- `.iris/aidlc/context/load-order.md`
+- `.iris/aidlc/standards/phases-and-gates.md`
+- `.iris/aidlc/standards/artifacts-registry.md`
+- `.iris/aidlc/validation/phase-preconditions.md`
+
+Plus phase-specific memory-bank files:
+- Inception: `memory-bank/intents/*`
+- Construction: `memory-bank/units/*`, `memory-bank/bolts/*`
+- Operations: `memory-bank/logs/*`, `memory-bank/standards/*`
+
+## Wrapper content requirements
+Each wrapper MUST include:
+- What the command does
+- What inputs it needs
+- What files it MUST write/update
+- Stop conditions

package/src/iris_bundle/.iris/aidlc/templates/bolt.md

@@ -0,0 +1,23 @@
+# Bolt: <title>
+
+## Status
+Draft | Ready | Executed | Verified
+
+## Objective
+<one sentence>
+
+## Preconditions
+- Approved unit: `memory-bank/units/<unit>/unit.md`
+
+## Steps
+1.
+2.
+
+## Files to Change
+- <path>
+
+## Verification
+- Commands:
+  - `<command>`
+- Evidence location:
+  - `memory-bank/units/<unit>/review.md` or `memory-bank/logs/...`

package/src/iris_bundle/.iris/aidlc/templates/doctrine-doc-template.md

@@ -0,0 +1,33 @@
+# <Title>
+
+## Purpose
+<One sentence: why this exists.>
+
+## Scope
+- In scope:
+- Out of scope:
+
+## Inputs
+- <required inputs + locations>
+
+## Outputs
+- <guaranteed outputs + locations>
+
+## Hard Rules
+- MUST:
+- MUST NOT:
+- SHOULD (only if necessary):
+
+## Procedure
+1.
+2.
+3.
+
+## Quality Gates
+- Gate 1:
+- Gate 2:
+
+## Failure Modes & Recovery
+- Failure:
+  - Symptom:
+  - Recovery:

package/src/iris_bundle/.iris/aidlc/templates/intent.md

@@ -0,0 +1,23 @@
+# Intent: <title>
+
+## Status
+Draft | Approved | Archived
+
+## Problem
+<What is broken or missing?>
+
+## Goals
+- [ ] <measurable goal>
+
+## Non-goals
+- <explicit exclusions>
+
+## Constraints
+- <time/tech/policy>
+
+## Definition of Done
+- [ ] <observable criteria>
+- Verification: <how to verify>
+
+## Notes
+<links to units/logs>

package/src/iris_bundle/.iris/aidlc/templates/log.md

@@ -0,0 +1,24 @@
+# Log: <topic>
+
+## Date
+YYYY-MM-DD
+
+## Context
+<what triggered this?>
+
+## Decision / Event
+<what happened?>
+
+## Options Considered
+- A:
+- B:
+
+## Outcome
+<chosen action + result>
+
+## Tradeoffs / Risks
+- <tradeoff>
+- <risk>
+
+## Next Actions
+- [ ] <action>

package/src/iris_bundle/.iris/aidlc/templates/review.md

@@ -0,0 +1,21 @@
+# Review: <unit/bolt>
+
+## Gate
+Inception | Construction | Operations
+
+## Checklist
+- [ ] Acceptance criteria met
+- [ ] Tests executed
+- [ ] Evidence recorded
+- [ ] Logs recorded
+- [ ] Rollback documented (if applicable)
+
+## Evidence
+- Unit: `memory-bank/units/<unit>/unit.md`
+- Logs: `memory-bank/logs/...`
+- Test output: <snippet/link>
+
+## Decision
+Accepted | Rejected
+
+## Notes

package/src/iris_bundle/.iris/aidlc/templates/unit.md

@@ -0,0 +1,31 @@
+# Unit: <title>
+
+## Status
+Draft | Approved | In Progress | Done | Archived
+
+## Scope
+<what is included?>
+
+## Out of Scope
+<what is excluded?>
+
+## Interfaces / Contracts
+- <api/schema/format changes>
+
+## Files Impacted (expected)
+- <path>
+
+## Acceptance Criteria
+- [ ] <criterion>
+
+## Test Plan
+- <commands/tests>
+
+## Risks
+- <risk> → <mitigation>
+
+## Rollback Plan
+<how to revert>
+
+## Links
+- Intent: `memory-bank/intents/<intent>.md`

package/src/iris_bundle/.iris/aidlc/validation/failure-modes.md

@@ -0,0 +1,16 @@
+# Failure Modes & Recovery
+
+## Missing prerequisites
+- Stop immediately.
+- Create missing artifacts using templates.
+- Log the decision/event.
+- Re-run checklist.
+
+## Phase skipping
+- Return to prior phase.
+- Produce approvals and evidence.
+- Only then proceed.
+
+## Unbounded scope
+- Split into smaller units.
+- Ensure each unit has measurable acceptance criteria.

package/src/iris_bundle/.iris/aidlc/validation/phase-preconditions.md

@@ -0,0 +1,21 @@
+# Phase Preconditions & Exit Criteria
+
+## Inception — Exit to Construction (REQUIRED)
+MUST exist:
+- `memory-bank/intents/<intent>.md` with `Status: Approved`
+- `memory-bank/units/<unit>/unit.md` with `Status: Approved`
+- `memory-bank/logs/<date>__inception-kickoff.md`
+
+## Construction — Entry (REQUIRED)
+MUST exist:
+- Approved unit: `memory-bank/units/<unit>/unit.md`
+- Ready bolt: `memory-bank/bolts/<unit>/<bolt>/bolt.md` with `Status: Ready`
+
+## Construction — Exit to Operations (REQUIRED)
+MUST exist:
+- Evidence in `memory-bank/units/<unit>/review.md` (Accepted) OR a log with equivalent evidence
+- `memory-bank/logs/<date>__construction-complete.md`
+
+## Operations — Entry (REQUIRED)
+MUST exist:
+- `memory-bank/logs/<date>__ops-handover.md`