@hanzlaa/rcode 2.1.0 → 2.3.1

package/package.json

@@ -1,22 +1,25 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "2.1.0",
+  "version": "2.3.1",
   "description": "Rihal Code (rcode) — installable context-brain for Rihalians. 44 agents, 93 slash commands, 58 skills, pullable Rihal standards. Unified install for Claude Code, Cursor, and Gemini.",
   "main": "cli/index.js",
   "bin": {
-    "rcode": "cli/index.js",
-    "rihal-code": "cli/index.js"
+    "rcode": "dist/rcode.js",
+    "rihal-code": "dist/rcode.js"
   },
   "scripts": {
     "dashboard": "node server/dashboard.js",
     "test": "node --test",
     "test:ci": "node --test --test-reporter=spec",
-    "postinstall": "node cli/postinstall.js"
+    "postinstall": "node cli/postinstall.js",
+    "build:cli": "node scripts/build.cjs",
+    "build": "node scripts/build.cjs"
   },
   "files": [
     "cli/",
     "rihal/",
     "server/",
+    "dist/",
     ".rihal-template/",
     "README.md",
     "AGENTS.md",
@@ -54,6 +57,16 @@
     "node": ">=18.0.0"
   },
   "dependencies": {},
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "picocolors": "^1.1.1",
+    "nanospinner": "^1.2.2",
+    "fast-glob": "^3.3.3",
+    "zod": "^3.24.0",
+    "semver": "^7.7.1",
+    "diff": "^7.0.0",
+    "@clack/prompts": "^0.9.1"
+  },
   "publishConfig": {
     "access": "public"
   }

package/rihal/DOCS-AUDIT.md

@@ -0,0 +1,14 @@
+# DOCS-AUDIT.md (per-project artefact)
+
+This file is generated by `/rihal:document-project` into the project root
+as `DOCS-AUDIT.md`. The shipped reference here just defines the schema:
+
+- **Inventory:** every doc file (path, last-touched, owner, freshness).
+- **Gaps:** docs that should exist per the project's domain (e.g. README,
+  CONTRIBUTING, ADRs for major decisions) but don't.
+- **Stale:** docs that diverge from current code/state (links to dead
+  files, version mismatches, removed features still documented).
+- **Recommendations:** ordered remediation list.
+
+Workflows that @-include this file expect the live audit output, which
+the workflow itself writes to disk before reading.

package/rihal/agents/rihal-code-reviewer.md

@@ -6,7 +6,7 @@ color: purple
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 # Rihal Code Reviewer

package/rihal/agents/rihal-codebase-mapper.md

@@ -7,7 +7,7 @@ color: cyan
 
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 
 <role>
 You are a rihal codebase mapper. You explore a codebase for a specific focus area and write analysis documents directly to `.rihal/codebase/`.

package/rihal/agents/rihal-docs-auditor.md

@@ -6,7 +6,7 @@ color: gold
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 # Rihal Documentation Auditor

package/rihal/agents/rihal-edge-case-hunter.md

@@ -6,7 +6,7 @@ color: maroon
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 # Rihal Edge Case Hunter

package/rihal/agents/rihal-executor.md

@@ -6,7 +6,7 @@ color: yellow
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/output-realism.md
 @.rihal/references/no-unauthorized-git-ops.md
 

package/rihal/agents/rihal-hussain-pm.md

@@ -7,6 +7,7 @@ color: orange
 
 @.rihal/references/response-style.md
 @.rihal/references/codebase-grounding.md
+@.rihal/references/karpathy-guidelines.md
 
 # Hussain-PM — Product Manager
 

package/rihal/agents/rihal-nyquist-auditor.md

@@ -6,7 +6,7 @@ color: #8B5CF6
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 <role>

package/rihal/agents/rihal-phase-researcher.md

@@ -7,8 +7,7 @@ color: cyan
 
 
 @.rihal/references/response-style.md
-
-
+@.rihal/references/karpathy-guidelines.md
 
 <role>
 You are a Rihal phase researcher. You answer "What do I need to know to PLAN this phase well?" and produce a single RESEARCH.md that the planner consumes.

package/rihal/agents/rihal-planner.md

@@ -6,7 +6,7 @@ color: green
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/output-realism.md
 
 <role>

package/rihal/agents/rihal-roadmapper.md

@@ -8,6 +8,7 @@ color: purple
 
 @.rihal/references/response-style.md
 @.rihal/references/output-realism.md
