@hanzlaa/rcode 4.6.0 → 4.7.1

package/README.md

@@ -23,7 +23,7 @@ pnpm dlx @hanzlaa/rcode install
 [![CI](https://github.com/hanzlahabib/rcode/actions/workflows/test.yml/badge.svg)](https://github.com/hanzlahabib/rcode/actions/workflows/test.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Status: `@hanzlaa/rcode` v4.4.4 on npm. 45 agents · 117 commands · 129 workflows · **1 runtime dependency**. Test status tracked by CI badge above. Actively dogfooded on real projects every week.
+Status: `@hanzlaa/rcode` v4.7.0 on npm. 45 agents · 117 commands · 129 workflows · **1 runtime dependency**. Test status tracked by CI badge above. Actively dogfooded on real projects every week.
 
 ---
 
@@ -49,7 +49,19 @@ If you're a solo dev or small team using Claude Code (or Cursor, Codex, VS Code)
 
 <p align="center"><img src="brand/hero-org-in-folder.png" alt="rcode is an engineering org in a folder: agents, commands, workflows, and skills as plain markdown" width="760"></p>
 
-Three layers, specialised for software delivery:
+In plain words: **rcode is a folder of instructions your AI already knows how to read.** No new app to install, no server to run, no separate "agent brain" — just files. Your IDE (Claude Code, Cursor, whichever) is already an agent; rcode just hands it a really good playbook and a notebook that never forgets.
+
+```mermaid
+flowchart LR
+    A["You type a command<br/>/rcode-plan"] --> B["rcode's files answer:<br/>what to do, in what order"]
+    B --> C["Your IDE's own agent<br/>does the actual work"]
+    C --> D["Result gets saved to<br/>.rcode/memory/"]
+    D -.->|"next session starts here"| A
+```
+
+That loop — command in, memory out, memory feeds the next command — is the whole idea. Everything else in this repo is detail on top of that loop.
+
+Three layers make it up:
 
 | Layer | What lives here | Example |
 |-------|-----------------|---------|
@@ -63,15 +75,26 @@ Single agent navigates the structure. No LangChain, no AutoGen, no orchestrator
 
 ## Why I built it
 
-I've shipped products solo for years and watched the same failure repeat in every project:
-
-- **Session 1:** Productive — agent helps me design auth, picks Postgres, plans the schema.
-- **Session 5:** Agent has no idea I picked Postgres. Suggests Mongo. We argue. I copy-paste the decision back in.
-- **Session 20:** I'm pasting in 4K tokens of "here's what we decided" every session. The agent never learns. The project file structure isn't enough — decisions live in chat.
+I've shipped products solo for years and watched the same failure repeat in every project. In one sentence: **the AI forgets everything the moment the chat window closes, so I kept re-explaining the same decisions forever.**
+
+```mermaid
+flowchart LR
+    subgraph without["😩 Without rcode"]
+        direction TB
+        w1["Session 1 — pick Postgres"] --> w2["Session 5 — agent forgot,<br/>suggests Mongo, you argue"]
+        w2 --> w3["Session 20 — you're pasting<br/>4K tokens of 'here's what<br/>we decided' every time"]
+    end
+    subgraph with["✅ With rcode"]
+        direction TB
+        r1["Session 1 — pick Postgres"] --> r2["Decision saved once to<br/>.rcode/memory/decisions.md"]
+        r2 --> r3["Session 20 — agent reads it<br/>automatically, no re-explaining"]
+    end
+    without ~~~ with
+```
 
-rcode is the answer I built for myself. **The decision lives in `.rcode/memory/decisions.md`. The agent reads it. Done.**
+That's it. That's the whole pitch. **Write the decision down once, in a file. The agent reads the file. Done.**
 
-Same problem at team scale: onboarding takes 30 minutes of archaeology. Late requirements shift goalposts with no audit trail. MVPs work but can't be revamped because the original "why" is gone. rcode checks the context in, so the next person (or session) starts oriented.
+The same problem shows up at team scale, just wearing a different costume: onboarding a new hire takes 30 minutes of Slack archaeology, a late requirement quietly shifts the goalposts with no record of why, and six months later nobody remembers why the MVP was built the way it was. rcode's fix is the same either way — write the context down where the agent (and the next human) will actually see it.
 
 ---
 
@@ -81,6 +104,7 @@ What you'll feel in week one:
 
 - **No more re-explaining.** Decisions, blockers, conventions live in `.rcode/memory/` — agent reads them at session start automatically (~5K tokens, fully oriented).
 - **Phased delivery without ceremony.** `/rcode-new-project` produces a roadmap with phases → sprints → tasks. `/rcode-plan` produces SPRINT.md files. `/rcode-execute` runs them with atomic commits. No Jira required.
+- **No blank-page starts.** Already know you're building an API, a SaaS product, or a mobile app? `/rcode-from-template api-backend` seeds a real roadmap + requirements doc for that project type — edit it down instead of writing it up from nothing.
 - **Specialist review on tap.** Want a Karpathy-style review of your last commit? `/rcode-review --karpathy`. Want a council debate on a decision? `/rcode-council should I rewrite auth?` — 5 agents answer in parallel, round 2 they challenge each other.
 - **Intent guards.** Run the wrong command and get a one-line redirect, not a useless output.
 - **Health check.** `rcode-tools health` returns JSON — milestone health, state snapshot, project status. Wire it into your dashboard.
@@ -159,12 +183,21 @@ pnpm dlx @hanzlaa/rcode install
 
 ### The full loop
 
+Four commands cover most of a real week of work — decide, plan, build, check in:
+
+```mermaid
+flowchart LR
+    A["🗣️ /rcode-council<br/>should I rewrite auth?"] --> B["📋 /rcode-plan --research<br/>build a rental app"]
+    B --> C["⚙️ /rcode-execute<br/>PLAN.md"]
+    C --> D["📊 /rcode-status<br/>phases · decisions · blockers"]
 ```
-/rcode-council should I rewrite auth?        → 5 agents debate, 2 rounds
-/rcode-plan --research build a rental app    → researcher grounds, sprint-checker verifies
-/rcode-execute .planning/plans/01/PLAN.md    → atomic commits + post-gates
-/rcode-status                                → phases, decisions, blockers, sessions
-```
+
+| Command | What it does |
+|---|---|
+| `/rcode-council should I rewrite auth?` | 5 specialist agents debate it, 2 rounds — you get a decision, not a monologue |
+| `/rcode-plan --research build a rental app` | A researcher grounds the plan in your real codebase, a checker verifies it before you build anything |
+| `/rcode-execute .planning/plans/01/PLAN.md` | Runs the plan as atomic git commits, with pass/fail gates between steps |
+| `/rcode-status` | One glance at phases, decisions, and blockers — no digging through chat history |
 
 Full install flavors and IDE options: [`docs/install.md`](docs/install.md). Step-by-step first project: [`docs/getting-started.md`](docs/getting-started.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.6.0",
+  "version": "4.7.1",
   "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/bin/rcode-tools.cjs

@@ -4589,6 +4589,7 @@ This file is loaded by Claude Code, Codex, and compatible AI coding tools at the
 - No "while I'm here" improvements
 - No speculative abstractions
 - No new files unless necessary
+- **No freehand status/handoff docs** (\`HANDOFF.md\`, \`AGENT_X_DONE.md\`, anything at the project root summarizing "what I did"). That record is \`<N>-SUMMARY.md\` under \`.planning/phases/\` — even mid-task or in a parallel multi-agent run, write there, not a new root-level file.
 
 ---
 

package/rcode/references/agent-shared-rules.md

@@ -48,6 +48,12 @@
 
 ---
 
+## File placement discipline
+
+**Completion notes go in the sprint file, never a freehand root-level doc.** When work finishes, the record is `.planning/phases/{phase}/{sprint}-SUMMARY.md` (written by `/rcode-execute`) or a note in the existing `SPRINT.md`/`REVIEW.md` — never a new `SOMETHING_DONE.md`, `HANDOFF.md`, or `AGENT_X_DONE.md` at the project root or anywhere outside `.planning/`/`.rcode/`. If you're in a parallel multi-agent run and were asked for a "handoff doc," that handoff still belongs inside the sprint's own files — a sibling agent reads the next `SPRINT.md`/`CONTEXT.md`, not a scavenger hunt through the repo root for status files with inconsistent names.
+
+**Never invent a new top-level artifact type.** `PROJECT.md`, `ROADMAP.md`, `REQUIREMENTS.md`, `CONTEXT.md`, `RESEARCH.md`, `SPRINT.md`, `SUMMARY.md`, `REVIEW.md` — this is the closed set. If a task genuinely needs a new kind of record, that's a call for the user, not something to freehand mid-task.
+
 ## Framework discipline
 
 **Cite the heuristic by name.** When refusing or recommending, name the rule that drove the call. *"Per the Reversibility test, this is a one-way door — ADR required."* Traceable reasoning beats opinion.

package/rcode/references/executor-playbook.md

@@ -26,7 +26,7 @@ If you commit a file under `.planning/` and `git status` afterwards still shows
 2. **Load sprint** — Parse SPRINT.md frontmatter (phase, sprint, type, autonomous, wave, depends_on). Honor CONTEXT.md if referenced.
 3. **Determine pattern** — Pattern A (no checkpoints → execute all), B (has checkpoints → stop at first), C (continuation → resume).
 4. **Execute stories** — For each story: if `type="auto"`, execute and commit. If `type="checkpoint:*"`, STOP and return checkpoint. Update story status via `rcode-tools.cjs state story move --id NN.S.TT --status done`.
-5. **Create SUMMARY** — After all auto stories complete, write `.planning/phases/XX-name/{phase}-{sprint}-SUMMARY.md`.
+5. **Create SUMMARY** — After all auto stories complete, write `.planning/phases/XX-name/{phase}-{sprint}-SUMMARY.md`. This is the *only* completion artefact. Never write a parallel status/handoff doc (`AGENT_X_DONE.md`, `HANDOFF.md`, a root-level `*_DONE.md`) — if the run involves multiple parallel executors, each still records its own SUMMARY.md under its own sprint; there is no separate hand-off format.
 6. **Update state** — Run state tools to record metrics, mark stories complete, advance sprint.
 7. **Final commit** — Commit SUMMARY.md, STATE.md, ROADMAP.md with docs message.
 

package/rcode/references/planner-playbook.md

@@ -12,6 +12,7 @@ hierarchical ID format, and output routing.
 
 ### Context Fidelity
 - **Locked Decisions** (CONTEXT.md): MUST implement exactly. Reference decision ID (D-01, D-02) in task actions.
+- **Reference, don't restate.** A decision ID is a pointer, not a license to re-paste the rationale. `<action>` explains WHAT to do and cites the ID for WHY (`"per D-02's flattening rule"`) — it does not re-explain the decision's reasoning, alternatives, or findings inline. The full "why" already lives in CONTEXT.md/RESEARCH.md; the executor opens those if they need it. A task whose `<action>` reads like a design doc (multi-paragraph rationale, full alternatives-considered writeups) is a sign the planner copied instead of pointed — cut it down to the instruction + the ID.
 - **Deferred Ideas**: MUST NOT appear in plans.
 - **Agent's Discretion**: Use judgment, document choices.
 

package/rcode/workflows/init.md

@@ -285,6 +285,18 @@ After writing both files, refresh the memory bank fingerprint so staleness check
 node .rcode/bin/rcode-tools.cjs context refresh >/dev/null 2>&1 || true
 ```
 
+## Step 4c — Scaffold CLAUDE.md / AGENTS.md if missing
+
+`generate-claude-md` (the command routing rule + project rules block every agent needs at session start) previously only ran via the `/rcode-new-project` roadmap flow — a project set up with `/rcode-init` alone (the common "add rcode to an existing codebase" path) never got it, so agents had no ambient instruction to check `do.md` before acting ad-hoc. Close that gap here, unconditionally (not just on `fresh`):
+
+```bash
+if [ ! -f CLAUDE.md ]; then
+  node .rcode/bin/rcode-tools.cjs generate-claude-md
+fi
+```
+
+Never pass `--force` here — an existing `CLAUDE.md` is the user's own file (or was already generated by a prior init/new-project run) and must not be overwritten. Silent no-op when `CLAUDE.md` already exists.
+
 ## Step 5 — Suggest the next step
 
 Print a contextual recommendation, **one line of copy-paste per suggestion** (per `.rcode/references/command-redirect-format.md`):
@@ -339,6 +351,7 @@ Silent if state tools fail.
 - [ ] `.rcode/JOURNEY.md` written (unless `--skip-scan` or no code)
 - [ ] `.rcode/context/active.md` populated with project state (not the placeholder stub)
 - [ ] `.rcode/context/project-brief.md` populated with project overview (not the placeholder stub)
+- [ ] `CLAUDE.md` exists (generated if it didn't already)
 - [ ] State detected correctly (fresh / existing-new-rcode / returning)
 - [ ] Contextual next-step suggestion printed as single-line copy-paste
 

package/rcode/workflows/new-project-create-roadmap.md

@@ -161,42 +161,32 @@ Use AskUserQuestion:
 
 **Generate or refresh project instruction file before final commit:**
 
-The rcode-tools CLI does not expose a `generate-claude-md` subcommand. Instead, if `$INSTRUCTION_FILE` does not already exist, write a minimal instruction file pointing at the rcode workflow docs:
-
-```markdown
-# {INSTRUCTION_FILE} — project instructions
-
-This project uses rcode for planning and execution. See `.planning/PROJECT.md` for context and `.planning/ROADMAP.md` for phases.
-
-Common commands:
-- /rcode-progress — check status and next action
-- /rcode-discuss-phase N — gather context before planning phase N
-- /rcode-plan N — create a SPRINT.md for phase N
-- /rcode-execute N — execute a SPRINT.md
-- /rcode-verify-work — conversational UAT
-- /rcode-complete-milestone — archive milestone and reset
-
-Rules:
-- Never run `git push` without explicit user authorization.
-- No Claude/AI attribution in commits.
-- Prefer editing existing files over creating new ones.
+```bash
+node .rcode/bin/rcode-tools.cjs generate-claude-md
 ```
 
-If it already exists, leave it alone (respect user-customized content).
+Writes `CLAUDE.md` and `AGENTS.md` from rcode's own template (commit rules,
+push rules, phase workflow rules, scope discipline, and the command-routing
+rule pointing at `do.md`). Refuses to touch an existing `CLAUDE.md` — if it
+already exists, this is a silent no-op (respects user-customized content).
+`AGENTS.md` is written only when absent, so an install-appended `## rcode
+Agents (installed)` roster section is never clobbered.
 
 **Commit roadmap (guarded):**
 
 ```bash
-git add \
-  .planning/ROADMAP.md \
-  .planning/STATE.md \
-  .planning/REQUIREMENTS.md \
-  "$INSTRUCTION_FILE" 2>/dev/null \
+# git add fails its whole invocation on any missing pathspec, so only pass
+# paths that actually exist (CLAUDE.md/AGENTS.md are conditional — see above).
+ADD_PATHS=(.planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md)
+for f in CLAUDE.md AGENTS.md; do [ -f "$f" ] && ADD_PATHS+=("$f"); done
+
+git add "${ADD_PATHS[@]}" 2>/dev/null \
 && git commit -m "docs: create roadmap ([N] phases)" 2>/dev/null \
-|| echo "ℹ .planning/ gitignored — roadmap written, not committed (instruction file committed separately)"
+|| echo "ℹ .planning/ gitignored — roadmap written, not committed (instruction files committed separately)"
 
-# Fallback: also try committing just the instruction file if .planning was ignored
-git add "$INSTRUCTION_FILE" 2>/dev/null && git commit -m "docs: add project instruction file" 2>/dev/null || true
+# Fallback: also try committing just the instruction files if .planning was ignored
+IFILES=(); for f in CLAUDE.md AGENTS.md; do [ -f "$f" ] && IFILES+=("$f"); done
+[ ${#IFILES[@]} -gt 0 ] && git add "${IFILES[@]}" 2>/dev/null && git commit -m "docs: add project instruction files" 2>/dev/null || true
 
 # Sync all roadmapper-created phases into state.json.
 # rcode-roadmapper writes ROADMAP.md as text — it never calls `phase add` — so

package/server/lib/html/client/components/App.js

@@ -14,7 +14,9 @@
 
 import { html, useState, useEffect, useRef, useCallback } from '../preact.js';
 import { parseFilters } from '../filter-state.js';
-import { getState, setState, subscribe, registerRefresh } from '../store.js';
+import { getState, setState, subscribe, registerRefresh, closeFileViewer, closeDecisionViewer, closeBlockerViewer } from '../store.js';
+import { FileReader } from './FileReader.js';
+import { DecisionDrawer, BlockerDrawer } from './shared.js';
 import { startSessionsPoll, refreshOrchToken } from '../orchestrator.js';
 import { Sidebar } from './Sidebar.js';
 import { Topbar } from './Topbar.js';
@@ -32,6 +34,7 @@ import { PhasesView } from '../views/PhasesView.js';
 import { SprintsView } from '../views/SprintsView.js';
 import { TasksView } from '../views/TasksView.js';
 import { KanbanView } from '../views/KanbanView.js';
+import { BacklogView } from '../views/BacklogView.js';
 import { FilesView } from '../views/FilesView.js';
 import { AgentsView } from '../views/AgentsView.js';
 import { MemoryView } from '../views/MemoryView.js';
@@ -48,6 +51,7 @@ const PREACT_VIEWS = {
   sprints:       SprintsView,
   tasks:         TasksView,
   kanban:        KanbanView,
+  backlog:       BacklogView,
   files:         FilesView,
   agents:        AgentsView,
   memory:        MemoryView,
@@ -213,6 +217,7 @@ export function App() {
         timeline:  d.timeline  || null,
         tasks:     d.tasks     || null,
         health:    d.health    || null,
+        backlog:   d.backlog   || [],
       });
       if (newState.raw) {
         Object.assign(patch, {
@@ -310,6 +315,15 @@ export function App() {
       <${RunnerPicker} />
       <${RunConfirmDialog} pending=${storeState.runConfirm} />
       <${CommandPalette} open=${paletteOpen} onClose=${() => setPaletteOpen(false)} />
+      ${storeState.fileViewer && html`
+        <${FileReader}
+          path=${storeState.fileViewer.path}
+          title=${storeState.fileViewer.title}
+          onClose=${closeFileViewer}
+        />
+      `}
+      <${DecisionDrawer} decision=${storeState.decisionViewer} onClose=${closeDecisionViewer} />
+      <${BlockerDrawer} blocker=${storeState.blockerViewer} onClose=${closeBlockerViewer} />
     </div>
   `;
 }

package/server/lib/html/client/components/PhaseGraph.js

@@ -171,25 +171,33 @@ function Tooltip({ phase, nodePos, canvasW, canvasH }) {
   `;
 }
 
-/** Wrapped flow row of chips — the honest no-dependencies presentation. */
+/**
+ * Sequence row — the honest no-dependencies presentation. There is nothing
+ * to lay out as a DAG (no edges), so this doesn't pretend to be a graph: a
+ * connected left-to-right chain of small status pills in roadmap order,
+ * joined by arrows. Reads as "the order things ship in", not "broken nodes".
+ */
 function FlowRow({ phases }) {
   return html`
-    <div class="pg-flow">
-      ${phases.map(p => {
+    <div class="pg-hint pg-hint-top">No cross-phase dependencies declared — phases shown in roadmap order.</div>
+    <div class="pg-seq">
+      ${phases.map((p, i) => {
         const kind = statusKind(p.status);
         const sprints = (p.sprints || []).length;
         return html`
-          <button key=${p.id} type="button"
-            class=${'pg-chip pg-' + kind}
-            title=${(p.name || '') + ' — ' + sprints + (sprints === 1 ? ' sprint' : ' sprints')}
-            onClick=${() => goToPhase(p.id)}>
-            <span class="pg-chip-id">P${p.id}</span>
-            <span class="pg-chip-name">${truncate(p.name, 24)}</span>
-          </button>
+          <span key=${p.id} class="pg-seq-item">
+            <button type="button"
+              class=${'pg-seq-chip pg-' + kind}
+              title=${(p.name || '') + ' — ' + sprints + (sprints === 1 ? ' sprint' : ' sprints')}
+              onClick=${() => goToPhase(p.id)}>
+              <span class="pg-seq-id">P${p.id}</span>
+              <span class="pg-seq-name">${truncate(p.name, 22)}</span>
+            </button>
+            ${i < phases.length - 1 ? html`<span class="pg-seq-arrow" aria-hidden="true">›</span>` : null}
+          </span>
         `;
       })}
     </div>
-    <div class="pg-hint">No cross-phase dependencies declared — phases shown in roadmap order.</div>
   `;
 }
 
@@ -280,7 +288,7 @@ export function PhaseGraph({ phases }) {
   return html`
     <details class="pg-panel" open>
       <summary>
-        <${Icon} name="layers" size=${14}/> Dependency Graph
+        <${Icon} name="layers" size=${14}/> ${hasDeps ? 'Dependency Graph' : 'Phases'}
         <span class="pg-count">${list.length} ${list.length === 1 ? 'phase' : 'phases'}</span>
       </summary>
       <div class="pg-legend">

package/server/lib/html/client/components/Sidebar.js

@@ -33,6 +33,7 @@ const NAV_LINKS = [
   { view: 'sprints',       icon: 'zap',         label: 'Sprints'       },
   { view: 'tasks',         icon: 'checkSquare', label: 'Tasks'         },
   { view: 'kanban',        icon: 'kanban',      label: 'Kanban'        },
+  { view: 'backlog',       icon: 'hourglass',   label: 'Backlog'       },
   { view: 'decisions',     icon: 'scale',       label: 'Decisions'     },
   { view: 'files',         icon: 'file-text',   label: 'Files'         },
   { view: 'agents',        icon: 'users',       label: 'Agents'        },

package/server/lib/html/client/components/Topbar.js

@@ -92,10 +92,10 @@ export function Topbar({ projectName, updatedAgo, refreshing, onRefresh, onToggl
           class="tb-btn tb-btn--icon"
           type="button"
           onClick=${onToggleTheme}
-          title=${'More — switch to ' + (themeLabel === 'light' ? 'dark' : 'light') + ' theme'}
-          aria-label="More options"
+          title=${'Switch to ' + (themeLabel === 'light' ? 'dark' : 'light') + ' theme'}
+          aria-label="Toggle theme"
         >
-          <span class="tb-kebab">⋯</span>
+          <${Icon} name=${themeLabel === 'light' ? 'moon' : 'sun'} size=${15} />
         </button>
       </div>
     </header>

package/server/lib/html/client/components/dashboard/Blockers.js

@@ -11,8 +11,8 @@
  */
 
 import { html } from '../../preact.js';
-import { useStore } from '../../store.js';
-import { rowLink } from '../../util.js';
+import { useStore, openBlockerViewer } from '../../store.js';
+import { pressable } from '../shared.js';
 
 // Severity → pill label (lowercase enum to human-facing label).
 const SEV_LABEL = { high: 'High', medium: 'Medium', low: 'Low' };
@@ -40,7 +40,7 @@ export function Blockers() {
             ${blockers.map((b) => {
               const sev = SEV_LABEL[b.severity] ? b.severity : 'low';
               return html`
-                <li class="bk-row ovr-link" key=${b.title} ...${rowLink('tasks')}>
+                <li class="bk-row ovr-link" key=${b.title} ...${pressable(() => openBlockerViewer(b))}>
                   <span class=${'bk-icon bk-sev-' + sev} aria-hidden="true">⚠</span>
                   <div class="bk-body">
                     <p class="bk-title">${b.title}</p>

package/server/lib/html/client/components/dashboard/CompletedTasks.js

@@ -10,8 +10,9 @@
  */
 
 import { html } from '../../preact.js';
-import { useStore } from '../../store.js';
+import { useStore, openFileViewer } from '../../store.js';
 import { humanDate } from '../../util.js';
+import { pressable } from '../shared.js';
 
 export function CompletedTasks() {
   const S = useStore();
@@ -30,7 +31,8 @@ export function CompletedTasks() {
         : html`
           <ul class="ct-list">
             ${items.map((t, i) => html`
-              <li class="ct-row" key=${t.title + i}>
+              <li class=${'ct-row' + (t.file ? ' ovr-link' : '')} key=${t.title + i}
+                ...${t.file ? pressable(() => openFileViewer(t.file, t.title)) : {}}>
                 <svg class="ct-check" width="16" height="16" viewBox="0 0 24 24"
                   fill="none" stroke="currentColor" stroke-width="2.5"
                   stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">

package/server/lib/html/client/components/dashboard/InProgress.js

@@ -18,8 +18,8 @@
  */
 
 import { html } from '../../preact.js';
-import { useStore } from '../../store.js';
-import { orchElapsed, rowLink } from '../../util.js';
+import { useStore, openFileViewer } from '../../store.js';
+import { orchElapsed } from '../../util.js';
 import { openTermPanel } from '../../orchestrator.js';
 import { pressable } from '../shared.js';
 import { TaskPipeline } from '../TaskPipeline.js';
@@ -60,7 +60,8 @@ export function InProgress() {
           <ul class="ip-list">
             ${live.map(s => html`<${LiveRow} key=${'live-' + s.storyId} session=${s}/>`)}
             ${items.map((t, i) => html`
-              <li class="ip-row ovr-link" key=${t.title + i} ...${rowLink('tasks')}>
+              <li class=${'ip-row' + (t.file ? ' ovr-link' : '')} key=${t.title + i}
+                ...${t.file ? pressable(() => openFileViewer(t.file, t.title)) : {}}>
                 <span class="ip-title">${t.title}</span>
                 <${TaskPipeline} task=${t} mini=${true}/>
                 ${Number.isFinite(t.pct) ? html`<span class="ip-badge">${t.pct}%</span>` : null}

package/server/lib/html/client/components/dashboard/ProgressTimeline.js

@@ -12,8 +12,8 @@
  */
 
 import { html } from '../../preact.js';
-import { useStore } from '../../store.js';
-import { rowLink } from '../../util.js';
+import { useStore, openFileViewer } from '../../store.js';
+import { pressable } from '../shared.js';
 
 // Map phase state → label + badge/segment modifier.
 function stateMeta(state) {
@@ -84,11 +84,16 @@ export function ProgressTimeline() {
       <div class="pt-track">
         ${phases.map((p, i) => {
           const m = stateMeta(p.state);
-          // Segment deep-links to its phase detail; fall back to the list
-          // when the phase has no id.
-          const target = p.id != null ? 'phases/' + p.id : 'phases';
+          // Same "first sprint with a resolved file" lookup PhasesView uses
+          // for its "View plan file" button. Falls back to the phase detail
+          // page when nothing resolved (e.g. phase has no SPRINT.md yet).
+          const sps = Array.isArray(p.sprints) ? p.sprints : [];
+          const planFile = (sps.find(s => s.file) || {}).file || null;
+          const onActivate = planFile
+            ? () => openFileViewer(planFile, 'Phase ' + (p.id != null ? p.id : '') + ' plan')
+            : () => { location.hash = p.id != null ? 'phases/' + p.id : 'phases'; };
           return html`
-            <div class=${'pt-seg ovr-link ' + m.mod} key=${p.name + i} ...${rowLink(target)}>
+            <div class=${'pt-seg ovr-link ' + m.mod} key=${p.name + i} ...${pressable(onActivate)}>
               <span class="pt-seg-name">${p.name}</span>
               <span class="pt-seg-range">${p.range || ''}</span>
               <span class="pt-seg-badge">${m.label}</span>

package/server/lib/html/client/components/dashboard/RecentDecisions.js

@@ -9,8 +9,9 @@
  */
 
 import { html } from '../../preact.js';
-import { useStore } from '../../store.js';
-import { humanDate, rowLink } from '../../util.js';
+import { useStore, openDecisionViewer } from '../../store.js';
+import { humanDate } from '../../util.js';
+import { pressable } from '../shared.js';
 
 // Map a free-form status string to a badge modifier class.
 function statusClass(status) {
@@ -42,7 +43,7 @@ export function RecentDecisions() {
         : html`
           <ul class="rd-list">
             ${decisions.map((d, i) => html`
-              <li class="rd-row ovr-link" key=${d.title + i} ...${rowLink('decisions')}>
+              <li class="rd-row ovr-link" key=${d.title + i} ...${pressable(() => openDecisionViewer(d))}>
                 <span class="rd-title">${d.title}</span>
                 ${d.status
                   ? html`<span class=${'rd-badge ' + statusClass(d.status)}>${d.status}</span>`