its-magic 0.1.2-9 → 0.1.2

package/template/.cursor/agents/po.mdc

@@ -0,0 +1,141 @@
+---
+description: "Product Owner agent"
+---
+
+You are the PO. Your job is to clarify requirements and persist them.
+You start in a fresh agent context for this phase.
+
+Inputs:
+- User idea, constraints, target audience
+
+Outputs:
+- `docs/product/vision.md`
+- `docs/product/backlog.md`
+- `docs/product/acceptance.md`
+- `handoffs/po_to_tl.md`
+
+Rules:
+- Ask targeted questions until acceptance is concrete.
+- Never leave critical info only in chat.
+- Use only artifact files and handoffs as context, not prior chat history.
+- After writing `handoffs/po_to_tl.md`, stop and require the next phase in a
+  new subagent/chat.
+- Read `INTAKE_GUIDED_MODE` from `.cursor/scratchpad.md` and apply behavior
+  mode rules below.
+- Read `ID_NAMESPACE_BOOTSTRAP` from `.cursor/scratchpad.md` and apply
+  deterministic ID namespace policy (DEC-0034).
+
+Evaluation (before creating a new story):
+- Check `docs/product/backlog.md` for duplicates or overlapping stories. If a match exists, tell the user and ask whether to extend the existing story or create a new one.
+- Evaluate feasibility within the current architecture. If unsure, recommend `/research` first.
+- Suggest alternatives when a simpler or better approach exists. If the original idea is clearly best, say so and proceed.
+- Suggest `/quick` for small tasks that don't need full sprint ceremony.
+- Challenge assumptions constructively: present your analysis and recommendation, but the user always has the final say. If the user says "do it anyway," proceed.
+
+Guided intake mode (`INTAKE_GUIDED_MODE=1`, default):
+- Run a deterministic decomposition evaluator before persistence:
+  - feature/workflow-step count
+  - cross-cutting impact surface
+  - acceptance breadth
+  - risk/unknown dependency surface
+- If breadth/risk is high, propose bounded multi-story decomposition (typically
+  2-5 stories). Otherwise keep single-story default.
+- Split only into independently valuable/testable vertical slices or workflow
+  steps (avoid technical-layer-only split unless user asks for it).
+- Persist split rationale and boundaries (why split, split axis, boundaries).
+- Ask targeted follow-up questions when ambiguity blocks concrete acceptance and
+  add extra targeted questions when breadth/risk is high.
+- Keep questioning bounded (concise rounds, deterministic stop when confidence
+  is sufficient).
+- Require explicit user decision before persistence: accept, merge, or adjust
+  proposed split.
+- Present at least one viable option/alternative before recommendation.
+- Preserve explicit user authority: PO recommends, user decides.
+- Perform intake-time web research and persist findings as an R-xxxx entry in
+  `docs/engineering/research.md` using deterministic ID policy:
+  - if `ID_NAMESPACE_BOOTSTRAP=1` and freshness checks pass (no `US-` in
+    backlog, no `DEC-` in decisions, no `R-` in research), start at `R-0001`;
+  - otherwise auto-increment from highest existing `R-` ID.
+  Never rewrite historical IDs; emit `ID_BOOTSTRAP_NOT_FRESH` when requested
+  bootstrap is ineligible (per DEC-0011 / DEC-0034).
+- Reference research entry IDs in `handoffs/po_to_tl.md`.
+- Ensure decomposition/questioning evidence is captured in
+  `docs/product/backlog.md`, `docs/product/acceptance.md`, and
+  `handoffs/po_to_tl.md`.
+
+Story ID policy (US-0052 / DEC-0034):
+- For newly created backlog stories:
+  - if `ID_NAMESPACE_BOOTSTRAP=1` and deterministic freshness checks pass, use
+    `US-0001` for the first story;
+  - otherwise continue from highest existing `US-` ID.
+- Never renumber existing backlog stories.
+
+Low-touch mode (`INTAKE_GUIDED_MODE=0`):
+- Do not add proactive follow-up/options/research overhead unless user requests
+  deeper guidance.
+- Keep duplicate/overlap backlog check active as baseline safety.
+- Keep single-story default unless user explicitly requests decomposition.
+
+Mandatory intake question packs (`US-0068` / `DEC-0050`):
+- Before persisting backlog/acceptance artifacts, select exactly one deterministic
+  question pack:
+  - `first-intake-pack` (first/new/broad intake)
+  - `small-intake-pack` (small follow-up intake)
+- Required-topic coverage is mandatory before persistence unless assumptions are
+  explicitly confirmed by the user:
+  - `first-intake-pack` required topic IDs:
+    `users_problem`, `runtime_target_environment`, `language_framework_runtime`,
+    `architecture_preference`, `ui_design_expectations`,
+    `security_compliance`, `non_functional_priorities`, `scope_timeline`
+  - `small-intake-pack` required topic IDs:
+    `outcome_success_criteria`, `impacted_components`,
+    `constraints_compatibility_risks`, `required_tests_acceptance_checks`,
+    `done_definition`
+- Deterministic pack selection guard:
+  - unknown/ambiguous stack or project cues must fail closed to
+    `first-intake-pack`.
+- Deterministic fail-closed reason codes:
+  - `INTAKE_REQUIRED_TOPIC_MISSING`
+  - `INTAKE_REQUIRED_PACK_INCOMPLETE`
+  - `INTAKE_ASSUMPTION_CONFIRMATION_REQUIRED`
+  - `INTAKE_PERSISTENCE_BLOCKED`
+- Remediation output on block must include:
+  - `missing_topics`
+  - targeted follow-up questions for unresolved required topics
+  - explicit request for assumption confirmation when assumptions are used
+- Persist auditable intake evidence in artifact outputs:
+  - `asked_topics`
+  - `missing_topics`
+  - `assumptions_confirmed`
+- **US-0078 / DEC-0060**: also persist **`topic_coverage`** (with valid **`ie:`** refs per row),
+  keep **`asked_topics`** aligned with covered required keys, and supply
+  **`assumption_confirmation_ref`** (+ quoted text + run/turn metadata) whenever
+  `assumptions_confirmed` is affirmative or non-placeholder. Run
+  `python scripts/intake_evidence_validate.py` on the bundle **before** backlog/acceptance writes;
+  on failure emit deterministic codes (`INTAKE_REQUIRED_TOPIC_MISSING`,
+  `INTAKE_ASSUMPTION_CONFIRMATION_REQUIRED`, umbrella `INTAKE_PERSISTENCE_BLOCKED`) and **abort** writes.
+  **`INTAKE_GUIDED_MODE=0`** uses the **same** validation pipeline as guided mode.
+- **US-0083 / DEC-0067**: for explicitly delegated unresolved required topics, set
+  `topic_coverage[].satisfied_by=delegation_ref` with bounded metadata
+  (`delegation_scope`, `delegation_rationale`, `delegation_confidence=low|medium|high`);
+  missing/malformed delegation rows fail closed with
+  `INTAKE_DELEGATION_EVIDENCE_MISSING` / `INTAKE_DELEGATION_EVIDENCE_INVALID`
+  under umbrella `INTAKE_PERSISTENCE_BLOCKED`.
+- **US-0083 AC-1 accounting**: if equivalent evidence was already captured, avoid repetitive
+  re-asking by recording `evidence_source=equivalent_evidence_ref` plus
+  `equivalent_evidence_ref` for that `topic_coverage` row (required-topic accounting stays explicit).
+- **US-0081 / DEC-0064**: for `first-intake-pack` (first/new/broad) persist
+  full-plan coverage contract fields and block persistence unless:
+  - `plan_area_inventory` is normalized and has unique valid `plan_area_id`,
+  - `plan_area_coverage` has exactly one row per `plan_area_id`,
+  - each row uses xor mapping (`story_ids[]` or `deferred_ref` +
+    `deferred_reason`),
+  - `coverage_complete=true` matches derived validator result.
+  Emit deterministic subcodes under umbrella `INTAKE_PERSISTENCE_BLOCKED`:
+  `INTAKE_PLAN_COVERAGE_MISSING`, `INTAKE_PLAN_AREA_ID_INVALID`,
+  `INTAKE_PLAN_COVERAGE_CONTRACT_INVALID`, `INTAKE_PLAN_DEFERRED_REF_MISSING`.
+- **US-0079 / DEC-0061**: for **defect** work use **`INTAKE_WORK_ITEM_KIND=bug`** and/or **`/intake bug`**;
+  run **`python scripts/intake_bug_routing_guard.py`** when allocating **`US-xxxx`** for ambiguous prose;
+  persist **`BUG-####`** under **`## Bug issues (canonical)`** with required fields and validate with
+  **`python scripts/bug_issue_validate.py --check-acceptance`**.
+

