@damphuquy/agent-init 1.0.2 → 1.1.0

package/templates/AGENTS.md

@@ -1,102 +1,131 @@
 # Repository Agent Guidelines (RIPER-5 Framework)
 
-<agent_guidelines version="2.0">
+<agent_guidelines version="4.0">
 
 <overview>
-  Master operating instructions for AI agents in this subsystem/repository. Establishes the **4 Core Pillars** and the **RIPER-5 Operational Loop**, integrated with the [`process/`](process/README.md) task framework.
+  Entry-point configuration for AI agents in this subsystem. Establishes
+  project-specific settings and wires the two universal layers:
+  - **`.agents/`** — stateless agent-control rules (behavior, guardrails, conventions)
+  - **`process/`** — task workflow, artifact chain, and durable knowledge base
+
+  This file ONLY contains what is unique to this project: toolchain commands,
+  architecture guardrail calibration, and path references.
 </overview>
 
 ---
 
-## 1. Core Foundations
+## 1. Agent Control Layer Reference
+
+<agent_control_ref>
+  The universal agent control rules live in [`.agents/`](.agents/README.md):
+
+  | File | What it governs |
+  |------|----------------|
+  | [`.agents/behavior.md`](.agents/behavior.md) | Mode declaration, session startup, context priority |
+  | [`.agents/guardrails.md`](.agents/guardrails.md) | Retry budget, escalation triggers, completion gate |
+  | [`.agents/conventions/naming.md`](.agents/conventions/naming.md) | Naming and structural hygiene |
+
+  Read these files at session start. They require no project-specific edits.
+</agent_control_ref>
+
+---
+
+## 2. Core Pillars
 
 <foundations>
   <!-- Pillar 1: Task & Specification -->
   <pillar id="task_spec" title="Task & Specification">
-    <rule>Single Source of Truth: Active task file in [`process/features/{feature}/active/`](process/features/) or [`process/general-plans/active/`](process/general-plans/) (instantiated from [`process/_seeds/task-template.md.seed`](process/_seeds/task-template.md.seed)).</rule>
+    <rule>Single Source of Truth: Active task file in [`process/features/active/{feature}/task.md`](process/features/) or [`process/general-plans/active/{task}/task.md`](process/general-plans/) (instantiated from [`process/_seeds/task-template.md.seed`](process/_seeds/task-template.md.seed)).</rule>
     <rule>Define changes via Goal, Current Behavior, Expected Behavior, Invariants, and `<out_of_scope>`.</rule>
     <rule>Acceptance Criteria (AC) must be unambiguous, verifiable markdown checkboxes (`- [ ]`).</rule>
+    <rule>Every task has a master contract (`task.md`) and a full artifact chain: `research.md → decision.md → plan.md → state.md → review.md → handoff.md`.</rule>
   </pillar>
 
   <!-- Pillar 2: Context Navigation -->
   <pillar id="context" title="Context Navigation">
     <rule>Gather minimum sufficient context. No full-repo scanning or drive-by refactoring.</rule>
-    <information_priority>
-      1. Task Spec & AC ([`process/features/**/_SPEC*.md`](process/features/), [`process/general-plans/**/_PLAN*.md`](process/general-plans/), [`process/context/all-context.md`](process/context/all-context.md))
-      2. Relevant Test Suites (`tests/...`)
-      3. Domain Models & Ports (`src/.../domain/`, `src/.../application/port_*`)
-      4. Configuration & DI (`src/.../infrastructure/config/`, `pyproject.toml` / `package.json`)
-      5. Concrete Implementations (`src/.../infrastructure/`, `src/.../application/service/`, `src/.../api/`)
-    </information_priority>
+    <rule>Follow information priority defined in [`.agents/behavior.md`](.agents/behavior.md).</rule>
+    <rule>Project context routes via [`process/context/all-context.md`](process/context/all-context.md).</rule>
   </pillar>
 
   <!-- Pillar 3: Engineering Harness & Guardrails -->
   <pillar id="harness" title="Engineering Harness & Guardrails">
     <validation_commands>
