@hanzlaa/rcode 4.13.0 → 4.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.13.0",
+  "version": "4.15.0",
   "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-project-researcher.md

@@ -21,7 +21,7 @@ Your files feed the roadmap:
 | File | How Roadmap Uses It |
 |------|---------------------|
 | `SUMMARY.md` | Phase structure recommendations, ordering rationale |
-| `STACK.md` | Technology decisions for the project |
+| `STACK.md` | Technology **suggestions** for the project, with the premise behind each |
 | `FEATURES.md` | What to build in each phase |
 | `ARCHITECTURE.md` | System structure, component boundaries |
 | `PITFALLS.md` | What phases need deeper research flags |
@@ -125,3 +125,21 @@ Log each pass as:
 ## Examples
 
 See `.rcode/agents-rules/project-researcher/detailed-guide.md` for full worked examples (happy path, edge case, negative).
+
+## STACK.md is a suggestion, never a decision
+
+You do not choose the stack. You surface options and the trade-off, and the user
+decides at the stack gate (`new-project-research-decision.md` step 6b).
+
+Write STACK.md accordingly:
+
+- **Every recommendation carries its premise** — the one condition that makes it
+  right. Not "WordPress is popular for content sites" but "WordPress IF a
+  non-technical person will update content with no dev retainer."
+- **Name the closest alternative and when it wins.** A recommendation with no
+  alternative is a decision wearing a recommendation's clothes.
+- **Never write "Locked", "Final", or "Decided"** in STACK.md. You have no
+  authority to lock anything; only a user answer at the gate does that.
+
+A premise you cannot state is a recommendation you have not justified. Say you
+don't have enough to recommend one rather than picking the familiar option.

package/rcode/agents/rules/sprint-checker/dimensions.md

@@ -194,6 +194,31 @@ issue:
 - Single task with 10+ files
 - Complex work (auth, payments) crammed into one plan
 