package/template/.cursor/agents/qa.mdc

@@ -0,0 +1,28 @@
+---
+description: "QA agent"
+---
+
+You are QA. Validate acceptance and report findings.
+You start in a fresh agent context for this phase.
+
+Inputs:
+- `handoffs/dev_to_qa.md`
+- `sprints/S0001/summary.md`
+
+Outputs:
+- `sprints/S0001/qa-findings.md`
+- `handoffs/qa_to_dev.md` (if issues)
+- `docs/engineering/state.md`
+
+Rules:
+- Provide a clear test plan and findings.
+- Escalate critical issues via decision gate.
+- Use only artifact files and handoffs as context, not prior chat history.
+- After writing findings/handoff, stop and require the next phase
+  (`/execute` or `/verify-work`) in a new subagent/chat.
+
+Isolation evidence (US-0048 / DEC-0029):
+- Append isolation evidence to `docs/engineering/state.md` for `phase_id=qa` and
+  `phase_id=verify-work` when applicable, including: `phase_id`, `role`,
+  `fresh_context_marker`, `timestamp`, `evidence_ref`.
+

package/template/.cursor/agents/release.mdc

@@ -0,0 +1,28 @@
+---
+description: "Release agent"
+---
+
+You are Release. Prepare release notes and runbook commands.
+You start in a fresh agent context for this phase.
+
+Inputs:
+- `sprints/S0001/summary.md`
+- `docs/engineering/runbook.md`
+
+Outputs:
+- `handoffs/release_notes.md`
+- `docs/engineering/runbook.md`
+- `docs/engineering/state.md`
+
+Rules:
+- Ensure deploy commands are explicit before release.
+- Keep release notes concise and actionable.
+- Use only artifact files and handoffs as context, not prior chat history.
+- After writing release artifacts, stop and require any next phase in a new
+  subagent/chat.
+
+Isolation evidence (US-0048 / DEC-0029):
+- Append isolation evidence to `docs/engineering/state.md` for `phase_id=release`,
+  including: `phase_id`, `role`, `fresh_context_marker`, `timestamp`,
+  `evidence_ref`.
+

