@hanzlaa/rcode 4.10.2 → 4.10.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.10.2",
+  "version": "4.10.4",
   "description": "rcode — the AI team that never forgets. Persistent memory, specialist agents, and slash commands for AI IDEs. Works in Claude Code, Cursor, Gemini, VS Code, and Antigravity.",
   "main": "cli/index.js",
   "bin": {

package/rcode/agents/rcode-planner.md

@@ -24,9 +24,9 @@ rcode sprint planner. Create executable SPRINT.md files with story breakdown, de
 
 **CRITICAL:** Over-splitting ticket-sized work is a bug. Only split when stories exceed 8 AND have independent work streams.
 
-**Hierarchical IDs:** Every story must have a hierarchical ID in its heading: `### Story {sprint-id}.{NN} — {name}`. The orchestrator passes you the `sprint-id` — use it verbatim in all story headings. Format: `NN.S.TT` (Phase.Sprint.Story).
+**Hierarchical IDs:** Every story must have a hierarchical ID on its `<task id="...">` attribute — NOT a markdown heading. `### Story N — Title` headings are a legacy pre-`<task>` format scanner.js only tolerates as a last-resort fallback; writing them as primary output breaks `execute-sprint.md`'s per-task dashboard-state-sync step, which parses `<task id=...>` and the frontmatter block, not headings (confirmed live — issue class #1034-#1036). The orchestrator passes you the `sprint-id` — use it verbatim as `<task id="{sprint-id}.{NN}">`. Format: `NN.S.TT` (Phase.Sprint.Story).
 
-**Output:** Write SPRINT.md (not PLAN.md) using the template at `rcode/templates/sprint.md`. Register the sprint in state via `rcode-tools.cjs state sprint add`.
+**Output:** Write SPRINT.md (not PLAN.md) using the template at `rcode/templates/sprint.md` EXACTLY — YAML frontmatter block (`phase:`/`sprint:`/`owner:`/etc.) followed by `<task>` XML blocks. This is not a style suggestion; downstream tooling parses this file with `grep`/regex against that exact shape, and any deviation (headings instead of `<task>` blocks, bold-label metadata instead of YAML frontmatter) silently breaks dashboard sync while the sprint still executes and commits real code — the failure is invisible until someone checks the dashboard. Register the sprint in state via `rcode-tools.cjs state sprint add`.
 
 Core: Parse user decisions from CONTEXT.md, decompose into sprints with stories, build dependency graphs, derive acceptance criteria per story.
 </role>

package/rcode/references/planner-playbook.md

@@ -64,24 +64,7 @@ Read ONLY when current task needs them. Don't preemptively load.
 
 ## SPRINT.md Frontmatter Template
 
-```yaml
----
-phase: XX-name
-sprint: NN.S
-type: execute | tdd
-wave: N                              # Auto-derived from depends_on
-depends_on: [sprint-id, ...]
-files_modified: [paths...]
-autonomous: true | false             # false if has checkpoints
-requirements: [REQ-01, REQ-02]        # MUST NOT be empty
-owner: yousef                        # OPTIONAL — see below
-
-must_haves:
-  truths: [...]                       # Observable outcomes from user perspective
-  artifacts: [...]                    # Files/models that must exist
-  key_links: [...]                    # Critical connections, breakage points
----
-```
+**`rcode/templates/sprint.md` is the single canonical template — read it now, don't improvise a different structure.** It is not optional/decorative; it is what `execute-sprint.md`'s `owner_agent_resolution` step and its per-task dashboard-state-sync step parse via `grep '^owner:'`/`^phase:'`/`^sprint:'`. A SPRINT.md that free-styles a different structure (bold-label metadata, `### Story N — Title` headings, or any shape without the exact `phase:`/`sprint:`/`owner:` YAML frontmatter block) silently breaks that parsing — the sprint still executes and commits real code, but the dashboard never learns it happened (confirmed live, issue class closed by #1034-#1036's fixes — do not reintroduce it by drifting from the template).
 
 **`owner:` field.** If this plan is grounded in a council session (a `.planning/council-sessions/council-*.md` file is referenced in `<context>` as the authoritative decision), set `owner:` to the id of that session's lead/highest-consensus technical persona for THIS sprint's dominant work — one of `haitham`, `hanzla`, `omar`, `waleed`, `yousef` (the engineer personas with execute permission; `sadiq`/`fatima`/others are advisory-only and never valid here). Pick by domain match: a sprint whose `files_modified` is mostly `src/routes|services|models` → `yousef` (backend); mostly `src/components|pages` → `haitham` (frontend); architecture-level, cross-cutting → `waleed`; general/full-stack with no clear split → `hanzla`. If there was no council session, or the domain split is genuinely ambiguous, omit `owner:` entirely — `execute-sprint.md` defaults to the generic `rcode-executor` when the field is absent. Do not guess an owner just to fill the field; an absent `owner:` is the correct, safe default.
 

package/rcode/templates/sprint.md

@@ -1,19 +1,43 @@
-# Sprint {sprint_id} — {sprint_goal}
+---
+phase: {phase_dir}
+sprint: {sprint_id}
+type: execute | tdd
+wave: {N}
+depends_on: [{sprint_id}, ...]
+files_modified: [{paths...}]
+autonomous: true | false
+requirements: [{REQ-01, REQ-02}]
+owner: {haitham|hanzla|omar|waleed|yousef}    # OPTIONAL — omit if no council session grounds this plan or the domain split is ambiguous; see planner-playbook.md's "owner: field" section
 
-<!-- P2: Omit Dependencies and Risks sections if empty. Omit Retrospective until sprint is complete. -->
+must_haves:
+  truths: [{observable outcomes from the user's perspective}]
+  artifacts: [{files/models that must exist}]
+  key_links: [{critical connections, breakage points}]
+---
 
-**Phase:** {phase_number} — {phase_name}
-**Status:** {status}
-**Velocity target:** {velocity_target} points
-**Started:** {started_at}
+## Sprint {sprint_id}: {one-line sprint goal, plain English, no jargon}
 
-## Sprint Goal
+{2-4 sentence plain-English recap: what this sprint builds and why, written for someone who will never open the XML tags below}
 
-{sprint_goal}
+**Tasks:**
+1. {task 1 title — copy the <title> attribute text verbatim}
+2. {task 2 title}
+3. {task N title}
 
-## Stories
+_Below this line is the execution prompt the agent reads — task bodies, read-first file lists, verification commands. Not meant for skimming._
 
-<!-- One <task> block per story. id= and <title> are REQUIRED (scanner.js's primary parse path) -->
+---
+
+<objective>{what this sprint delivers and why, grounded in the council session or codebase scan}</objective>
+
+<execution_context>
+@.rcode/workflows/execute-sprint.md
+@.rcode/templates/summary.md
+</execution_context>
+
+<context>{council session reference if one grounds this plan, else key codebase facts verified by Read}</context>
+
+<!-- One <task> block per story. id= and title= are REQUIRED (scanner.js's primary parse path — do not use nested <title> tags or "### Story N — name" headings, those are legacy formats scanner.js only supports as a fallback). -->
 <tasks>
 <task id="{sprint_id}.{NN}" type="auto">
 <title>{story title}</title>
@@ -28,53 +52,6 @@
 </task>
 </tasks>
 
-## Capacity
-
-- **Velocity target:** {velocity_target} points
-- **Total committed:** {total_points} points
-- **Buffer:** {buffer_points} points ({buffer_pct}%)
-
-<!-- Omit if no cross-story dependencies exist -->
-## Dependencies
-
-| Story | Depends on | Status |
-|-------|-----------|--------|
-
-<!-- Omit if no risks identified -->
-## Risks
-
-| Risk | Impact | Mitigation |
-|------|--------|------------|
-
-## Files Touched
-
-<!-- Planner must populate before handoff to executor. Used by wave-overlap checker and merge reviewers. -->
-
-**Creates:**
-<!-- - `exact/path/new-file.ts` — one-line responsibility -->
-
-**Modifies:**
-<!-- - `exact/path/existing.ts` — what changes -->
-
-**Tests:**
-<!-- - `tests/exact/path/test.ts` — tests for -->
-
-**Aggregator files (append-only — never replace):**
-<!-- - `packages/shared/src/index.ts` — adds export for X -->
-
-## Sprint Review
-
-<!-- Fill at sprint completion only — omit this section until then -->
-- Stories completed: {done_count}/{total_count}
-- Velocity actual: {velocity_actual} points
-- Carryover: {carryover}
-
-## Retrospective
-
-<!-- Fill at sprint completion only — omit this section until then -->
-### What went well
--
-### What didn't
--
-### Action items
--
+<verification>{how to confirm the whole sprint, not just individual tasks, actually works}</verification>
+<success_criteria>{bullet list — what must be true for this sprint to count as done}</success_criteria>
+<output>Create `.planning/phases/{phase-dir}/{phase}-{plan}-SUMMARY.md`</output>

package/rcode/workflows/council.md

@@ -602,6 +602,14 @@ node .rcode/bin/rcode-tools.cjs state record-council \
 node .rcode/bin/rcode-tools.cjs state record-session
 ```
 
+**Also record the decision itself (closes #1036-adjacent gap — dashboard "Decisions (ADRs)" reads `state.json`'s `decisions[]`, which `record-council` above does NOT populate; only `state add-decision` does).** Write one concise line per DISTINCT consensus decision the council reached — not the full synthesis prose, not one line per panelist. A council session that reached one architectural consensus gets one `add-decision` call; a session with 2-3 genuinely separate decisions gets that many calls. `add-decision` takes the summary as a plain positional argument (no `--summary-file` flag exists on this subcommand — verified against `rcode-tools.cjs`'s actual implementation, don't invent flags), so keep each summary to one shell-safe line:
+
+```bash
+node .rcode/bin/rcode-tools.cjs state add-decision "{one-line consensus decision, e.g. 'Password reset: opaque crypto token, sha256-hashed on existing user record, 15-30min single-use expiry, console-stub email'}"
+```
+
+If the council reached no real consensus (pure disagreement, or panelists only asked clarifying questions), skip this call — don't manufacture a decision that wasn't made.
+
 > **Note:** If `rcode-tools.cjs` state commands fail (e.g. state.json missing or not yet initialized), continue without error — state tracking is optional, the session artifact saved in Step 5 is mandatory.
 
 ## Success Criteria

package/rcode/workflows/execute-sprint.md

@@ -31,7 +31,11 @@ else
 fi
 ```
 
-Use `$EXEC_AGENT` as the `subagent_type` in every Task spawn below (Pattern A, Pattern B subagent route). No other change to the spawn prompt is needed — the persona file's own conditional clause tells it to load the full executor playbook when it sees `subagent_type` = itself and a SPRINT.md path in the prompt. If `$EXEC_AGENT` is a persona and that persona is not installed (agent file missing), fall back to `rcode-executor` and note the fallback in SUMMARY.md's Deviations section — do not fail the sprint over this.
+Use `$EXEC_AGENT` as the `subagent_type` in every Task spawn below (Pattern A, Pattern B subagent route). No other change to the spawn prompt is needed — the persona file's own conditional clause tells it to load the full executor playbook when it sees `subagent_type` = itself and a SPRINT.md path in the prompt.
+
+**Fall back to `rcode-executor` and note the fallback in SUMMARY.md's Deviations section (do not fail the sprint) when:**
+- `$EXEC_AGENT` is a persona and that persona's agent file is not installed in this project, OR
+- The persona agent **declines/refuses the role** — a persona's own scope-discipline and anti-injection instincts may correctly distrust a spawn prompt that merely *asserts* "you are the sprint executor" without provenance from a real `/rcode-execute` dispatch (confirmed live: this happens; a hand-authored trigger reads exactly like a prompt-injection attempt to the persona, and refusing that is the correct default). Detect this by the spawn returning zero commits / zero file changes with a refusal-shaped response (no tool calls, explanation citing lack of authorization or wrong capability lane) rather than a normal execution report. Retry once with `rcode-executor`; do not retry the same persona a second time.
 </step>
 
 <process>