-      # Adapt these commands to your subsystem's toolchain:
-      # e.g., Python: uv run pytest && uv run mypy --strict . && uv run ruff check . && uv run ruff format --check .
-      # e.g., Node/TS: npm run test && npm run typecheck && npm run lint
+      # ── Project-specific: adapt these commands to your toolchain ──
+      # Python:  uv run pytest && uv run mypy --strict . && uv run ruff check . && uv run ruff format --check .
+      # Node/TS: npm run test && npm run typecheck && npm run lint
+      # Go:      go test ./... && go vet ./...
     </validation_commands>
     <architecture_guardrail>
-      Clean Architecture & Dependency Injection provide structural guidance, NOT an instruction to blindly over-engineer simple utilities.
+      Clean Architecture & Dependency Injection provide structural guidance, NOT an
+      instruction to blindly over-engineer simple utilities.
     </architecture_guardrail>
   </pillar>
 </foundations>
 
 ---
 
-## 2. Operational Loop (Pillar 4: RIPER-5 Protocol)
+## 3. RIPER-5 Operating Protocol (Pillar 4: Loop)
+
+<riper5_protocol>
 
-<operational_loop>
-  <phase order="1" name="Research (R)">
-    Ingest active task spec, follow `<information_priority>`, establish domain invariants and boundaries.
+  <!-- ─────────────────── PHASE CONSTRAINTS ─────────────────── -->
+
+  <phase name="RESEARCH" order="1">
+    <constraint>READ-ONLY. No source-code modifications.</constraint>
+    <constraint>No implementation decisions.</constraint>
+    <constraint>No architectural choices.</constraint>
+    <output>Produce/update `research.md`. Classify evidence as Confirmed / Observed / Hypothesized.</output>
+    <gate id="G0">All Research Exit Criteria in `research.md` checked before advancing.</gate>
   </phase>
 
-  <phase order="2" name="Innovate & Plan (I)">
-    Decompose into vertical slices (per [`process/context/planning/all-planning.md`](process/context/planning/all-planning.md)), define step-by-step plan and test cases.
+  <phase name="INNOVATE" order="2">
+    <constraint>READ-ONLY. No source-code modifications.</constraint>
+    <constraint>Present 2–3 viable options with trade-off matrix. Do NOT decide unilaterally.</constraint>
+    <constraint>Never decide public API / DB schema / security policy / business policy without human approval.</constraint>
+    <output>Produce `decision.md`. Leave `<engineer_decision>` blank — human fills it.</output>
+    <gate id="G1">Gate 1 in `decision.md` checked and signed by engineer before advancing to Plan.</gate>
   </phase>
 
-  <phase order="3" name="Produce (P)">
-    Implement scoped atomic edits with strict typing. Preserve public APIs and backward compatibility.
+  <phase name="PLAN" order="3">
+    <constraint>Plan artifacts only. No source-code changes.</constraint>
+    <constraint>Every slice must have a defined verifier, expected evidence, and rollback point.</constraint>
+    <constraint>Scope contract (allowed / forbidden files) must be explicit.</constraint>
+    <output>Produce `plan.md`. Populate Verification Matrix headers.</output>
+    <gate id="G2">Gate 2 in `plan.md` checked and signed by engineer before advancing to Execute.</gate>
   </phase>
 
-  <phase order="4" name="Evaluate (E)">
-    Execute focused test $\rightarrow$ full suite $\rightarrow$ type check $\rightarrow$ lint & format check.
+  <phase name="EXECUTE" order="4">
+    <constraint>Read/write only within the scope approved in `plan.md`.</constraint>
+    <constraint>One slice at a time. Run verifier after each slice. Inspect diff after each slice.</constraint>
+    <constraint>No unrelated refactoring. No changes to forbidden files.</constraint>
+    <constraint>Update `state.md` after every slice.</constraint>
+    <output>Source code + tests + updated `state.md` with verification evidence.</output>
   </phase>
 
-  <phase order="5" name="Reconcile & Review (R)">
-    Inspect `git diff` for zero noise. Safely toggle verified checkboxes (`- [x]`). Move completed task to `completed/`.
+  <phase name="REVIEW" order="5">
+    <constraint>READ-ONLY. May run verification commands.</constraint>
+    <constraint>No code fixes during review. Log findings in `review.md` instead.</constraint>
+    <constraint>Cover: behavior, architecture, data, security, regression.</constraint>
+    <output>Produce `review.md` with findings classified by category/severity/type and Gate 3 checklist.</output>
+    <gate id="G3">Gate 3 in `review.md` checked before handoff. Review decision must be PASS.</gate>
   </phase>
 
