@hanzlaa/rcode 4.14.0 → 4.15.0

package/package.json

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

@@ -7167,6 +7167,16 @@ async function main() {
         if (args[0] === 'list') { result = cmdPhasesList(args.slice(1)); if (result === undefined) return; }
         else { console.error('Unknown phases subcommand. Valid: list'); process.exit(1); }
         break;
+      case 'customize': {
+        const customize = require(path.join(__dirname, 'lib', 'customize.cjs'));
+        result = customize.dispatch(RCODE_DIR, args);
+        break;
+      }
+      case 'memlog': {
+        const memlog = require(path.join(__dirname, 'lib', 'memlog.cjs'));
+        result = memlog.dispatch(PLANNING_DIR, args);
+        break;
+      }
       case 'find-phase':
         result = cmdFindPhase(args);
         break;
@@ -7615,6 +7625,9 @@ async function main() {
         console.log('  phase scaffold-milestone --names "n1|n2|..." → bulk-create phase folders for a milestone (#731)');
         console.log('  phase scaffold-all                           → create missing phase folders for all phases in ROADMAP.md (#731)');
         console.log('  phase rename-dir <N> [--apply]               → align a phase dir slug with its ROADMAP name (dry-run by default)');
+        console.log('  customize <resolve <name>|list|init <name>>  → per-workflow overrides in .rcode/custom/ that survive an update');
+        console.log('  memlog <init|append|read|open>               → append-only run memory (.planning/MEMLOG.md)');
+        console.log('    memlog append --type <decision|change|override|assumption|event|blocker> --text "..." [--phase N]');
         console.log('  workflow-config-audit                        → find workflows still referencing .planning/config.json (#733)');
         console.log('  commit "<msg>" [--files p1 p2 ...]          → atomic git commit with conventional-commits validation (no AI attribution, no --no-verify, no auto-push)');
         console.log('  commit-to-subrepo --subrepo <p> "<msg>"     → atomic commit inside a git subrepo (same validation as commit)');

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

@@ -41,6 +41,38 @@ on what it touches, so a high score is corroboration and a zero score is no
 information. When your reading disagrees with the score, your reading wins, and
 you name the file or decision that made you override.
 
+**Apply the project's overrides before you follow a shipped rule.** rcode's
+workflows and references are regenerated by the installer, so anything a project
+edited into them is lost on the next update. Overrides live in `.rcode/custom/`,
+which the installer never writes:
+
+```bash
+node ".rcode/bin/rcode-tools.cjs" customize resolve <workflow-or-reference-name>
+```
+
+Non-empty `block` is appended AFTER the shipped content and wins where they
+conflict. Overrides append rather than replace on purpose: a replacing override
+silently drops whatever the next rcode version adds, which is the same trap as
+editing the installed file, just slower to notice.
+
+**Log it when it happens, not when you remember.** Every decision, change of
+direction, override, and assumption goes into the memlog at the moment it occurs:
+
+```bash
+node ".rcode/bin/rcode-tools.cjs" memlog append \
+  --type <decision|change|override|assumption|event|blocker> \
+  --text "<one line, with the reason>" [--phase N]
+```
+
+Not at the end of the session, not "when there's a natural pause" — those are the
+entries that never get written. **Whatever is not logged is lost on the next
+`/clear` or resume**, and a project whose artifacts nobody can explain is the
+result. The memlog is append-only: a wrong entry is followed by a correcting
+entry, never edited away, so the disagreement stays visible.
+
+This does not replace `state add-decision` — that is the curated record of
+decisions that stuck. The memlog is the raw trail, including the reversals.
+
 **Elicitation is not authoring — hand the pen back.** When gathering what the user
 wants, the moment you catch yourself naming the stack, picking the MVP cut, or
 proposing the phase breakdown, stop and hand it back to them. Infer-and-confirm

package/rcode/references/roadmapper-playbook.md

@@ -156,6 +156,14 @@ Read only when the current task needs the detail. Don't preemptively load.
    **Read PROJECT.md's Glossary and use its terms verbatim** in phase names and
    goals. A roadmap that renames the domain's nouns forces every downstream
    agent to guess which concept a phase is about.
+   **Cut phases vertically.** Every phase must answer: what can someone do after
+   this that they could not do before? A phase whose goal names a layer ("the
+   data model", "the API", "all the repositories") rather than a capability is
+   horizontal, and everything it builds goes unexercised until some later phase
+   reaches for it — which is how a service ships with no caller. Create the
+   schema, services, and endpoints a phase's own capability needs, and no more.
+   A genuine foundation phase is allowed, but it names what it unblocks in the
+   same sentence and is no bigger than that.
    **Read PROJECT.md's Out of Scope (Non-Goals) before phasing.** A phase whose
    goal reaches into a declared non-goal is scope creep with a plan attached —
    flag it rather than quietly phasing it.

package/rcode/references/universal-anti-patterns.md

@@ -10,6 +10,32 @@ Phase plan picks up scope adjacent to the actual goal. Symptom: phase descriptio
 ### Implicit prerequisites
 Phase assumes another phase has shipped without declaring the dependency. Symptom: plan refers to a file or table that doesn't exist yet. Fix: surface the dependency in the phase's `Depends on` line in ROADMAP.md.
 
+### Layer-first phasing (horizontal slices)
+
+A phase whose whole job is one technical layer: "Phase 1 — create all the
+database tables", "Phase 2 — build every repository", "Phase 3 — the API".
+Symptom: the phase's goal names a layer or an artifact type rather than
+something a user can do afterwards, and no phase before the last one produces
+anything anybody can use.
+
+Why it costs more than it looks: nothing in a layer-first phase is exercised
+until a much later phase reaches for it, so a table, a service, or an endpoint
+can be built wrong — or built and never wired to anything — and pass every gate
+in between. Confirmed live: a project shipped a cycle-closing service with
+exactly one importer in the whole repo, its own test, because the phase that
+built it was never obliged to connect it to anything a user touches.
+
+Fix: **cut phases vertically.** Each phase delivers one thing end to end, and
+creates only the schema, services, and endpoints that thing needs. Tables get
+created by the first phase that reads or writes them, not by a phase whose
+purpose is tables. If a foundation genuinely must come first (auth, a
+migration framework), name what it unblocks in the same sentence and keep it as
+small as that.
+
+The test: read a phase goal and ask *what can someone do after this that they
+could not do before?* If the honest answer is "nothing yet, but later phases
+need it", the phase is horizontal.
+
 ### Vague acceptance
 Acceptance criterion is "users can do X" with no measurable threshold. Fix: make every acceptance criterion observable from outside the system — a CLI command, an API response, a log line, a UI assertion.
 

package/rcode/workflows/execute.md

@@ -41,8 +41,13 @@ a dashboard frozen at `planned`. See issue #915.
     is authorized from here:
     ```bash
     node ".rcode/bin/rcode-tools.cjs" state set-intent build --source execute.md
+    node ".rcode/bin/rcode-tools.cjs" memlog append --type event --text "Execution started for phase ${PHASE_NUMBER}" --phase "${PHASE_NUMBER}"
     ```
 
+    Log every deviation, checkpoint decision, and override with
+    `memlog append` as it happens — a deviation nobody recorded is
+    indistinguishable from a plan that was followed.
+
 **Mandatory before execution begins.** Run these checks first and surface
 findings BEFORE any subagents are spawned. If any check fails, stop and
 route back to the user.

package/rcode/workflows/new-project-research-decision.md

@@ -281,6 +281,8 @@ Record the answer with `state add-decision`, including the premise it rests on:
 ```bash
 node ".rcode/bin/rcode-tools.cjs" state add-decision \
   "Stack: {chosen}. Premise: {the one reason}. Confirmed by user {date}."
+node ".rcode/bin/rcode-tools.cjs" memlog append --type decision \
+  --text "Stack: {chosen}. Premise: {the one reason}. User-confirmed at the stack gate."
 ```
 
 ### The premise is part of the decision

package/rcode/workflows/new-project.md

@@ -711,6 +711,11 @@ This document evolves at phase transitions and milestone boundaries.
 5. Assumptions Index — any row still `unconfirmed` after a whole milestone is a
    finding, not a formality. Resolve or escalate it
 6. Key Decisions — check every premise still holds
+7. **Memlog audit** — `rcode-tools.cjs memlog open` lists every assumption,
+   override, and blocker logged during the milestone. Walk it: each one is
+   captured in PROJECT.md, resolved, or explicitly deferred with an owner.
+   Entries that survive a whole milestone unexamined are the ones that turn into
+   "nobody knows why this is like this" 
 
 ---
 *Last updated: {date} after initialization*

package/rcode/workflows/plan.md

@@ -103,9 +103,18 @@ exists to prevent (see step 8).
 ## 0.4. Record the authorized scope
 
 ```bash
+# Project overrides for this workflow — appended after everything below, and
+# they win on conflict. The installer never writes .rcode/custom/, so these
+# survive `rcode install`.
+node ".rcode/bin/rcode-tools.cjs" customize resolve plan
 node ".rcode/bin/rcode-tools.cjs" state set-intent plan --source plan.md
+node ".rcode/bin/rcode-tools.cjs" memlog append --type event --text "Planning started for phase ${PHASE}" --phase "${PHASE}"
 ```
 
+**Log as you go from here.** Every decision the panel forces, every checker issue
+you accept or reject, every assumption the planner had to make — one
+`memlog append` line each, at the moment it happens.
+
 This is what the user asked for on THIS invocation, and it is what `resume-work`
 will restore later. Planning does not authorize building — see step 15.