@hanzlaa/rcode 4.10.3 → 4.10.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.10.3",
+  "version": "4.10.5",
   "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/auto-init-guard.md

@@ -5,11 +5,21 @@ Run this check at the very start of any workflow that needs project state.
 ## Step: Detect project initialization
 
 ```bash
-test -f .rcode/config.yaml && echo "rcode-ready" || echo "rcode-not-initialized"
+if [ ! -f .rcode/config.yaml ]; then
+  echo "rcode-not-initialized"
+elif grep -q "Generated by install" .rcode/config.yaml 2>/dev/null && [ ! -f .rcode/JOURNEY.md ]; then
+  echo "rcode-seeded-not-configured"
+else
+  echo "rcode-ready"
+fi
 ```
 
+**Why the middle case matters (confirmed live, issue class closed by #1034-#1036's fixes):** `rcode install` pre-seeds `config.yaml` with installer defaults (`user_name: "$USER"`, `mode: "guided"`, etc.) so the tool has something to read before the user ever runs `/rcode-init`. A plain `test -f .rcode/config.yaml` check can't tell "the user was actually asked their preferences" apart from "the installer wrote plausible-looking defaults nobody confirmed" — both produce a config.yaml that exists. `/rcode-init` itself distinguishes these correctly (via its own `JOURNEY.md`-presence check), but every OTHER workflow that dispatches through this lightweight guard (e.g. `/rcode-do`) was checking existence only, so a user routed entirely through `/rcode-do` could go through many sessions on installer defaults, never once asked their name/language/mode/model-profile — while a user who happened to run `/rcode-init` directly got asked properly. That inconsistency is now closed: `rcode-seeded-not-configured` routes to the same question flow as `rcode-not-initialized` below, just skipping the bin-bootstrap step (already done by install).
+
 **If `rcode-ready`:** continue with the workflow normally.
 
+**If `rcode-seeded-not-configured`:** skip Step 1 (bin bootstrap — install already did this) and go straight to Step 2 (ask the 5 config questions) below, then continue with Steps 3-6 as written (Step 3's `.rcode/config.yaml` write overwrites the installer-seeded stub with real answers).
+
 **If `rcode-not-initialized`:** the user has never set up rcode for this project. Do NOT fail or continue blindly. Run the project init flow inline before proceeding:
 
 ---

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>