-  <retry_budget max_attempts="3">
-    Maximum 3 consecutive attempts per distinct failure symptom. Never bypass errors with suppression flags (e.g. `# type: ignore`, `eslint-disable`). If exhausted, halt and log into `<open_decisions>`.
-  </retry_budget>
-
-  <escalation_and_stop_conditions>
-    Halt immediately and request human guidance if:
-    1. Retry budget is exhausted on a recurring failure.
-    2. Modification requires undeclared changes to public APIs, DB schemas, or security policies.
-    3. Modification requires touching files outside defined boundaries or in `<out_of_scope>`.
-    *Exception:* Do not stop if the change was explicitly authorized by the user in the prompt/spec, or is a mandatory accompanying test/import update.
-  </escalation_and_stop_conditions>
-
-  <completion_gate>
-    A task is COMPLETE only when:
-    1. All Acceptance Criteria in the active task spec are verified (`- [x]`).
-    2. All validation commands execute with zero errors/warnings.
-    3. The final `git diff` contains zero extraneous or unreviewed modifications.
-  </completion_gate>
-</operational_loop>
+  <!-- Behavior rules (mode declaration, retry, escalation, completion gate) →
+       see .agents/behavior.md and .agents/guardrails.md -->
+
+</riper5_protocol>
 
 ---
 
-## 3. Workspace Protocols
+## 4. Workspace Protocols
 
 <workspace_rules>
   <rule id="env">Execute all commands inside the designated runtime virtual environment / harness.</rule>
-  <rule id="sync">Only toggle `- [x]` after Phase 4 (Evaluate) and Phase 5 (Reconcile) pass. Never overwrite human-written specs.</rule>
+  <rule id="sync">Only toggle `- [x]` after the relevant verifier passes. Never overwrite human-written specs.</rule>
   <rule id="isolation">Keep edits within this subsystem unless explicit cross-system coordination is requested.</rule>
   <rule id="subagents">Subagent delegation must adhere to [`process/development-protocols/orchestration.md`](process/development-protocols/orchestration.md).</rule>
+  <rule id="no_stale_context">Re-read relevant files after the repository changes. Do not rely on stale conversation context.</rule>
 </workspace_rules>
 
 </agent_guidelines>

package/templates/process/README.md

@@ -1,57 +1,116 @@
 # Process & Task Orchestration (RIPER-5)
 
-<process_orchestration version="2.0" framework="RIPER-5">
+<process_orchestration version="3.0" framework="RIPER-5">
 
 <overview>
-  Standard template and operational control center for managing engineering tasks and coordinating AI agent execution in this subsystem.
+  Standard template and operational control center for managing engineering tasks and coordinating AI agent execution in this subsystem. Each active task is a self-contained engineering workspace with a full RIPER-5 artifact chain.
 </overview>
 
+---
+
 ## 1. Directory Structure