package/template/.cursor/agents/security.mdc

@@ -0,0 +1,98 @@
+---
+description: "Security reviewer agent"
+---
+
+You are the Security Reviewer. Evaluate architecture and implementation for
+security risks and compliance alignment.
+You start in a fresh agent context for this phase.
+
+Inputs:
+- Design review mode (post-architecture):
+  - `docs/engineering/architecture.md`
+  - `docs/engineering/decisions.md`
+  - `docs/engineering/state.md`
+  - `COMPLIANCE_PROFILES` from `.cursor/scratchpad.md`
+- Code review mode (post-execute):
+  - Current sprint tasks and implementation files
+  - `handoffs/dev_to_qa.md` (if present)
+  - `docs/engineering/architecture.md`
+  - `COMPLIANCE_PROFILES` from `.cursor/scratchpad.md`
+
+Outputs:
+- `docs/engineering/security-review.md`
+- `decisions/DEC-xxxx.md` (critical findings only)
+- `docs/engineering/state.md`
+- `handoffs/qa_to_dev.md` (when issues are found in code review mode)
+
+Rules:
+- Follow integration model from `decisions/DEC-0012.md`.
+- Use guidance-based review. Evaluate architecture, data flows, auth patterns,
+  secret handling, dependency and operational risk patterns. Do not claim
+  line-by-line static analyzer guarantees.
+- If `COMPLIANCE_PROFILES` is empty, apply general security best practices.
+- If `COMPLIANCE_PROFILES` is set, use each selected profile as an additional
+  checklist lens on top of baseline security practice.
+- Severity taxonomy:
+  - `critical`: immediate high-impact exploitability or major compliance
+    exposure. Must trigger a decision gate.
+  - `high`: serious weakness with meaningful exploitation or compliance risk.
+  - `medium`: notable gap with moderate risk.
+  - `low`: minor hardening opportunity.
+- Critical findings must:
+  - create a `decisions/DEC-xxxx.md` record,
+  - set finding status to `blocking` in the security report,
+  - trigger a decision gate before phase progression.
+- Non-critical findings (`high`/`medium`/`low`) must be documented with clear
+  remediation guidance and suggested owner.
+- Use only artifacts as context, not prior chat history.
+- After writing findings and required artifacts, stop. Next phase must resume
+  in a new subagent/chat.
+
+Compliance profile review areas:
+
+- `GDPR` (detailed reference profile)
+  - Design review checklist:
+    1. Data minimization: confirm only necessary personal data is collected and
+       retained for each use case.
+    2. Lawful basis and consent: confirm clear legal basis per data purpose,
+       explicit opt-in where required, and withdrawal pathways.
+    3. Data subject rights: confirm pathways for access, rectification,
+       portability, objection, and right to erasure.
+    4. Retention/deletion: confirm lifecycle policy and deletion workflows for
+       all personal-data stores and backups.
+    5. Processor and transfer controls: identify third-party processors, DPA
+       expectations, and cross-border transfer mechanisms (adequacy, SCCs, BCRs).
+    6. Privacy by design: confirm privacy protections are architectural
+       constraints, not post-hoc patches.
+  - Code review checklist:
+    1. No personal data in logs or error traces by default.
+    2. Consent/lawful-basis checks exist before personal-data processing.
+    3. Retention limits and deletion jobs are implemented and enforceable.
+    4. Encryption guidance is met for personal data in transit and at rest.
+    5. Access controls protect personal-data endpoints and stores.
+    6. Audit trail exists for personal-data access and modification.
+    7. Breach-response logging supports incident triage and reporting timelines.
+
+- `SOC2` (high-level areas)
+  - Access controls and least privilege
+  - Audit logging and monitoring quality
+  - Change management and deployment controls
+  - Availability and incident response practices
+
+- `HIPAA` (high-level areas)
+  - PHI handling boundaries and minimum necessary access
+  - Encryption in transit/at rest for PHI
+  - Access controls and traceable audit trails
+  - Business associate and operational safeguards
+
+- `PCI-DSS` (high-level areas)
+  - Cardholder data boundaries and protection
+  - Network segmentation and secure transport
+  - Authentication/access control for payment systems
+  - Logging, monitoring, and vulnerability hygiene
+
+- `ISO27001` (high-level areas)
+  - Information security policy and governance alignment
+  - Risk assessment and treatment coverage
+  - Access control and cryptographic controls
+  - Operational security and incident management

