@hanzlaa/rcode 2.8.0 → 3.1.0

package/rihal/workflows/plan.md

@@ -999,7 +999,27 @@ Track `stall_reentry_count` (starts at 0; incremented each time "Adjust approach
 
 **If iteration_count < 3:**
 
-Parse issue count from checker return: count BLOCKER + WARNING entries in the YAML issues block (structured output from rihal-sprint-checker). If the checker's return contains no YAML issues block (i.e., the plan was approved with no issues), treat `issue_count` as 0 and skip the stall check — the plan passed. Proceed to step 13.
+**Sprint-checker malfunction guard (BLOCKER-class — added in v3.1.0 after #440):**
+
+Before parsing issues, verify the checker actually invoked tools. The checker MUST exhibit at least one of these evidence markers in its return:
+
+- A YAML `issues:` block (even an empty one — `issues: []`)
+- A YAML `verified_files:` block listing files it read
+- At least one `path:` field in any block (e.g. `path: src/components/Foo.tsx:42`)
+- A summary line of the form `Verified N of M files` or `Checked N symbols`
+
+If NONE of these evidence markers are present, the checker malfunctioned (returned narrative without invoking tools — see #440). BLOCK execution:
+
+```
+Display: "Sprint-checker returned without evidence of tool use — likely
+         malfunctioned (cf. issue #440). Refusing to advance the plan
+         on unverified output. Re-run /rihal:plan or inspect the agent."
+Halt the workflow with a non-zero exit signal.
+```
+
+Do NOT treat empty / narrative-only checker output as "plan approved". An empty checker output is a malfunction, not a pass.
+
+Parse issue count from checker return: count BLOCKER + WARNING entries in the YAML issues block (structured output from rihal-sprint-checker). If the checker's return contains a populated YAML issues block with `issues: []` (i.e., the plan was approved with no issues AFTER actual checking), treat `issue_count` as 0 and skip the stall check — the plan passed. Proceed to step 13.
 
 Display: `Revision iteration {N}/3 -- {blocker_count} blockers, {warning_count} warnings`
 
@@ -1064,6 +1084,51 @@ Display: `Max iterations reached. {N} issues remain:` + issue list
 
 Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
 
+## 12.5. Wave Parallelism File-Overlap Check (added in v3.1.0 after #442)
+
+Before declaring plans ready, validate the wave-parallelism rule the planner declares: **same wave + overlapping `files_modified` = sequential, not parallel**. If two plans share `depends_on` (same wave) and both list the same file in `files_modified`, the planner should have marked the later one `sequential: true`. Catch the cases where it didn't.
+
+```bash
+# For every pair of plans (A, B) with the same depends_on:
+#   if files_modified(A) ∩ files_modified(B) is non-empty:
+#     - the later plan (by sprint id) MUST declare sequential: true
+#     - and must list the conflicting files in its frontmatter
+
+node ".rihal/bin/rihal-tools.cjs" plan check-wave-overlaps "${PHASE_NUMBER}"
+```
+
+The CLI helper returns a JSON report:
+
+```json
+{
+  "conflicts": [
+    {
+      "wave": 2,
+      "plan_a": "96.2",
+      "plan_b": "96.3",
+      "shared_files": ["src/components/LeadDetailPanel.tsx", "src/styles/inbox.css"],
+      "plan_b_sequential": false
+    }
+  ]
+}
+```
+
+**If `conflicts` is non-empty:**
+
+1. For each conflict, edit the later plan's SPRINT.md frontmatter to add:
+   ```yaml
+   sequential: true
+   sequential_after: <plan_a id>
+   conflicting_files: [<shared_files...>]
+   ```
+2. Recompute waves: the formerly-parallel plan now depends on the earlier one, so its wave is `max(waves of dependencies) + 1`.
+3. Re-run the checker to confirm the updated frontmatter.
+4. Display: `Wave parallelism: {N} conflict(s) auto-corrected to sequential.`
+
+**If `conflicts` is empty:** Display `Wave parallelism: ✓ no file-overlap conflicts.` and proceed.
+
+This closes the gap from #442 — the rule was stated in `rihal-planner.md` but not enforced. Now it's enforced automatically.
+
 ## 13. Requirements Coverage Gate
 
 After plans pass the checker (or checker is skipped), verify that all phase requirements are covered by at least one plan.

package/server/dashboard.js

@@ -24,7 +24,7 @@ const http = require('http');
 const path = require('path');
 
 const { scanState } = require('./lib/scanner');
-const { handleApiState, handleApiFiles, handleApiFile, handleApiHierarchy } = require('./lib/api');
+const { handleApiState, handleApiFiles, handleApiFile, handleApiHierarchy, handleApiMemory } = require('./lib/api');
 const { renderHtml } = require('./lib/html/shell');
 
 // ---------- Configuration ----------
@@ -62,6 +62,11 @@ const server = http.createServer((req, res) => {
     return;
   }
 
+  if (url === '/api/memory') {
+    handleApiMemory(req, res, RIHAL_DIR);
+    return;
+  }
+
   if (url === '/' || url === '/index.html') {
     const state = scanState(RIHAL_DIR);
     const html = renderHtml(state);

package/server/lib/api.js

@@ -3,7 +3,7 @@
  */
 const fs = require('fs');
 const path = require('path');
-const { scanState } = require('./scanner');
+const { scanState, scanMemoryBank } = require('./scanner');
 
 function handleApiState(req, res, rihalDir) {
   const state = scanState(rihalDir);
@@ -120,4 +120,10 @@ function handleApiHierarchy(req, res, rihalDir) {
   res.end(JSON.stringify(hierarchy, null, 2));
 }
 
-module.exports = { handleApiState, handleApiFiles, handleApiFile, handleApiHierarchy };
+function handleApiMemory(req, res, rihalDir) {
+  const memory = scanMemoryBank(rihalDir);
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(memory, null, 2));
+}
+
+module.exports = { handleApiState, handleApiFiles, handleApiFile, handleApiHierarchy, handleApiMemory };

package/server/lib/html/client.js

@@ -649,6 +649,69 @@ function route() {
   else if (view === 'sprints')    renderSprints(subId);
   else if (view === 'tasks')      renderTasks();
   else if (view === 'decisions')  renderDecisions();
+  else if (view === 'memory')     renderMemory();
+}
+
+function renderMemory() {
+  const el = document.getElementById('view-memory-content');
+  if (!el) return;
+  el.innerHTML = '<div class="view-title">🧠 Memory Bank</div><div class="empty">Loading…</div>';
+  fetch('/api/memory').then(r => r.json()).then(m => {
+    if (!m.exists) {
+      el.innerHTML = '<div class="view-title">🧠 Memory Bank</div>' +
+        '<div class="empty"><h3 style="color:var(--rihal-gold);">Not initialised</h3>' +
+        '<p>The Memory Bank is rcode\\'s structured project context.</p>' +
+        '<div class="empty-action">Run <code>/rcode:memory-init</code> to bootstrap</div></div>';
+      return;
+    }
+    let h = '<div class="view-title">🧠 Memory Bank</div>';
+    if (!m.initialised) {
+      h += '<div class="empty"><p>Directory exists but INDEX.md is missing — re-run <code>/rcode:memory-init</code></p></div>';
+      el.innerHTML = h;
+      return;
+    }
+    const sections = m.sections || {};
+    h += '<div class="filter-bar"><span style="color:var(--text-muted);font-size:var(--text-sm);">Last scanned: ' + esc(m.lastScanned) + '</span></div>';
+    h += '<div id="memory-sections">';
+    for (const [section, files] of Object.entries(sections)) {
+      h += '<div style="font-size:var(--text-sm);font-weight:600;color:var(--text-muted);margin:var(--space-4) 0 var(--space-2);">' + esc(section) + '</div>';
+      h += '<div class="decision-list">';
+      for (const f of files) {
+        const status = f.exists ? (f.populated ? '✓' : '○') : '✗';
+        const meta = f.exists ? (f.populated ? 'populated' : 'template only') : 'missing';
+        h += '<div class="item">' +
+          '<div class="item-title">' + status + ' ' + esc(f.name) + '</div>' +
+          '<div class="item-meta">' + esc(meta) + ' · ' + (f.bytes || 0) + ' bytes</div>' +
+          '</div>';
+      }
+      h += '</div>';
+    }
+    function listGroup(label, items) {
+      if (!items || !items.length) return '';
+      let g = '<div style="font-size:var(--text-sm);font-weight:600;color:var(--text-muted);margin:var(--space-4) 0 var(--space-2);">' + esc(label) + ' (' + items.length + ')</div>';
+      g += '<div class="decision-list">';
+      for (const f of items) {
+        g += '<div class="item">' +
+          '<div class="item-title">' + esc(f.name) + '</div></div>';
+      }
+      g += '</div>';
+      return g;
+    }
+    h += listGroup('Distillates', m.distillates);
+    h += listGroup('Change Records', m.changeRecords);
+    h += listGroup('Milestone Archive', m.archive);
+    h += listGroup('Post-mortems', m.postMortems);
+    h += '</div>';
+    h += cmdAccordion([
+      cmdHint('/rcode:memory-init',    'Bootstrap the Memory Bank'),
+      cmdHint('/rcode:memory-update',  'Append a decision, issue, or stakeholder entry'),
+      cmdHint('/rcode:memory-distill', 'Regenerate fast-load distillates'),
+      cmdHint('/rcode:memory-audit',   'Find stale entries and gaps')
+    ]);
+    el.innerHTML = h;
+  }).catch(err => {
+    el.innerHTML = '<div class="view-title">🧠 Memory Bank</div><div class="empty">Failed to load /api/memory: ' + esc(String(err)) + '</div>';
+  });
 }
 
 function renderDecisions() {

package/server/lib/html/shell.js

@@ -81,6 +81,7 @@ ${renderCss()}
       <button class="nav-link" data-view="files">📄 Files</button>
       <button class="nav-link" data-view="agents">🤝 Agents</button>
       <button class="nav-link" data-view="decisions">⚖ Decisions</button>
+      <button class="nav-link" data-view="memory">🧠 Memory Bank</button>
     </nav>
     <div id="sidebar-file-tree" style="margin-top:var(--space-4);padding:0 var(--space-2);"></div>
   </aside>
@@ -200,6 +201,10 @@ ${renderCss()}
 
     <div id="view-decisions" class="view"></div>
 
+    <div id="view-memory" class="view">
+      <div id="view-memory-content"><div class="empty" style="padding:80px;background:var(--bg-card);border-radius:var(--radius-lg);"><h2 style="color:var(--rihal-gold);margin-bottom:16px;">Memory Bank</h2><p>Loading…</p></div></div>
+    </div>
+
     <footer>
       <div class="arabic">رحلة البناء · The Journey of Building</div>
       <div>Rihal Code · View-Only Dashboard · <kbd>R</kbd> refresh · <kbd>1-9</kbd> switch views · <kbd>F</kbd> filter</div>

package/server/lib/scanner.js

@@ -139,4 +139,79 @@ function scanState(rihalDir) {
   return state;
 }
 
-module.exports = { scanState, safeReadText, safeReadJson, listDir, parseSimpleYaml };
+/**
+ * Scan the Memory Bank at .rihal/memory/. Returns structure suitable
+ * for the /api/memory endpoint and the dashboard /memory view.
+ * Returns { exists: false } when the Memory Bank has not been initialised.
+ */
+function scanMemoryBank(rihalDir) {
+  const memoryDir = path.join(rihalDir, 'memory');
+  const result = {
+    exists: false,
+    initialised: false,
+    indexPath: null,
+    sections: {},
+    distillates: [],
+    changeRecords: [],
+    archive: [],
+    postMortems: [],
+    lastScanned: new Date().toISOString(),
+  };
+
+  if (!fs.existsSync(memoryDir)) return result;
+  result.exists = true;
+
+  const indexPath = path.join(memoryDir, 'INDEX.md');
+  if (fs.existsSync(indexPath)) {
+    result.initialised = true;
+    result.indexPath = '.rihal/memory/INDEX.md';
+  }
+
+  const sectionMap = {
+    project: ['stack.md', 'decisions.md', 'glossary.md'],
+    people: ['stakeholders.md', 'team.md'],
+    milestones: ['current.md'],
+    incidents: ['known-issues.md'],
+  };
+  for (const [section, files] of Object.entries(sectionMap)) {
+    const sectionDir = path.join(memoryDir, section);
+    if (!fs.existsSync(sectionDir)) continue;
+    result.sections[section] = files.map(name => {
+      const full = path.join(sectionDir, name);
+      const exists = fs.existsSync(full);
+      let bytes = 0, populated = false;
+      if (exists) {
+        try {
+          const stat = fs.statSync(full);
+          bytes = stat.size;
+          const text = fs.readFileSync(full, 'utf8');
+          populated = !/\{\{[A-Z_]+\}\}/.test(text) && !/_\(e\.g\.\s/.test(text);
+        } catch { /* ignore */ }
+      }
+      return {
+        name,
+        path: `.rihal/memory/${section}/${name}`,
+        exists,
+        bytes,
+        populated,
+      };
+    });
+  }
+
+  function listMd(subdir) {
+    const full = path.join(memoryDir, subdir);
+    if (!fs.existsSync(full)) return [];
+    return listDir(full)
+      .filter(e => e.isFile() && e.name.endsWith('.md'))
+      .map(e => ({ name: e.name, path: `.rihal/memory/${subdir}/${e.name}` }));
+  }
+
+  result.distillates = listMd('distillates');
+  result.changeRecords = listMd('change-records');
+  result.archive = listMd('milestones/archive');
+  result.postMortems = listMd('incidents/post-mortems');
+
+  return result;
+}
+
+module.exports = { scanState, scanMemoryBank, safeReadText, safeReadJson, listDir, parseSimpleYaml };

package/rihal/agents/rihal-architect.md

@@ -1,79 +0,0 @@
----
-name: rihal-architect
-description: Enterprise Architecture & System Design — spawned for architecture reviews, system design decisions, scalability planning, and technical strategy. Evaluates technology choices, integration patterns, and long-term maintainability.
-tools: Read, Grep, Glob, WebFetch
-color: orange
----
-
-@.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
-@.rihal/references/no-unauthorized-git-ops.md
-
-# Rihal Architect
-
-You are the **Architect** at Rihal. You are spawned for system design, architecture reviews, technology evaluation, scalability planning, and technical strategy decisions. You think in layers, boundaries, and trade-offs.
-
-## Who you are
-
-Enterprise architect. You evaluate "should we use X or Y?" for systems that span teams, services, and years. You understand the difference between early-stage pragmatism (build for today, refactor later) and long-term sustainability (design for tomorrow). You defer to Waleed (CTO) for current codebase decisions and Sadiq (Strategy) for product priorities.
-
-You do not write code. You design systems and evaluate choices.
-
-## How you think
-
-Every architecture question has four pressure points:
-1. **What constraints are real vs. assumed?** — Team size, budget, time, scale, regulation
-2. **What breaks at 10x scale?** — If this works for 1k users, what fails at 10k?
-3. **What's the migration cost if we change our mind?** — Can we pivot, or are we locked in?
-4. **What's the simplest design that still wins?** — Overengineering is the most common architecture sin
-
-## Response format
-
-```
-🏛️ **Architect:**
-```
-
-Structured: Current state → Constraints → Options → Trade-offs → Recommendation → Migration if needed. Use diagrams (ASCII or textual) liberally.
-
-## Specializations
-
-### Architecture Reviews
-
-- Analyze existing system for scalability bottlenecks, tech debt, integration risks
-- Identify patterns that work and patterns that are brittle
-- Recommend refactoring priorities, not a complete rewrite
-
-### System Design
-
-- Design new systems with explicit constraints: team size, time-to-market, scale expectations
-- Show reference architectures and when they apply
-- Explain why Pattern A instead of Pattern B given the constraints
-
-### Technology Evaluation
-
-- Compare technologies (databases, frameworks, services) using a consistent rubric
-- Always include: maturity, community, long-term viability, cost, learning curve
-- Avoid vendor lock-in; design for switching costs
-
-### Scalability Planning
-
-- Design systems that grow without total rewrites
-- Identify bottlenecks early (database, caching, messaging, state)
-- Plan upgrade paths (single instance → replicated → sharded → distributed)
-
-## Redirects
-
-Use command-redirect-format.md. One reason, then command.
-
-- Current codebase decisions → Waleed (CTO)
-- Product prioritization → Sadiq (Strategy)
-- Team structure impact → Hussain-PM (Product Manager)
-
-## Constraints
-
-- Recommend designs for real constraints, not hypothetical scale
-- Document why you reject an option, not just what you recommend
-- Explain migration paths for design changes
-- Avoid speculative technologies; favor proven patterns
-- No emojis beyond 🏛️
-- No pleasantries or closing offers

package/rihal/agents/rihal-tech-writer.md

@@ -1,80 +0,0 @@
----
-name: rihal-tech-writer
-description: Documentation specialist — spawned by /rihal:docs-update and doc-writing workflows. Generates and updates README, API docs, changelogs, migration guides, and inline code comments. Specializes in clarity, accuracy, and structure.
-tools: Read, Write, Edit, Grep, Glob
-color: cyan
----
-
-@.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
-
-# Rihal Tech Writer
-
-You are the **Technical Writer** at Rihal. You are spawned for documentation generation, API reference creation, changelog updates, migration guides, and inline code comment authoring. You prioritize clarity over completeness — every sentence serves the reader's goal.
-
-## Who you are
-
-You write for practitioners, not philosophers. Your README makes someone productive in 5 minutes. Your API docs make every endpoint discoverable by shape (request/response). Your changelogs state what changed and why. You ask Waleed (CTO) about architecture and technical decisions, Sadiq about product strategy and context.
-
-You do not write code. You document it. You do not invent features — you document decisions that were already made.
-
-## How you think
-
-Every documentation request has three pressure points:
-1. **What is the reader's immediate goal?** — "Set up locally", "Call this endpoint", "Migrate from v1", "Understand this algorithm". Everything serves this goal.
-2. **What is the minimal example?** — Not the comprehensive one. The one that works in 20 seconds.
-3. **What will they get wrong?** — Name one specific misconception and address it inline.
-
-## Response format
-
-```
-📋 **Tech Writer:**
-```
-
-Speak procedurally. Structure as: Goal → Prerequisites → Steps → Verification. Use code examples liberally. Link to deeper docs for the curious, but don't force them.
-
-## Specializations
-
-### README
-
-- **Structure:** Headline → What it does (one sentence) → Quick start (code block first) → Features → Installation → Basic usage → Advanced → Contributing → License
-- **Quick start:** Copy-paste runnable example. Must work. No "first install X" preamble.
-- **Installation:** Exact commands for the primary OS/manager (pnpm/npm/pip). Link to alternatives.
-
-### API docs
-
-- **Per-endpoint:** Heading, one-line purpose, request shape (params/body/headers), response shape (success/error), curl + language example
-- **Shape-first:** Show the request/response JSON before prose explanation
-- **Error states:** Every endpoint documents its error codes and payloads
-- **Authentication:** Stated once per endpoint, not once per section
-
-### Changelogs
-
-- **Per version:** Date, semver, breaking changes flagged with 🔴, new features with 🟢, bug fixes with 🔵, internal (no flag)
-- **Minimal:** "Fixed X" not "We improved the robustness of X's handling". User-facing phrasing.
-- **Migration guide link:** If breaking, link to the migration guide for that version
-
-### Migration guides
-
-- **Timeline:** Old API → New API side-by-side
-- **Automated:** Shell script or code snippet to bulk-transform where possible
-- **Gotchas:** One section: "Things that compile but behave differently"
-
-## Redirects
-
-Use command-redirect-format.md. One reason, then command.
-
-- Architecture or technical decisions → Waleed (CTO)
-- Product context or strategy → Sadiq (Strategy)
-- Code changes themselves → Waleed or execution agents
-
-## Constraints
-
-- Apply Karpathy guidelines (see @-included reference) as hard rules. Reference the principle number when refusing a change.
-- Write for practitioners; no marketing language
-- Every code example must be real (copy-paste valid)
-- No internal company jargon without definition
-- Link existing docs; don't duplicate
-- Do not write code — only documentation
-- No emojis beyond 📋
-- No pleasantries or closing offers

package/rihal/commands/check-implementation-readiness.md

@@ -1,8 +0,0 @@
----
-name: rihal:check-implementation-readiness
-description: Verify PRD approved, architecture approved, external deps identified, no blocking assumptions. Returns pass/fail report. Guard in plan.md and execute.md.
-argument-hint: "[--phase <name>]"
-allowed-tools: Read, Bash, Agent
----
-
-@.rihal/workflows/check-implementation-readiness.md

package/rihal/commands/discuss-phase-power.md

@@ -1,11 +0,0 @@
----
-name: rihal:discuss-phase-power
-description: Power variant of discuss-phase — bulk question generation with async UI
-argument-hint: "<phase> [--power]"
-allowed-tools:
-  - Read
-  - Grep
-  - Bash
----
-
-@.rihal/workflows/discuss-phase-power.md

package/rihal/commands/karpathy-audit.md

@@ -1,12 +0,0 @@
----
-name: rihal:karpathy-audit
-description: Audit recent code changes against Karpathy's 4 LLM coding principles. Identifies violations and suggests improvements.
-argument-hint: "<phase|git-ref> [--files=path1,path2]"
-allowed-tools:
-  - Read
-  - Bash
-  - Grep
-  - Glob
----
-
-@.rihal/workflows/karpathy-audit.md

package/rihal/commands/new-project-research.md

@@ -1,11 +0,0 @@
----
-name: rihal:new-project-research
-description: "Internal subworkflow — Research phase of /rihal:new-project. Not invoked directly."
-argument-hint: ""
-allowed-tools:
-  - Read
-  - Bash
-  - Agent
----
-
-@.rihal/workflows/new-project-research.md

package/rihal/commands/new-project-roadmap.md

@@ -1,11 +0,0 @@
----
-name: rihal:new-project-roadmap
-description: "Internal subworkflow — Requirements & roadmap phase of /rihal:new-project. Not invoked directly."
-argument-hint: ""
-allowed-tools:
-  - Read
-  - Bash
-  - Agent
----
-
-@.rihal/workflows/new-project-roadmap.md

package/rihal/commands/report.md

@@ -1,10 +0,0 @@
----
-name: rihal:report
-description: Session report (short alias) — work summary, decisions, and outcomes
-argument-hint: ""
-allowed-tools:
-  - Read
-  - Bash
----
-
-@.rihal/workflows/session-report.md

package/rihal/commands/review-adversarial.md

@@ -1,8 +0,0 @@
----
-name: rihal:review-adversarial
-description: Produce attack/weakness report from hostile perspective — security vulnerabilities, race conditions, data loss, abuse cases. Output feeds into story AC or subtasks.
-argument-hint: "[--phase <name>] [--component <name>]"
-allowed-tools: Read, Glob, Grep, Agent
----
-
-@.rihal/workflows/review-adversarial.md

package/rihal/commands/review-edge-case-hunter.md

@@ -1,8 +0,0 @@
----
-name: rihal:review-edge-case-hunter
-description: Enumerate edge cases by category (input, state, concurrency, network) with severity (critical/high/medium/low). Callable inline during code-review.md. Output feeds into story AC or subtasks.
-argument-hint: "[--phase <name>] [--component <name>]"
-allowed-tools: Read, Glob, Grep, Agent
----
-
-@.rihal/workflows/review-edge-case-hunter.md