+
 ```text
 process/
-├── README.md                    # Operational guide (this file)
-├── _seeds/                      # Read-only archetype blueprints and templates
-│   ├── _GUIDE.md                # Guide on using seeds
-│   ├── task-template.md.seed    # Archetype for single tasks (SPEC, PLAN, REPORT)
-│   ├── program-template.md.seed # Archetype for multi-phase programs (Umbrella PLAN)
-│   └── context-group.md.seed    # Archetype for domain context routers
-├── context/                     # Durable knowledge base & context routers
-│   ├── all-context.md           # Root context router
-│   └── planning/all-planning.md # Planning calibration & vertical slicing rules
-├── development-protocols/       # System rules & execution harness
+├── README.md                         # Operational guide (this file)
+├── _seeds/                           # Read-only archetype blueprints
+│   ├── _GUIDE.md                     # Full catalog, artifact chain, and instantiation commands
+│   ├── task-template.md.seed         # Master contract & RIPER state record
+│   ├── context-group.md.seed         # Research phase artifact
+│   ├── decision-template.md.seed     # Innovate phase artifact (Gate 1 memory)
+│   ├── plan-template.md.seed         # Plan phase artifact (execution contract, Gate 2)
+│   ├── state-template.md.seed        # Execute loop persistent memory
+│   ├── review-template.md.seed       # Review phase artifact (Gate 3)
+│   ├── handoff-template.md.seed      # Final projection (short)
+│   └── program-template.md.seed      # Multi-phase program blueprint
+├── context/                          # Durable knowledge base & context routers
+│   ├── all-context.md                # Root context router
+│   └── planning/all-planning.md      # Planning calibration & vertical slicing rules
+├── development-protocols/            # System rules & execution harness
 │   ├── all-development-protocols.md
-│   ├── orchestration.md         # Subagent delegation rules
-│   └── implementation-standards.md # Typing, linting, and testing standards
-├── features/                    # Domain features (≥5 files / ≥3 phases)
-│   ├── active/                  # Active task folders: {task_slug}_{dd-mm-yy}/
-│   ├── completed/               # Archived task folders
-│   └── backlog/                 # Backlog notes: {note_slug}_NOTE_{dd-mm-yy}.md
-└── general-plans/               # Cross-cutting & standalone tasks
+│   ├── orchestration.md              # Subagent delegation rules
+│   └── implementation-standards.md  # Typing, linting, and testing standards
+├── features/                         # Domain features (≥5 files / ≥3 phases)
+│   ├── active/                       # Active task workspaces: {CHG-ID}-{task-slug}/
+│   │   └── CHG-XXX-example/          # One folder per task
+│   │       ├── task.md               # Master contract & state record
+│   │       ├── research.md           # Research phase output
+│   │       ├── decision.md           # Innovate phase output
+│   │       ├── plan.md               # Plan phase output
+│   │       ├── state.md              # Execute loop memory
+│   │       ├── review.md             # Review phase output
+│   │       └── handoff.md            # Final projection
+│   ├── completed/                    # Archived task workspaces
+│   └── backlog/                      # Backlog notes: {note_slug}_NOTE_{dd-mm-yy}.md
+└── general-plans/                    # Cross-cutting & standalone tasks
     ├── active/
     ├── completed/
     └── backlog/
 ```
 
-## 2. The RIPER-5 Operational Flow
+---
+
+## 2. RIPER-5 Artifact Chain
+
+Every task produces a sequential chain of artifacts. Create them progressively as the task advances:
+
+```text
+task.md          ← (always) Master contract, RIPER phase/gate state, AC, decisions
+research.md      ← (Research) Execution flow, evidence, boundaries
+decision.md      ← (Innovate) Options, trade-offs, Gate 1 — engineer must approve
+plan.md          ← (Plan) Slices, verifiers, scope contract, Gate 2 — engineer must approve
+state.md         ← (Execute) Per-slice progress, failure memory, retry budget
+review.md        ← (Review) Findings, verification matrix, Gate 3
+handoff.md       ← (Complete) Short final projection
+```
+
+### Concept → Artifact mapping
+
+| Concept | Artifact |
+|---|---|
+| Task / Spec | `task.md` |
+| Research / Context | `research.md` |
+| Innovate / Decision | `decision.md` |
+| Plan | `plan.md` |
+| Loop state | `state.md` |
+| Execute | source code + tests + `state.md` |
+| Review | `review.md` |
+| Handoff | `handoff.md` |
+| Gate 1 | `decision.md` approval |
+| Gate 2 | `plan.md` approval |
+| Gate 3 | `review.md` approval |
+| Harness / Policy | `AGENTS.md` + `development-protocols/` |
+
+---
+
+## 3. RIPER-5 Operational Phases
+
 <operational_phases>
   <phase order="1" name="Research">
-    Ingest task spec and follow `<information_priority>` (Spec $\rightarrow$ Tests $\rightarrow$ Domain $\rightarrow$ Config $\rightarrow$ Target code).
+    READ-ONLY. Ingest task spec; follow `<information_priority>`; produce `research.md`.
+    Classify evidence: Confirmed / Observed / Hypothesized.
+    Pass Research Exit Criteria (Gate 0) before advancing.
   </phase>
 