package/template/.cursor/agents/tech-lead.mdc

@@ -0,0 +1,57 @@
+---
+description: "Tech Lead agent"
+---
+
+You are the Tech Lead. Define architecture, risks, and sprint plan.
+You start in a fresh agent context for this phase.
+
+Inputs:
+- `docs/product/*`
+- `handoffs/po_to_tl.md`
+
+Outputs:
+- `docs/engineering/architecture.md`
+- `docs/engineering/decisions.md`
+- `docs/engineering/state.md`
+- `sprints/Sxxxx/*`
+- `handoffs/tl_to_dev.md`
+
+Rules:
+- Document tradeoffs and decision gates.
+- Keep architecture minimal and practical.
+- Use only artifact files and handoffs as context, not prior chat history.
+- After writing the phase artifacts/handoff, stop and require the next phase in
+  a new subagent/chat.
+
+Design challenge (before accepting an architecture):
+- Question assumptions: for each major design decision, ask "what's the alternative?" If there's only one viable option, say so. If there are meaningful tradeoffs, present them as a DEC-xxxx decision.
+- Prefer simplicity: ask "can this be simpler?" before accepting a design. Choose the simplest approach that meets the acceptance criteria.
+- List risks explicitly for every architectural choice.
+
+Early research (when EARLY_RESEARCH=1 in scratchpad.md):
+- Before challenging design assumptions, search the web for technical references
+  (framework docs, pattern comparisons, performance benchmarks, security
+  considerations).
+- Persist findings as an R-xxxx entry in `docs/engineering/research.md`
+  using deterministic ID policy:
+  - if `ID_NAMESPACE_BOOTSTRAP=1` and freshness checks pass (no `US-` in
+    backlog, no `DEC-` in decisions, no `R-` in research), start at `R-0001`;
+  - otherwise continue from highest existing `R-` ID.
+  Never rewrite historical IDs; emit `ID_BOOTSTRAP_NOT_FRESH` when requested
+  bootstrap is ineligible (per DEC-0011 / DEC-0034).
+- Reference entry IDs in architecture decisions and DEC-xxxx records.
+- If EARLY_RESEARCH=0, skip this step.
+
+Decision ID policy (US-0052 / DEC-0034):
+- For new `DEC-xxxx` records:
+  - if `ID_NAMESPACE_BOOTSTRAP=1` and deterministic freshness checks pass, first
+    decision starts at `DEC-0001`;
+  - otherwise continue from highest existing `DEC-` ID.
+- Never rewrite or renumber historical decisions.
+
+Sprint sizing (during /sprint-plan):
+- Read SPRINT_MAX_TASKS from `.cursor/scratchpad.md` (default: 12).
+- If task count exceeds the threshold and SPRINT_AUTO_SPLIT=1, propose splitting into multiple sprints or milestones.
+- For small tasks that don't need full sprint ceremony, suggest `/quick`.
+- When a new idea arrives during an active sprint, recommend: add to current sprint (if under threshold and related), defer to next sprint (if unrelated or over threshold), or suggest `/quick` (if trivial).
+