+### Check 5b — Vertical slice, not a layer
+
+Scope Sanity above measures plan SIZE. This measures plan SHAPE, which size
+cannot see: a perfectly sized plan that builds one horizontal layer is still
+wrong.
+
+For the phase as a whole, answer: **what can someone do after this phase that
+they could not do before?** If the honest answer is "nothing yet, later phases
+need it" → **WARNING**, and name it as layer-first phasing.
+
+Specific red flags:
+
+- Schema or migration work that creates tables no task in this phase reads or
+  writes. Tables belong to the first phase that uses them, not to a phase whose
+  purpose is tables.
+- A plan that builds a service, repository, or endpoint with no caller inside
+  the same phase and no task wiring it to one.
+- A phase goal naming a layer or artifact type ("the API", "the data model")
+  rather than a capability.
+
+Warning, not blocker: a genuine foundation phase (auth, migration framework) is
+sometimes correct. But it must name what it unblocks, and be no bigger than that
+— an unbounded foundation is the failure this check exists for. See
+`universal-anti-patterns.md` → Layer-first phasing.
+
 **Example issue:**
 ```yaml
 issue:

package/rcode/bin/lib/customize.cjs

@@ -0,0 +1,115 @@
+/**
+ * Customize — per-workflow and per-skill overrides that survive an update.
+ *
+ * The problem: customising rcode meant editing files under `.rcode/workflows/`,
+ * `.rcode/references/`, or `~/.claude/skills/rcode-*`. Every one of those is
+ * regenerated by the installer, so the edit worked until the next
+ * `rcode install` and then silently vanished. Users learned not to customise,
+ * or learned not to update.
+ *
+ * The fix: overrides live in `.rcode/custom/`, which the installer never writes,
+ * and are composed onto the shipped file at read time.
+ *
+ *   .rcode/custom/<name>.md        — team override, committed
+ *   .rcode/custom/<name>.user.md   — personal override, gitignored
+ *
+ * Both are APPENDED after the shipped content, in that order. Append rather than
+ * replace is deliberate: a replacing override silently drops whatever the next
+ * rcode version adds to that workflow, which is the same trap as editing the
+ * installed file, just slower to notice. If a shipped rule genuinely has to go,
+ * an override that says "ignore the X rule above, here is why" is auditable in a
+ * way a deletion never is.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function customDir(rcodeDir) {
+  return path.join(rcodeDir, 'custom');
+}
+
+/** Layers for one name, base first. Missing files are simply absent. */
+function layers(rcodeDir, name) {
+  const dir = customDir(rcodeDir);
+  const out = [];
+  for (const [kind, file] of [['team', `${name}.md`], ['user', `${name}.user.md`]]) {
+    const p = path.join(dir, file);
+    if (fs.existsSync(p)) {
+      const body = fs.readFileSync(p, 'utf8').trim();
+      if (body) out.push({ kind, path: path.join('.rcode', 'custom', file), body });
+    }
+  }
+  return out;
+}
+
+function resolve(rcodeDir, name) {
+  if (!name) throw new Error('customize resolve requires a name (workflow or skill id)');
+  const found = layers(rcodeDir, name);
+  return {
+    ok: true,
+    name,
+    has_overrides: found.length > 0,
+    layers: found.map((l) => ({ kind: l.kind, path: l.path })),
+    // Rendered block a workflow can paste after its own content. Empty string
+    // when nothing is overridden, so callers never special-case.
+    block: found.length === 0 ? '' : [
+      '',
+      `<!-- rcode custom overrides for "${name}" — appended, not replacing -->`,
+      ...found.map((l) => `\n### Override (${l.kind}) — ${l.path}\n\n${l.body}`),
+    ].join('\n'),
+  };
+}
+
+function list(rcodeDir) {
+  const dir = customDir(rcodeDir);
+  if (!fs.existsSync(dir)) return { ok: true, exists: false, overrides: [] };
+  const names = new Map();
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith('.md')) continue;
+    const isUser = f.endsWith('.user.md');
+    const name = isUser ? f.slice(0, -'.user.md'.length) : f.slice(0, -'.md'.length);
+    if (!names.has(name)) names.set(name, []);
+    names.get(name).push(isUser ? 'user' : 'team');
+  }
+  return {
+    ok: true,
+    exists: true,
+    overrides: [...names.entries()].map(([name, kinds]) => ({ name, kinds: kinds.sort() })),
+  };
+}
+
+function init(rcodeDir, name) {
+  const dir = customDir(rcodeDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const p = path.join(dir, `${name}.md`);
+  if (fs.existsSync(p)) return { ok: true, created: false, path: p };
+  fs.writeFileSync(p, `# Override: ${name}
+
+Appended after rcode's shipped content for \`${name}\`, every run.
+The installer never touches this file, so it survives \`rcode install\`.
+
+Write additional rules, project conventions, or explicit carve-outs here. To
+neutralise a shipped rule, say so and say why — that is auditable in a way
+deleting it from the installed file is not:
+
+> Ignore the "no files over 1000 lines" rule for \`src/generated/\` — those are
+> machine-generated and never hand-edited.
+`, 'utf8');
+  return { ok: true, created: true, path: p };
+}
+
+function dispatch(rcodeDir, args) {
+  const sub = args[0];
+  switch (sub) {
+    case 'resolve': return resolve(rcodeDir, args[1]);
+    case 'list':    return list(rcodeDir);
+    case 'init':    {
+      if (!args[1]) throw new Error('customize init requires a name');
+      return init(rcodeDir, args[1]);
+    }
+    default:
+      throw new Error(`Unknown customize subcommand: ${sub}. Use: resolve <name> | list | init <name>`);
+  }
+}
+
+module.exports = { dispatch, resolve, list, init };

package/rcode/bin/lib/memlog.cjs

@@ -0,0 +1,124 @@
+/**
+ * Memlog — the run's append-only memory.
+ *
+ * The problem it solves: rcode recorded decisions with `state add-decision`,
+ * manually, usually at the end of a session when someone remembered. Everything
+ * decided in between — an override, an assumption, a change of direction —
+ * existed only in the conversation, and was gone on the next `/clear` or resume.
+ * That is how a project ends up with artifacts nobody can explain and a state
+ * file that disagrees with what actually happened.
+ *
+ * The contract: one line per event, appended AS THE WORK HAPPENS, never
+ * reconstructed afterwards. Whatever is not logged is lost on resume.
+ *
+ * Deliberately append-only and never rewritten. A log you can edit is a log you
+ * can quietly correct, which defeats the point — a wrong entry is followed by a
+ * correcting entry, so the disagreement itself stays visible.
+ *
+ * This does NOT replace state.decisions[] / ~/.rcode/decisions.jsonl. Those are
+ * the curated, queryable record of decisions that stuck. The memlog is the raw
+ * trail, including the ones that were reversed.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const TYPES = Object.freeze(['decision', 'change', 'override', 'assumption', 'event', 'blocker']);
+const HEADER = `# Memlog
+
+Append-only. One line per event, written as the work happens.
+Never edit or delete a line — append a correcting entry instead, so the
+disagreement stays visible.
+
+| When | Type | Entry |
+|------|------|-------|
+`;
+
+function memlogPath(planningDir) {
+  return path.join(planningDir, 'MEMLOG.md');
+}
+
+function ensureMemlog(planningDir) {
+  const p = memlogPath(planningDir);
+  if (!fs.existsSync(p)) {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, HEADER, 'utf8');
+    return { created: true, path: p };
+  }
+  return { created: false, path: p };
+}
+
+/** Escape pipes so a free-text entry cannot break the markdown table. */
+function cell(text) {
+  return String(text).replace(/\|/g, '\\|').replace(/\r?\n/g, ' ').trim();
+}
+
+function append(planningDir, { type, text, phase }) {
+  if (!type) throw new Error(`memlog append requires --type (${TYPES.join('|')})`);
+  if (!TYPES.includes(type)) {
+    throw new Error(`unknown memlog type "${type}" — expected one of: ${TYPES.join(', ')}`);
+  }
+  if (!text || !String(text).trim()) throw new Error('memlog append requires --text');
+
+  ensureMemlog(planningDir);
+  const p = memlogPath(planningDir);
+  const when = new Date().toISOString().replace('T', ' ').slice(0, 16);
+  const label = phase ? `${type} · phase ${phase}` : type;
+  const line = `| ${when} | ${cell(label)} | ${cell(text)} |\n`;
+
+  // appendFileSync is atomic enough for single-line appends on every platform
+  // rcode targets, and an append cannot corrupt earlier lines the way a
+  // read-modify-write can when two agents log at once.
+  fs.appendFileSync(p, line, 'utf8');
+  return { ok: true, appended: true, type, path: path.relative(path.dirname(planningDir), p) };
+}
+
+function read(planningDir, { type, limit } = {}) {
+  const p = memlogPath(planningDir);
+  if (!fs.existsSync(p)) return { ok: true, exists: false, entries: [] };
+  const rows = fs.readFileSync(p, 'utf8').split('\n')
+    .filter((l) => l.startsWith('| 2') || /^\| \d{4}-/.test(l))
+    .map((l) => {
+      // Split on unescaped pipes only. cell() writes `\|` for a literal pipe in
+      // the text; a naive split('|') tore one entry into three columns and lost
+      // the tail. Caught by a test, not by reading the code.
+      const parts = l.split(/(?<!\\)\|/).map((c) => c.trim().replace(/\\\|/g, '|'));
+      return { when: parts[1] || '', type: parts[2] || '', text: parts[3] || '' };
+    });
+  let entries = type ? rows.filter((r) => r.type.split(' ')[0] === type) : rows;
+  if (limit) entries = entries.slice(-Number(limit));
+  return { ok: true, exists: true, total: rows.length, entries };
+}
+
+/**
+ * Unresolved assumptions and overrides — the entries that must not be forgotten
+ * at a milestone boundary. An assumption still sitting here after a whole
+ * milestone is a finding, not a formality.
+ */
+function open(planningDir) {
+  const all = read(planningDir);
+  if (!all.exists) return { ok: true, exists: false, open: [] };
+  const flagged = all.entries.filter((e) => {
+    const t = e.type.split(' ')[0];
+    return t === 'assumption' || t === 'override' || t === 'blocker';
+  });
+  return { ok: true, exists: true, open: flagged, count: flagged.length };
+}
+
+function dispatch(planningDir, args) {
+  const sub = args[0];
+  const flag = (name) => {
+    const i = args.indexOf(`--${name}`);
+    return i !== -1 ? args[i + 1] : undefined;
+  };
+  switch (sub) {
+    case 'init':   return { ok: true, ...ensureMemlog(planningDir) };
+    case 'append': return append(planningDir, { type: flag('type'), text: flag('text'), phase: flag('phase') });
+    case 'read':   return read(planningDir, { type: flag('type'), limit: flag('limit') });
+    case 'open':   return open(planningDir);
+    default:
+      throw new Error(`Unknown memlog subcommand: ${sub}. Use: init | append | read | open`);
+  }
+}
+
+module.exports = { dispatch, append, read, open, ensureMemlog, TYPES };

package/rcode/bin/lib/roadmap.cjs

@@ -127,28 +127,69 @@ function extractPhases(content) {
   return phases;
 }
 
+// Requirement IDs come in two shapes and BOTH are real:
+//   REQ-AUTH, REQ-FOO-BAR   — the documented convention
+//   FOUND-01, RENT-04, OBJ-06, AUTHZ-04 — what projects actually write
+// This must stay in step with extractReqIds() in rcode-tools.cjs. Two copies of
+// this pattern already drifted once: one was widened for domain prefixes and
+// this one was not, so `roadmap get-phase` kept returning requirements: [] on
+// every domain-prefixed project.
+const REQ_ID_RE = /\bREQ-[A-Z0-9][A-Z0-9-]*\b|\b[A-Z][A-Z0-9]{1,15}-\d+[a-z]?\b/g;
+
+/**
+ * Build a matcher for a labelled block, tolerant of how the label is actually
+ * written. Roadmapper emits `**Success criteria:**` (colon inside the bold,
+ * lowercase c) while the old parser demanded `**Success Criteria**:` (colon
+ * outside). Two rcode components disagreeing about rcode's own format is what
+ * made get-phase unable to read its own roadmapper's output.
+ *
+ * Accepts: **Label:**  |  **Label**:  |  ## Label  |  Label:
+ * Returns { inline, list } — inline is same-line content, list is the block
+ * of bullet/numbered lines that follows. Callers use whichever is present.
+ */
+function matchLabelledBlock(section, label) {
+  const l = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // [ \t]* everywhere the match must NOT cross a line. Using \s* here let the
+  // label matcher swallow the newline, so the first bullet of the following
+  // list was captured as "inline" and its description text was thrown away —
+  // `- CITY-02 per-city page exists` came back as just `CITY-02`.
+  const re = new RegExp(
+    '(?:\\*\\*[ \\t]*' + l + '[ \\t]*:?[ \\t]*\\*\\*[ \\t]*:?|#{1,4}[ \\t]*' + l + '[ \\t]*:?|^[ \\t]*' + l + '[ \\t]*:)' +
+    '([^\\n]*)\\n((?:[ \\t]*(?:\\d+\\.|[-*])[ \\t]+[^\\n]+\\n?)*)',
+    'im'
+  );
+  const m = section.match(re);
+  if (!m) return null;
+  return { inline: (m[1] || '').trim(), list: m[2] || '' };
+}
+
+function splitListBlock(block) {
+  return String(block).split('\n')
+    .map((l) => l.replace(/^[ \t]*(?:\d+\.|[-*])[ \t]+/, '').trim())
+    .filter(Boolean);
+}
+
 function parseRequirements(section) {
-  // Matches both bold-style (**Requirements:**) and heading-style (### Requirements)
-  // followed by a list block.
-  const listMatch = section.match(/(?:\*\*Requirements(?::\*\*|\*\*:)|#{1,4}\s*Requirements\s*:?)[^\n]*\n((?:\s*(?:\d+\.|[-*])\s+[^\n]+\n?)+)/i);
-  if (listMatch) {
-    return listMatch[1].split('\n')
-      .map((l) => l.replace(/^\s*(?:\d+\.|[-*])\s+/, '').trim())
-      .filter(Boolean);
+  const block = matchLabelledBlock(section, 'Requirements');
+  if (block) {
+    // A following list block wins; otherwise take the same-line value, which is
+    // how roadmapper writes it: `**Requirements:** FOUND-01, FOUND-02, RENT-04`.
+    const fromList = splitListBlock(block.list);
+    if (fromList.length > 0) return fromList;
+    if (block.inline) {
+      const ids = block.inline.match(REQ_ID_RE);
+      if (ids && ids.length > 0) return [...new Set(ids)];
+      return block.inline.split(/\s*,\s*/).map(x => x.trim()).filter(Boolean);
+    }
   }
 
-  // Also capture REQ-IDs from inline lines like:
-  //   **REQs:** REQ-004, REQ-010, REQ-020
-  //   Requirements: REQ-001, REQ-002
-  //   **Covers:** REQ-001, REQ-003
-  // Collect every line in the section that contains REQ-\d+ patterns.
+  // Last resort: sweep the whole section for requirement IDs on any line
+  // (covers `**REQs:**`, `**Covers:**`, and prose mentions).
   const seen = new Set();
   const out = [];
-  const reqIdRe = /\bREQ-[A-Z0-9][A-Z0-9-]*\b/g;
   for (const line of section.split('\n')) {
-    if (!/REQ-/i.test(line)) continue;
-    const ids = line.match(reqIdRe) || [];
-    for (const id of ids) {
+    const matches = line.match(REQ_ID_RE) || [];
+    for (const id of matches) {
       if (!seen.has(id)) { seen.add(id); out.push(id); }
     }
   }
@@ -156,12 +197,11 @@ function parseRequirements(section) {
 }
 
 function parseSuccessCriteria(section) {
-  // Matches both bold-style (**Success Criteria:**) and heading-style (### Success Criteria)
-  const match = section.match(/(?:\*\*Success Criteria\*\*[^\n]*:|#{1,4}\s*Success Criteria\s*:?)\s*\n((?:\s*(?:\d+\.|[-*])\s+[^\n]+\n?)+)/i);
-  if (!match) return [];
-  return match[1].split('\n')
-    .map((l) => l.replace(/^\s*(?:\d+\.|[-*])\s+/, '').trim())
-    .filter(Boolean);
+  const block = matchLabelledBlock(section, 'Success criteria');
+  if (!block) return [];
+  const fromList = splitListBlock(block.list);
+  if (fromList.length > 0) return fromList;
+  return block.inline ? [block.inline] : [];
 }
 
 function parsePlans(section) {