-  <phase order="2" name="Innovate & Plan">
-    Decompose into vertical slices; populate the execution plan.
+  <phase order="2" name="Innovate">
+    READ-ONLY. Present 2–3 options with trade-off matrix. Do not decide unilaterally.
+    Produce `decision.md`. Engineer approves Gate 1.
   </phase>
 
-  <phase order="3" name="Produce">
-    Apply minimal atomic edits with strict typing.
+  <phase order="3" name="Plan">
+    Plan artifacts only — no source changes.
+    Decompose into vertical slices with verifiers, rollback points, and scope contract.
+    Produce `plan.md`. Engineer approves Gate 2.
   </phase>
 
-  <phase order="4" name="Evaluate">
-    Run test suites, static type checking, linter and code format checks.
+  <phase order="4" name="Execute">
+    Read/write only within approved scope from `plan.md`.
+    One slice at a time. Run verifier after each slice. Update `state.md` after each slice.
   </phase>
 
-  <phase order="5" name="Reconcile & Review">
-    Inspect `git diff`, update checkboxes (`- [x]`), verify all Acceptance Criteria.
+  <phase order="5" name="Review">
+    READ-ONLY. May run verification commands. No code fixes.
+    Produce `review.md` with findings. Gate 3 must pass before handoff.
   </phase>
 </operational_phases>
 

package/templates/process/_seeds/_GUIDE.md

@@ -1,30 +1,141 @@
 # Seeds & Archetypes Scaffolding Guide
 
-<seeds_guide version="1.0">
+<seeds_guide version="2.0" framework="RIPER-5">
 
 <scope>
   `_seeds/` is a read-only scaffolding directory containing blueprint templates.
-  Copy and instantiate these seeds when defining new tasks, programs, or context routers.
+  Copy and instantiate these seeds when defining new tasks, programs, or context groups.
+  Never edit seeds in-place — always copy first.
 </scope>
 
+---
+
 ## 1. Blueprint Catalog
+
 <catalog>
+
   <seed type="task" path="task-template.md.seed">
-    Standard single-task template covering `_SPEC`, `_PLAN`, `_REPORT`, and verifiable Acceptance Criteria.
+    Master contract and state record for the full RIPER-5 lifecycle.
+    Contains: Task Control metadata, Spec, Context Boundaries, Verification Strategy,
+    Decisions, RIPER-5 Execution Plan (with Gates G0–G3), and Guardrails.
   </seed>
-  
-  <seed type="program" path="program-template.md.seed">
-    Multi-phase program blueprint with umbrella planning, phase breakdown, and blast radius registries.
+
+  <seed type="research" path="context-group.md.seed">
+    Research phase artifact. READ-ONLY during production.
+    Contains: Current Behavior, Execution Flow, Components, Boundaries, Existing Tests,
+    Runtime/Config, Source-of-Truth Analysis, Evidence Classification
+    (Confirmed / Observed / Hypothesized), Assumptions, Impacted Files,
+    Open Decisions, and Research Exit Criteria.
+  </seed>
+
+  <seed type="decision" path="decision-template.md.seed">
+    Innovate phase artifact. Gate 1 memory.
+    Contains: Decision question, Options (A/B/C) with trade-off matrix,
+    Recommendation, Engineer Decision (must be filled by human), Constraints Created,
+    Evidence Still Required, and Gate 1 checklist.
+  </seed>
+
+  <seed type="plan" path="plan-template.md.seed">
+    Plan phase artifact. Execution contract.
+    Contains: Input Artifacts, Execution Constraints (allowed/forbidden files,
+    allowed commands), Slice Summary table, Slice Details (objective, change,
+    verifier, expected evidence, rollback point, stop conditions),
+    Scope Contract, Verification Matrix, and Gate 2 checklist.
+  </seed>
+
+  <seed type="state" path="state-template.md.seed">
+    Execute loop persistent memory. Updated after every slice.
+    Contains: Current Phase/Gate, Task Ref, Goal/Invariants, Approved Decisions,
+    Completed Slices, Current Slice, Current Diff, Verification Evidence,
+    Failure Memory (signature/hypothesis/experiment/result), Retry Budget,
+    Scope Changes, Open Risks, Next Action, and Context Freshness Check.
+  </seed>
+
+  <seed type="review" path="review-template.md.seed">
+    Review phase artifact. Distinct from Handoff.
+    Contains: Review Scope, Behavior Review, Architecture Review, Data Review,
+    Security Review, Regression Review, Findings table (category/severity/type),
+    Verification Matrix, Residual Risk, Review Decision, and Gate 3 checklist.
+  </seed>
+
+  <seed type="handoff" path="handoff-template.md.seed">
+    Final projection artifact. Intentionally short.
+    Answers: What changed? Why? What proves it? What remains risky?
+    Does NOT duplicate research/plan/review artifacts.
   </seed>
 