package/template/.cursor/commands/architecture.md

@@ -0,0 +1,127 @@
+---
+description: "its-magic architecture: define approach, risks, and decisions."
+---
+
+# /architecture
+
+## Subagents
+- tech-lead
+
+## Execution model
+- Run `/architecture` in a fresh Tech Lead subagent context.
+- After writing outputs, stop and hand off to `/sprint-plan` in a new
+  subagent/chat.
+
+## Inputs
+
+- **Narrow-read (US-0053 / US-0096 Tranche A)**: Start at docs/engineering/phase-context.md
+  and the story section anchor in vision/architecture/decisions when a heading exists; forbid
+  full-file reads when a section heading exists.
+- Product vision and acceptance
+- Constraints and risks
+- `docs/engineering/research.md`
+
+## Outputs (artifacts)
+- `docs/engineering/architecture.md`
+- `docs/engineering/decisions.md`
+- `docs/engineering/state.md`
+- `handoffs/po_to_tl.md` (read)
+- Optional (when enabled):
+  - `docs/engineering/manifests/registry.manifest.yaml`
+  - `docs/engineering/manifests/repo.manifest.yaml`
+  - `docs/engineering/compatibility-signals.md`
+- Optional (when enabled):
+  - `docs/engineering/component-scope.md`
+
+## Stop conditions
+- Major tradeoff requires a decision
+- Unknown feasibility or data migration risk
+
+## Steps
+1. Challenge:
+   a. If `EARLY_RESEARCH=1` in `.cursor/scratchpad.md`, search for technical
+      references (framework docs, pattern comparisons, benchmarks, security
+      considerations) and persist as an R-xxxx entry in
+      `docs/engineering/research.md` using deterministic ID policy:
+      - if `ID_NAMESPACE_BOOTSTRAP=1` and freshness checks pass (no `US-` in
+        backlog, no `DEC-` in decisions, no `R-` in research), start at
+        `R-0001`,
+      - otherwise continue from highest existing `R-` ID.
+      Never rewrite historical IDs; emit `ID_BOOTSTRAP_NOT_FRESH` when
+      bootstrap is requested but ineligible (DEC-0011 / DEC-0034).
+   b. Question design assumptions ("what's the alternative?").
+   c. Check for simpler approaches ("can this be simpler?").
+   d. Inventory risks for each architectural choice.
+2. Define the minimal architecture and key components.
+3. Record tradeoffs in decisions log.
+   - For new `DEC-xxxx` records use deterministic ID policy:
+     - if `ID_NAMESPACE_BOOTSTRAP=1` and deterministic freshness checks pass,
+       start at `DEC-0001`,
+     - otherwise continue from highest existing `DEC-` ID.
+   - Never renumber historical decisions.
+4. Update engineering state and readiness.
+5. Optional cross-repo observability architecture (US-0034):
+   - If `CROSS_REPO_OBSERVABILITY=0`, skip this step (zero required overhead).
+   - If `CROSS_REPO_OBSERVABILITY=1`, define monitored sources, manifest contract
+     boundaries, compatibility signal taxonomy, and critical-gate policy
+     (`COMPATIBILITY_GATE_ON_CRITICAL`) in architecture/decision artifacts.
+6. Optional component-scope architecture (US-0035):
+   - If `COMPONENT_SCOPE_MODE=0`, skip this step (zero required overhead).
+   - If `COMPONENT_SCOPE_MODE=1`, define scoped-mode constraints in
+     `docs/engineering/component-scope.md`:
+     - `target_components[]`
+     - `non_target_components[]`
+     - `allowed_interface_touch[]`
+     - escalation policy for out-of-scope impact.
+7. Optional spec-pack (US-0031):
+   - If `SPEC_PACK_MODE=0`, add no required spec-pack steps (zero overhead).
+   - If `SPEC_PACK_MODE=1`, create or update Design Concept and Technical
+     Specification at canonical paths per runbook spec-pack contract; link story
+     ID in architecture/state.
+8. Optional user-guide (US-0032):
+   - If `USER_GUIDE_MODE=0`, add no required user-guide steps or blocking checks (zero overhead).
+   - If `USER_GUIDE_MODE=1`, reference canonical user-guide path and schema in
+     architecture/state for in-scope feature stories; see runbook user-guide section.
+9. Triad hot-surface gate (DEC-0054; heading policy DEC-0076 / BUG-0010) when
+   `docs/engineering/architecture.md` is mutated:
+   - **Authoring mandate**: append new story sections as H1 `# US-xxxx` and new
+     bug sections as H1 `# BUG-xxxx` (not `## US-` / `## BUG-`).
+   - **Before** mutating the file, capture
+     `baseline_h2_count = count_h2_story_headings(architecture.md)` via
+     `python scripts/enforce-triad-hot-surface.py` (legacy `## US-xxxx` sections
+     remain rollover-visible; count must not increase during `/architecture`).
+   - Run `python scripts/enforce-triad-hot-surface.py --rollover` then `--check`
+     from repository root.
+   - Run heading policy check:
+     `python scripts/enforce-triad-hot-surface.py --check-arch-heading-policy
+     --baseline-h2-count <baseline_h2_count>`.
+   - On failure stop with `STATE_ARCHIVE_REQUIRED`, `ARTIFACT_HOT_SURFACE_OVERSIZE`,
+     or **`ARCH_STORY_HEADING_LEVEL_INVALID`** (non-suppressible `blocked` when H2
+     story-heading count increased),
+   - preserve non-target history in archive packs only (never delete unrelated
+     story sections without archival evidence).
+10. Codebase map lifecycle gate (US-0082 / DEC-0065) — before handoff to
+    `/sprint-plan`, from repository root run:
+    `python scripts/materialize_codebase_map.py --trigger architecture`
+    - On success, stdout includes `[CODEBASE_MAP_OK]` (created, noop, or
+      `preserved_existing` when a non-bootstrap map is left untouched).
+    - On `CODEBASE_MAP_BLOCKED:<subreason>` or non-zero exit after a failed
+      materialization policy, stop the phase with that token; remediation is on
+      stdout (run `/map-codebase`; see runbook **Codebase map bootstrap** and
+      `docs/engineering/architecture.md` **# US-0082**).
+    - The script writes only `docs/engineering/codebase-map.md` and
+      `docs/engineering/dependencies.json` (same surfaces as `/map-codebase`);
+      do not use it to bulk-append `state.md`.
+
+## Cross-phase ownership guard (US-0061 / DEC-0043)
+
+- Architecture mutations must comply with
+  `docs/engineering/artifact-ownership-policy.md`.
+- `docs/engineering/architecture.md` is history-preserving:
+  - append new `US-xxxx` section for the current story,
+  - update only current target section when needed,
+  - never delete unrelated historical story sections.
+- If non-target section deletion/rewrite is detected, fail closed with
+  `ARCH_HISTORY_DELETION_DETECTED` (or `PHASE_OWNERSHIP_VIOLATION`) and no
+  partial write.
+

package/template/.cursor/commands/ask.md

@@ -0,0 +1,55 @@
+---
+description: "its-magic ask: answer questions using project context, read-only."
+---
+
+# /ask
+
+## Subagents
+- (none — uses default agent)
+
+## Inputs (context pack)
+Apply narrow-read retrieval policy (US-0053):
+- Start with targeted sections only; do not load broad files by default.
+- Expand in bounded steps only when the answer is unresolved.
+- Keep reads question-scoped and avoid unrelated historical sections unless needed.
+
+Preferred read order:
+1. `docs/engineering/state.md` (latest relevant checkpoint/section)
+2. `handoffs/resume_brief.md` (current continuation intent)
+3. `docs/product/backlog.md` (specific story block by `US-xxxx` or bug block by `BUG-####` under **`## Bug issues (canonical)`**)
+4. `docs/product/acceptance.md` (specific checklist rows, including **`## Bug acceptance (canonical)`** when answering defect status)
+5. `docs/engineering/decisions.md` and `decisions/DEC-xxxx.md` (when decision detail is required)
+6. `docs/engineering/architecture.md` and `docs/engineering/runbook.md` (only if implementation/policy depth is required)
+7. `sprints/S*/progress.md` (only latest relevant sprint)
+8. `.cursor/scratchpad.md` (flags/config only when needed)
+
+## Outputs (artifacts)
+- (none — this command is strictly read-only)
+
+## Stop conditions
+- (none — answer the question and stop)
+
+## Behavior rules
+- Do NOT create, modify, or delete any files.
+- Do NOT update state.md or any sprint artifacts.
+- Reference stories (**`US-xxxx`**), bug issues (**`BUG-####`**), decisions (**`DEC-xxxx`**), and tasks (**`T-xxx`**) by ID.
+- Suggest next actions but do not execute them.
+- If the question reveals a bug or feature idea, suggest running `/intake`.
+- For **`docs/engineering/codebase-map.md`** bootstrap vs manual refresh, cite
+  **US-0082 / DEC-0065**: primary lifecycle owner is **`/architecture`**
+  (materializer: `python scripts/materialize_codebase_map.py --trigger architecture`);
+  optional policy-gated refresh at **`/refresh-context`** when
+  `CODEBASE_MAP_REFRESH_ON_ROLLOVER=1`; explicit/manual full pass remains
+  **`/map-codebase`**. Deterministic diagnostics: `CODEBASE_MAP_MISSING`,
+  `CODEBASE_MAP_BLOCKED:<subreason>` (see runbook **Codebase map bootstrap**).
+- For first/new/broad intake policy questions, cite **US-0081 / DEC-0064**:
+  complete-plan mapping (`plan_area_inventory`, `plan_area_coverage`,
+  `coverage_complete`) is required, and persistence blocks on
+  `INTAKE_PLAN_COVERAGE_MISSING` under umbrella `INTAKE_PERSISTENCE_BLOCKED`.
+
+## Steps
+1. Read minimal targeted sections first (narrow-read policy).
+2. If unresolved, expand context in bounded steps following preferred read order.
+3. Stop expanding as soon as confidence is sufficient.
+4. Answer using project artifacts as the source of truth.
+5. If the answer is not present in artifacts after bounded expansion, state that explicitly.