+@.rihal/references/karpathy-guidelines.md
 
 <role>
 You are a rihal roadmapper. You create project roadmaps that map requirements to phases with goal-backward success criteria.

package/rihal/agents/rihal-security-adversary.md

@@ -6,7 +6,7 @@ color: darkred
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 # Rihal Security Adversary

package/rihal/agents/rihal-security-auditor.md

@@ -6,7 +6,7 @@ color: purple
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 # Rihal Security Auditor

package/rihal/agents/rihal-sprint-checker.md

@@ -7,7 +7,7 @@ color: green
 
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 
 <role>
 You are a Rihal sprint checker. Verify that sprints WILL achieve the phase goal, not just that they look complete.

package/rihal/agents/rihal-verifier.md

@@ -6,7 +6,7 @@ color: green
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 <role>

package/rihal/bin/lib/roadmap.cjs

@@ -1,9 +1,8 @@
 /**
  * Roadmap — Rihal ROADMAP.md parsing and mutation helpers.
  *
- * Self-contained (stdlib only). Matches GSD output shapes for the subset of
- * commands that Rihal workflows currently invoke: get-phase, list-phases,
- * update-plan-progress, and clear.
+ * Self-contained (stdlib only). Subcommands invoked by Rihal workflows:
+ * get-phase, list-phases, update-plan-progress, clear.
  */
 
 const fs = require('fs');

package/rihal/bin/rihal-tools.cjs