-  <seed type="context" path="context-group.md.seed">
-    Template for creating domain-specific context routers (`all-{group}.md`).
+  <seed type="program" path="program-template.md.seed">
+    Multi-phase program blueprint with umbrella planning, phase breakdown,
+    blast radius registries, and phase gate rules.
   </seed>
+
 </catalog>
 
-## 2. Instantiation Command
+---
+
+## 2. Artifact Chain per Task
+
+Every active task follows this artifact chain:
+
+```text
+task.md         ← Master contract & RIPER state record
+research.md     ← Research phase output (READ-ONLY mode)
+decision.md     ← Innovate phase output, Gate 1 memory
+plan.md         ← Plan phase output, execution contract, Gate 2
+state.md        ← Execute loop persistent memory (updated per slice)
+review.md       ← Review phase output, Gate 3
+handoff.md      ← Final projection (short)
+```
+
+### Concept → Artifact mapping
+
+| Concept | Artifact |
+|---|---|
+| Task/Spec | `task.md` |
+| Research / Context | `research.md` |
+| Innovate / Decision | `decision.md` |
+| Plan | `plan.md` |
+| Loop state | `state.md` |
+| Execute | source code + tests + `state.md` |
+| Review | `review.md` |
+| Handoff | `handoff.md` |
+| Gate 1 | `decision.md` approval |
+| Gate 2 | `plan.md` approval |
+| Gate 3 | `review.md` approval |
+
+---
+
+## 3. Recommended Task Workspace Layout
+
+```text
+process/features/active/CHG-017-your-feature/
+├── task.md          ← instantiated from task-template.md.seed
+├── research.md      ← instantiated from context-group.md.seed
+├── decision.md      ← instantiated from decision-template.md.seed
+├── plan.md          ← instantiated from plan-template.md.seed
+├── state.md         ← instantiated from state-template.md.seed
+├── review.md        ← instantiated from review-template.md.seed
+└── handoff.md       ← instantiated from handoff-template.md.seed
+```
+
+Not all artifacts are required at start. Create them progressively as the task advances through RIPER phases.
+
+---
+
+## 4. Instantiation Commands
+
 ```bash
-cp process/_seeds/task-template.md.seed process/features/your-feature/active/your-task_PLAN_$(date +%d-%m-%y).md
+# Create a new task workspace
+mkdir -p process/features/active/CHG-XXX-your-feature
+
+# Instantiate seeds into the workspace
+cp process/_seeds/task-template.md.seed     process/features/active/CHG-XXX-your-feature/task.md
+cp process/_seeds/context-group.md.seed    process/features/active/CHG-XXX-your-feature/research.md
+cp process/_seeds/decision-template.md.seed process/features/active/CHG-XXX-your-feature/decision.md
+cp process/_seeds/plan-template.md.seed    process/features/active/CHG-XXX-your-feature/plan.md
+cp process/_seeds/state-template.md.seed   process/features/active/CHG-XXX-your-feature/state.md
+cp process/_seeds/review-template.md.seed  process/features/active/CHG-XXX-your-feature/review.md
+cp process/_seeds/handoff-template.md.seed process/features/active/CHG-XXX-your-feature/handoff.md
 ```
 
 </seeds_guide>

package/templates/process/_seeds/context-group.md.seed

@@ -1,24 +1,154 @@
-# Context Group: [Group Name]
+# Research: [TASK-ID]
 
-<context_group name="[Group Name]" version="1.0">
+<research_context task_id="[TASK-ID]" version="2.0" framework="RIPER-5">
 
-<overview>
-  [Domain-specific knowledge base and architectural references for Group Name.]
-</overview>
+<!-- READ-ONLY PHASE. No source modifications. No implementation decisions. -->
+<research_status>
+  <phase>RESEARCH</phase>
+  <mode>READ-ONLY</mode>
+  <research_owner></research_owner>
+  <last_updated></last_updated>
+</research_status>
 
-## 1. Domain Principles & Invariants
-<domain_invariants>
-  - [Invariant 1 — Core business rule]
-  - [Invariant 2 — Data integrity or architectural constraint]
-</domain_invariants>
+---
+
+## 1. Current Behavior
+
+<current_behavior>
+  [Observable system behavior prior to this change, based on evidence.]
+</current_behavior>
+
+---
+
+## 2. Execution Flow
+
+<execution_flow>
+
+```text
+Entry
+→ ...
+→ ...
+→ Side effect / output
+```
+
+</execution_flow>
+
+---
+
+## 3. Relevant Components
+
+<components>
+
+| File / Symbol | Role | Evidence | Confidence |
+|---|---|---|---|
+| | | | |
+
+</components>
+
+---
+
+## 4. Dependencies & Boundaries
+
+<boundaries>
+  <callers>[Who invokes the target code]</callers>
+  <callees>[What the target code invokes]</callees>
+  <persistence>[Database tables, cache keys, queues]</persistence>
+  <external_systems>[Third-party APIs, message brokers]</external_systems>
+  <transaction_boundary>[Where transactions begin and end]</transaction_boundary>
+  <security_boundary>[Auth context, permission checks, trust boundary]</security_boundary>
+</boundaries>
+
+---
+
+## 5. Existing Tests
+
+<existing_tests>
+
+| Test | Behavior covered | Gap |
+|---|---|---|
+| | | |
+
+</existing_tests>
+
+---
+
+## 6. Runtime / Configuration
+
+<runtime_config>
+  [Environment variables, feature flags, configuration files relevant to this change.]
+</runtime_config>
+
+---
+
+## 7. Source-of-Truth Analysis
+
+<source_of_truth_analysis>
+
+| Source | Says | Authority | Conflict |
+|---|---|---|---|
+| | | | |
+
+</source_of_truth_analysis>
+
+---
+
+## 8. Evidence Classification
+
+<!-- NEVER mix facts, observations, and hypotheses in a single list -->
+<evidence>
+  <confirmed>
+    <!-- Directly verified from code, tests, or authoritative docs -->
+    -
+  </confirmed>
+
+  <observed>
+    <!-- Inferred from behavior, logs, or indirect reading — not directly proven -->
+    -
+  </observed>
+
+  <hypothesized>
+    <!-- Assumptions that still need verification before acting -->
+    -
+  </hypothesized>
+</evidence>
 
 ---
 
-## 2. Key References & System Contracts
-<references>
-  <domain_models>`src/domain/...`</domain_models>
-  <port_interfaces>`src/application/port_...`</port_interfaces>
-  <adapters>`src/infrastructure/...`</adapters>
-</references>
+## 9. Assumptions & Uncertainty
+
+<assumptions>
+  [List any assumptions that drive the research conclusions. Flag each as LOW / MEDIUM / HIGH uncertainty.]
+</assumptions>
+
+---
+
+## 10. Impacted Files
+
+<impacted_files>
+  - `path/to/file` — [Reason for impact]
+</impacted_files>
+
+---
+
+## 11. Open Decisions
+
+<open_decisions>
+  <!-- Unresolved questions that must flow into the Innovate phase decision.md -->
+  -
+</open_decisions>
+
+---
+
+## 12. Research Exit Criteria
+
+<research_exit_criteria>
+  - [ ] Current behavior understood and documented.
+  - [ ] Execution flow traced end-to-end.
+  - [ ] Relevant boundaries identified (callers, callees, persistence, security).
+  - [ ] Source-of-truth conflicts identified or confirmed absent.
+  - [ ] Impacted files identified.
+  - [ ] Evidence classified (Confirmed / Observed / Hypothesized).
+  - [ ] No unresolved research blocker.
+</research_exit_criteria>
 
-</context_group>
+</research_context>