@@ -1950,7 +1950,7 @@ function cmdState(subArgs) {
   // --- promote-backlog <from> --to <target> ---
   // Promote a 999.x parking-lot phase to a real phase number.
   // Mutates state.phases[]; renames the on-disk directory if present.
-  // Tracks issue #159 (M2.5 — GSD-parity 999.x convention).
+  // Tracks issue #159 (M2.5 — 999.x parking-lot convention).
   if (sub === 'promote-backlog') {
     const from = subArgs[1];
     const flags = parseFlags(2);
@@ -2568,8 +2568,12 @@ function cmdResolveModel(agentId) {
 }
 
 /**
- * config set --key <k> --value <v> — update a key in .rihal/config.yaml
- * Writes YAML-style `key: value` (quotes strings with spaces).
+ * config set --key <k> --value <v> — DEPRECATED legacy form.
+ *
+ * Closes #233. The original implementation used a flat YAML parser that
+ * destroyed the nested `workflow:` and `git:` sections on every save.
+ * This shim now delegates to the nested-safe writer in lib/config.cjs and
+ * emits a one-line deprecation warning to stderr so callers migrate.
  */
 function cmdConfigSet(subArgs) {
   const flags = {};
@@ -2587,34 +2591,10 @@ function cmdConfigSet(subArgs) {
   if (!key) throw new Error('config set requires --key <key> --value <value>\n  e.g. config set --key language --value Arabic');
   if (!value) throw new Error('config set requires --key <key> --value <value>\n  e.g. config set --key language --value Arabic');
 
-  const configPath = path.join(RIHAL_DIR, 'config.yaml');
-  fs.mkdirSync(RIHAL_DIR, { recursive: true });
-
-  let content = '';
-  if (fs.existsSync(configPath)) {
-    content = fs.readFileSync(configPath, 'utf8');
-  }
-
-  // Parse current config
-  const config = parseSimpleYaml(content);
-
-  // Update the key
-  config[key] = value;
-
-  // Serialize back to YAML
-  const lines = [];
-  for (const [k, v] of Object.entries(config)) {
-    const needsQuotes = /\s/.test(v);
-    const yamlValue = needsQuotes ? `"${v.replace(/"/g, '\\"')}"` : v;
-    lines.push(`${k}: ${yamlValue}`);
-  }
-
-  const newContent = lines.join('\n') + '\n';
-  const tmp = configPath + '.tmp';
-  fs.writeFileSync(tmp, newContent, 'utf8');
-  fs.renameSync(tmp, configPath);
+  process.stderr.write(`[deprecated] 'config set --key X --value Y' — use 'config-set X Y' instead (preserves nested YAML).\n`);
 
-  return { ok: true, key, value, path: configPath };
+  const cfg = require(path.join(__dirname, 'lib', 'config.cjs'));
+  return cfg.cmdSet(PROJECT_ROOT, key, value);
 }
 
 /**
@@ -2805,8 +2785,26 @@ function cmdNotesCount() {
  */
 function cmdBrain(args) {
   const sub = args[0] || 'help';
-  const sourcesPath = path.join(PROJECT_ROOT, 'rihal', 'brain', 'sources.yaml');
-  const brainDir = path.join(PROJECT_ROOT, 'rihal', 'brain');
+  // sources.yaml lives under .rihal/brain/ in user installs (v2.2+).
+  // Older installs may have it at rihal/brain/ (pre-v2.2) — fall back for compat.
+  let sourcesPath = path.join(RIHAL_DIR, 'brain', 'sources.yaml');
+  let brainDir = path.join(RIHAL_DIR, 'brain');
+  if (!fs.existsSync(sourcesPath)) {
+    const legacyPath = path.join(PROJECT_ROOT, 'rihal', 'brain', 'sources.yaml');
+    if (fs.existsSync(legacyPath)) {
+      sourcesPath = legacyPath;
+      brainDir = path.join(PROJECT_ROOT, 'rihal', 'brain');
+    }
+  }
+
+  // Resolve a source's dest directory relative to brainDir.
+  // Accepts legacy absolute-looking values ("rihal/brain/rihal-github/") by
+  // stripping any leading "rihal/brain/" so the resolved path sits inside the
+  // chosen brainDir. New sources.yaml should use bare names ("rihal-github/").
+  function resolveDest(dest) {
+    const trimmed = String(dest || '').replace(/^rihal\/brain\//, '').replace(/^\/+/, '');
+    return path.join(brainDir, trimmed);
+  }
 
   if (!fs.existsSync(sourcesPath)) {
     return {
@@ -2913,7 +2911,7 @@ function cmdBrain(args) {
   if (sub === 'status') {
     const report = { ok: true, sources: [] };
     for (const s of sources) {
-      const destPath = path.join(PROJECT_ROOT, s.dest || '');
+      const destPath = resolveDest(s.dest);
       const exists = fs.existsSync(destPath);
       report.sources.push({
         name: s.name,
@@ -2947,7 +2945,7 @@ function cmdBrain(args) {
 
     if (repo === 'self') {
       // In-repo copy — use rsync-ish node copy from paths under project root.
-      const destPath = path.join(PROJECT_ROOT, s.dest);
+      const destPath = resolveDest(s.dest);
       fs.mkdirSync(destPath, { recursive: true });
       const paths = Array.isArray(s.paths) ? s.paths : [];
       let copied = 0;
@@ -2989,7 +2987,7 @@ function cmdBrain(args) {
       const paths = Array.isArray(s.paths) ? s.paths : [];
       execSync(`git -C "${tmp}" sparse-checkout set ${paths.map(p => `"${p}"`).join(' ')}`, { stdio: 'pipe' });
 
-      const destPath = path.join(PROJECT_ROOT, s.dest);
+      const destPath = resolveDest(s.dest);
       fs.mkdirSync(destPath, { recursive: true });
       // Copy everything the sparse checkout materialized.
       function copyTree(src, dst) {
@@ -3015,7 +3013,7 @@ function cmdBrain(args) {
 }
 
 /**
- * cmdProgress — single pre-computed progress blob (GSD-parity, issue #159).
+ * cmdProgress — single pre-computed progress blob (issue #159).
  *
  * Subcommands:
  *   progress init          Full snapshot — everything /rihal:progress needs.
@@ -3301,6 +3299,121 @@ function cmdStateSnapshot() {
   };
 }
 
+/**
+ * cmdGitignore — re-render the rcode-managed block in .gitignore based on
+ * current config (specifically commit_planning from .rihal/config.yaml).
+ *
+ * Subcommands:
+ *   gitignore refresh   rewrite the rcode block in-place
+ *   gitignore status    report current commit_planning + block presence
+ *
+ * Mirrors the logic in cli/install.js ensureRcodeGitignore — kept in sync
+ * by convention. Any change to the block format should update both.
+ * Closes #189 — runtime toggle for commit_planning.
+ */
+function cmdGitignore(args) {
+  const sub = args[0] || 'refresh';
+  const gitignorePath = path.join(PROJECT_ROOT, '.gitignore');
+  const configPath = path.join(RIHAL_DIR, 'config.yaml');
+
+  // Read commit_planning from config; default true if missing.
+  let commitPlanning = true;
+  if (fs.existsSync(configPath)) {
+    const cfg = fs.readFileSync(configPath, 'utf8');
+    const m = cfg.match(/^\s*commit_planning:\s*(true|false)\s*$/m);
+    if (m) commitPlanning = (m[1] === 'true');
+  }
+
+  const BEGIN = '# ===== rcode-managed gitignore block (npx @hanzlaa/rcode install) =====';
+  const END   = '# ===== end rcode-managed gitignore block =====';
+
+  if (sub === 'status') {
+    const exists = fs.existsSync(gitignorePath);
+    const hasBlock = exists && fs.readFileSync(gitignorePath, 'utf8').includes(BEGIN);
+    return {
+      ok: true,
+      gitignore_exists: exists,
+      block_present: hasBlock,
+      commit_planning: commitPlanning,
+    };
+  }
+
+  if (sub !== 'refresh') {
+    return { ok: false, error: `Unknown gitignore subcommand: ${sub}. Try: refresh | status` };
+  }
+
+  const lines = [
+    '',
+    BEGIN,
+    '# Added automatically on rcode install. Idempotent — safe to re-run.',
+    '# Edit `commit_planning` in .rihal/config.yaml, then: rihal-tools gitignore refresh',
+    '',
+    '# Installed methodology files (regenerate with: npx @hanzlaa/rcode install)',
+    '.claude/',
+    '.rihal/bin/',
+    '.rihal/workflows/',
+    '.rihal/references/',
+    '.rihal/commands/',
+    '.rihal/skills/',
+    '',
+    '# Pulled Rihal brain content (refresh with: rcode brain pull)',
+    '.rihal/brain/rihal-github/',
+    '.rihal/brain/rihal-docs/',
+    '.rihal/brain/best-practices/',
+    '',
+    '# Runtime noise',
+    '.rihal/state.json.lock',
+    '.planning/debug/',
+    '.planning/_backup/',
+  ];
+  if (!commitPlanning) {
+    lines.push('', '# Planning artifacts — kept local (commit_planning: false)', '.planning/');
+  }
+  lines.push(
+    '',
+    '# What you DO commit:',
+    '#   .rihal/config.yaml        - project mode/language/profile/commit_planning',
+    '#   .rihal/state.json         - decisions, roadmap pointer, blockers',
+    '#   .rihal/brain/sources.yaml - brain source manifest',
+    commitPlanning
+      ? '#   .planning/                - PRD, roadmap, sprints, SUMMARY.md files'
+      : '#   (planning artifacts are NOT committed — see commit_planning in config)',
+    END,
+    ''
+  );
+  const BLOCK = lines.join('\n');
+
+  /** Replace the rcode block in text using indexOf — safer than regex. */
+  function spliceBlock(existing, newBlock) {
+    const start = existing.indexOf(BEGIN);
+    if (start < 0) return null;
+    const endIdx = existing.indexOf(END, start);
+    if (endIdx < 0) return null;
+    // Include trailing newline after END if present, and leading newline before BEGIN.
+    let sliceStart = start;
+    if (sliceStart > 0 && existing[sliceStart - 1] === '\n') sliceStart -= 1;
+    let sliceEnd = endIdx + END.length;
+    if (existing[sliceEnd] === '\n') sliceEnd += 1;
+    return existing.slice(0, sliceStart) + newBlock + existing.slice(sliceEnd);
+  }
+
+  if (!fs.existsSync(gitignorePath)) {
+    fs.writeFileSync(gitignorePath, BLOCK);
+    return { ok: true, action: 'created', commit_planning: commitPlanning };
+  }
+  const existing = fs.readFileSync(gitignorePath, 'utf8');
+  if (existing.includes(BEGIN)) {
+    const rewritten = spliceBlock(existing, BLOCK);
+    if (rewritten !== null && rewritten !== existing) {
+      fs.writeFileSync(gitignorePath, rewritten);
+      return { ok: true, action: 'updated', commit_planning: commitPlanning };
+    }
+    return { ok: true, action: 'no-change', commit_planning: commitPlanning };
+  }
+  fs.writeFileSync(gitignorePath, existing + BLOCK);
+  return { ok: true, action: 'appended', commit_planning: commitPlanning };
+}
+
 function cmdFindFiles(rawArgs) {
   const flags = {};
   const parts = rawArgs.split(/\s+/).filter(p => p);
@@ -3455,6 +3568,10 @@ async function main() {
         result = cmdStateSnapshot();
         break;
       }
+      case 'gitignore': {
+        result = cmdGitignore(args);
+        break;
+      }
       case 'agent-skills':
         result = cmdAgentInfo(args[0]);
         break;

package/rihal/brain/sources.yaml

@@ -34,7 +34,7 @@ sources:
       - docs/issue-standards.md
       - docs/commit-standards.md
       - docs/review-checklist.md
-    dest: rihal/brain/rihal-github/
+    dest: rihal-github/
 
   - name: rihal-docs
     description: >
@@ -47,13 +47,16 @@ sources:
       - "guides/**/*.md"
       - "standards/**/*.md"
       - "playbooks/**/*.md"
-    dest: rihal/brain/rihal-docs/
+    dest: rihal-docs/
 
   - name: rihal-best-practices
     description: >
       Hanzla's one-year-of-usage best practices — in-repo, version-
-      controlled alongside the rest of Rihal Code.
+      controlled alongside the rest of Rihal Code. Resolved from the
+      installed .rihal/skills/_shared/ dir (or the package's own
+      rihal/skills/_shared/ when running inside the rihal-code repo).
     repo: self
     paths:
+      - .rihal/skills/_shared/**/*.md
       - rihal/skills/_shared/**/*.md
-    dest: rihal/brain/best-practices/
+    dest: best-practices/

package/rihal/commands/audit.md

@@ -0,0 +1,8 @@
+---
+name: rihal:audit
+description: Single audit entry point — asks what to audit (phase, milestone, UAT, code, fix, work) and dispatches to the right subroute. Honours .rihal/config.yaml mode.
+argument-hint: "[phase | milestone | uat | code | fix | work] [...subroute args]"
+allowed-tools: Read, Write, Bash, AskUserQuestion
+---
+
+@.rihal/workflows/audit.md

package/rihal/commands/checkpoint-preview.md

@@ -0,0 +1,13 @@
+---
+name: rihal:checkpoint-preview
+description: Human-in-the-loop change review — makes sense of a diff, focuses attention where it matters, and walks through testing. Use when you say "checkpoint", "walk me through this", or "human review".
+argument-hint: "[<branch-or-diff>]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+@.rihal/workflows/checkpoint-preview.md

package/rihal/commands/config.md

@@ -1,8 +1,8 @@
 ---
 name: rihal:config
-description: View or edit Rihal configuration (language, mode, model profile, branching strategy)
-argument-hint: "[show | set <key> <value>]"
-allowed-tools: Read, Bash, AskUserQuestion
+description: Alias for /rihal:settings — view or edit Rihal config (language, mode, model profile, workflow gates, git strategy)
+argument-hint: "[show | get <key> | set <key> <value>]"
+allowed-tools: Read, Write, Bash, AskUserQuestion
 ---
 
-@.rihal/workflows/config.md
+@.rihal/workflows/settings.md

package/rihal/commands/prfaq.md

@@ -0,0 +1,15 @@
+---
+name: rihal:prfaq
+description: Working Backwards PRFAQ challenge — stress-test a product concept by writing the press release before building it. Produces a battle-hardened PRFAQ document + PRD distillate.
+argument-hint: "[<idea>] [--headless] [--customer=<persona>] [--problem=<problem>] [--stakes=<why>] [--solution=<concept>]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Agent
+  - AskUserQuestion
+  - WebSearch
+  - WebFetch
+---
+
+@.rihal/workflows/prfaq.md

package/rihal/commands/settings.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:settings
-description: Interactive configuration wizard for Rihal project settings. Update model profile, research strategy, execution gates, and branching strategy.
-argument-hint: ""
+description: View or edit Rihal project settings (mode, model_profile, workflow gates, git strategy). Supports show / get / set / interactive modes.
+argument-hint: "[show | get <key> | set <key> <value>]"
 allowed-tools: Read, Write, Bash, AskUserQuestion
 ---
 

package/rihal/references/agent-contracts.md

@@ -0,0 +1,12 @@
+# Agent Contracts
+
+Conventions Rihal sub-agents follow when invoked from a workflow.
+
+- **Input**: a single prompt string. The orchestrator passes structured data
+  inline (path lists, JSON blobs) — sub-agents do not stream args.
+- **Output**: one final message back to the orchestrator. No partial state
+  is visible mid-run.
+- **Side effects**: each agent's tool list is its full surface — any tool
+  not granted in the agent definition is unavailable.
+- **Failure**: agents that hit an obstacle return a structured "blocked"
+  message rather than fabricating output.