@hanzlaa/rcode 2.1.0

package/rihal/agents/rules/verifier/data-flow-trace.md

@@ -0,0 +1,65 @@
+# Verifier — Data-Flow Trace (Step 4b / Level 4)
+
+Artifacts that pass Levels 1-3 (exist, substantive, wired) can still be hollow if their data source produces empty or hardcoded values. Level 4 traces upstream from the artifact to verify real data flows through the wiring.
+
+**When to run:** For each artifact that passes Level 3 (WIRED) and renders dynamic data (components, pages, dashboards — not utilities or configs).
+
+## How
+
+### 1. Identify the data variable
+
+What state/prop does the artifact render?
+
+```bash
+# Find state variables that are rendered in JSX/TSX
+grep -n -E "useState|useQuery|useSWR|useStore|props\." "$artifact" 2>/dev/null
+```
+
+### 2. Trace the data source
+
+Where does that variable get populated?
+
+```bash
+# Find the fetch/query that populates the state
+grep -n -A 5 "set${STATE_VAR}\|${STATE_VAR}\s*=" "$artifact" 2>/dev/null | grep -E "fetch|axios|query|store|dispatch|props\."
+```
+
+### 3. Verify the source produces real data
+
+Does the API/store return actual data or static/empty values?
+
+```bash
+# Check the API route or data source for real DB queries vs static returns
+grep -n -E "prisma\.|db\.|query\(|findMany|findOne|select|FROM" "$source_file" 2>/dev/null
+
+# Flag: static returns with no query
+grep -n -E "return.*json\(\s*\[\]|return.*json\(\s*\{\}" "$source_file" 2>/dev/null
+```
+
+### 4. Check for disconnected props
+
+Props passed to child components that are hardcoded empty at the call site:
+
+```bash
+# Find where the component is used and check prop values
+grep -r -A 3 "<${COMPONENT_NAME}" "${search_path:-src/}" --include="*.tsx" 2>/dev/null | grep -E "=\{(\[\]|\{\}|null|''|\"\")\}"
+```
+
+## Data-flow status
+
+| Data Source | Produces Real Data | Status |
+| ---------- | ------------------ | ------ |
+| DB query found | Yes | ✓ FLOWING |
+| Fetch exists, static fallback only | No | ⚠️ STATIC |
+| No data source found | N/A | ✗ DISCONNECTED |
+| Props hardcoded empty at call site | No | ✗ HOLLOW_PROP |
+
+## Final Artifact Status (updated with Level 4)
+
+| Exists | Substantive | Wired | Data Flows | Status |
+| ------ | ----------- | ----- | ---------- | ------ |
+| ✓ | ✓ | ✓ | ✓ | ✓ VERIFIED |
+| ✓ | ✓ | ✓ | ✗ | ⚠️ HOLLOW — wired but data disconnected |
+| ✓ | ✓ | ✗ | - | ⚠️ ORPHANED |
+| ✓ | ✗ | - | - | ✗ STUB |
+| ✗ | - | - | - | ✗ MISSING |

package/rihal/agents/rules/verifier/gap-output.md

@@ -0,0 +1,51 @@
+# Verifier — Status Determination + Gap Output (Steps 8–10)
+
+## Step 8: Identify Human Verification Needs
+
+**Always needs human:** Visual appearance, user flow completion, real-time behavior, external service integration, performance feel, error message clarity.
+
+**Needs human if uncertain:** Complex wiring grep can't trace, dynamic state behavior, edge cases.
+
+**Format:**
+
+```markdown
+### 1. {Test Name}
+
+**Test:** {What to do}
+**Expected:** {What should happen}
+**Why human:** {Why can't verify programmatically}
+```
+
+## Step 9: Determine Overall Status
+
+**Status: passed** — All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns.
+
+**Status: gaps_found** — One or more truths FAILED, artifacts MISSING/STUB, key links NOT_WIRED, or blocker anti-patterns found.
+
+**Status: human_needed** — All automated checks pass but items flagged for human verification.
+
+**Score:** `verified_truths / total_truths`
+
+## Step 10: Structure Gap Output (If Gaps Found)
+
+Structure gaps in YAML frontmatter for `/rihal:plan --gaps`:
+
+```yaml
+gaps:
+  - truth: "Observable truth that failed"
+    status: failed
+    reason: "Brief explanation"
+    artifacts:
+      - path: "src/path/to/file.tsx"
+        issue: "What's wrong"
+    missing:
+      - "Specific thing to add/fix"
+```
+
+- `truth`: The observable truth that failed
+- `status`: failed | partial
+- `reason`: Brief explanation
+- `artifacts`: Files with issues
+- `missing`: Specific things to add/fix
+
+**Group related gaps by concern** — if multiple truths fail from the same root cause, note this to help the planner create focused plans.

package/rihal/agents/rules/verifier/key-links.md

@@ -0,0 +1,56 @@
+# Verifier — Key Link Wiring Patterns (Step 5)
+
+Key links are critical connections. If broken, the goal fails even with all artifacts present.
+
+Use rihal-tools for key link verification against must_haves in PLAN frontmatter:
+
+```bash
+LINKS_RESULT=$(node ".rihal/bin/rihal-tools.cjs" verify key-links "$PLAN_PATH")
+```
+
+Parse JSON result: `{ all_verified, verified, total, links: [{from, to, via, verified, detail}] }`
+
+For each link:
+- `verified=true` → WIRED
+- `verified=false` with "not found" in detail → NOT_WIRED
+- `verified=false` with "Pattern not found" → PARTIAL
+
+## Fallback Patterns
+
+Use these if `must_haves.key_links` not defined in PLAN.
+
+### Pattern: Component → API
+
+```bash
+grep -E "fetch\(['\"].*$api_path|axios\.(get|post).*$api_path" "$component" 2>/dev/null
+grep -A 5 "fetch\|axios" "$component" | grep -E "await|\.then|setData|setState" 2>/dev/null
+```
+
+Status: WIRED (call + response handling) | PARTIAL (call, no response use) | NOT_WIRED (no call)
+
+### Pattern: API → Database
+
+```bash
+grep -E "prisma\.$model|db\.$model|$model\.(find|create|update|delete)" "$route" 2>/dev/null
+grep -E "return.*json.*\w+|res\.json\(\w+" "$route" 2>/dev/null
+```
+
+Status: WIRED (query + result returned) | PARTIAL (query, static return) | NOT_WIRED (no query)
+
+### Pattern: Form → Handler
+
+```bash
+grep -E "onSubmit=\{|handleSubmit" "$component" 2>/dev/null
+grep -A 10 "onSubmit.*=" "$component" | grep -E "fetch|axios|mutate|dispatch" 2>/dev/null
+```
+
+Status: WIRED (handler + API call) | STUB (only logs/preventDefault) | NOT_WIRED (no handler)
+
+### Pattern: State → Render
+
+```bash
+grep -E "useState.*$state_var|\[$state_var," "$component" 2>/dev/null
+grep -E "\{.*$state_var.*\}|\{$state_var\." "$component" 2>/dev/null
+```
+
+Status: WIRED (state displayed) | NOT_WIRED (state exists, not rendered)

package/rihal/agents/rules/verifier/requirements-coverage.md

@@ -0,0 +1,28 @@
+# Verifier — Requirements Coverage (Step 6)
+
+## 6a. Extract requirement IDs from PLAN frontmatter
+
+```bash
+grep -A5 "^requirements:" "$PHASE_DIR"/*-SPRINT.md 2>/dev/null
+```
+
+Collect ALL requirement IDs declared across plans for this phase.
+
+## 6b. Cross-reference against REQUIREMENTS.md
+
+For each requirement ID from plans:
+
+1. Find its full description in REQUIREMENTS.md (`**REQ-ID**: description`)
+2. Map to supporting truths/artifacts verified in Steps 3-5
+3. Determine status:
+   - ✓ SATISFIED: Implementation evidence found that fulfills the requirement
+   - ✗ BLOCKED: No evidence or contradicting evidence
+   - ? NEEDS HUMAN: Can't verify programmatically (UI behavior, UX quality)
+
+## 6c. Check for orphaned requirements
+
+```bash
+grep -E "Phase $PHASE_NUM" .rihal/REQUIREMENTS.md 2>/dev/null
+```
+
+If REQUIREMENTS.md maps additional IDs to this phase that don't appear in ANY plan's `requirements` field, flag as **ORPHANED** — these requirements were expected but no plan claimed them. ORPHANED requirements MUST appear in the verification report.

package/rihal/agents/rules/verifier/verification-report.md

@@ -0,0 +1,131 @@
+# Verifier — VERIFICATION.md Template + Return Format
+
+## Create VERIFICATION.md
+
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+
+Create `.rihal/phases/{phase_dir}/{phase_num}-VERIFICATION.md`:
+
+```markdown
+---
+phase: XX-name
+verified: YYYY-MM-DDTHH:MM:SSZ
+status: passed | gaps_found | human_needed
+score: N/M must-haves verified
+re_verification: # Only if previous VERIFICATION.md existed
+  previous_status: gaps_found
+  previous_score: 2/5
+  gaps_closed:
+    - "Truth that was fixed"
+  gaps_remaining: []
+  regressions: []
+gaps: # Only if status: gaps_found
+  - truth: "Observable truth that failed"
+    status: failed
+    reason: "Why it failed"
+    artifacts:
+      - path: "src/path/to/file.tsx"
+        issue: "What's wrong"
+    missing:
+      - "Specific thing to add/fix"
+human_verification: # Only if status: human_needed
+  - test: "What to do"
+    expected: "What should happen"
+    why_human: "Why can't verify programmatically"
+---
+
+# Phase {X}: {Name} Verification Report
+
+**Phase Goal:** {goal from ROADMAP.md}
+**Verified:** {timestamp}
+**Status:** {status}
+**Re-verification:** {Yes — after gap closure | No — initial verification}
+
+## Goal Achievement
+
+### Observable Truths
+
+| #   | Truth   | Status     | Evidence       |
+| --- | ------- | ---------- | -------------- |
+| 1   | {truth} | ✓ VERIFIED | {evidence}     |
+| 2   | {truth} | ✗ FAILED   | {what's wrong} |
+
+**Score:** {N}/{M} truths verified
+
+### Required Artifacts
+
+| Artifact | Expected    | Status | Details |
+| -------- | ----------- | ------ | ------- |
+| `path`   | description | status | details |
+
+### Key Link Verification
+
+| From | To  | Via | Status | Details |
+| ---- | --- | --- | ------ | ------- |
+
+### Data-Flow Trace (Level 4)
+
+| Artifact | Data Variable | Source | Produces Real Data | Status |
+| -------- | ------------- | ------ | ------------------ | ------ |
+
+### Behavioral Spot-Checks
+
+| Behavior | Command | Result | Status |
+| -------- | ------- | ------ | ------ |
+
+### Requirements Coverage
+
+| Requirement | Source Plan | Description | Status | Evidence |
+| ----------- | ---------- | ----------- | ------ | -------- |
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+| ---- | ---- | ------- | -------- | ------ |
+
+### Human Verification Required
+
+{Items needing human testing — detailed format for user}
+
+### Gaps Summary
+
+{Narrative summary of what's missing and why}
+
+---
+
+_Verified: {timestamp}_
+_Verifier: the agent (rihal-verifier)_
+```
+
+## Return to Orchestrator
+
+**DO NOT COMMIT.** The orchestrator bundles VERIFICATION.md with other phase artifacts.
+
+Return with:
+
+```markdown
+## Verification Complete
+
+**Status:** {passed | gaps_found | human_needed}
+**Score:** {N}/{M} must-haves verified
+**Report:** .rihal/phases/{phase_dir}/{phase_num}-VERIFICATION.md
+
+{If passed:}
+All must-haves verified. Phase goal achieved. Ready to proceed.
+
+{If gaps_found:}
+### Gaps Found
+{N} gaps blocking goal achievement:
+1. **{Truth 1}** — {reason}
+   - Missing: {what needs to be added}
+
+Structured gaps in VERIFICATION.md frontmatter for `/rihal:plan --gaps`.
+
+{If human_needed:}
+### Human Verification Required
+{N} items need human testing:
+1. **{Test name}** — {what to do}
+   - Expected: {what should happen}
+
+Automated checks passed. Awaiting human verification.
+```

package/rihal/bin/lib/code-references.cjs

@@ -0,0 +1,196 @@
+/**
+ * code-references.cjs — Extract and verify file/symbol references in text.
+ *
+ * Pure Node stdlib module. No external dependencies.
+ *
+ * Usage:
+ *   const cr = require('./code-references.cjs');
+ *   const refs = cr.extractReferences(planText);
+ *   const result = cr.verifyReferences(refs, projectRoot);
+ *
+ * Exports:
+ *   - extractReferences(text) → { files, symbols, fileLines }
+ *   - verifyReferences(refs, projectRoot) → { verified, missing, summary }
+ *
+ * Detection patterns:
+ *   - Files: \b[\w/.-]+\.(py|ts|tsx|js|jsx|md|yaml|yml|json|sh|cjs|mjs|rs|go|java|rb)\b
+ *   - Symbols (snake_case): \b[a-z_][a-z0-9_]+\( → strip the (
+ *   - Symbols (CamelCase): \b[A-Z][A-Za-z0-9]+\b (filter common English words)
+ *   - File:line: \b([\w/.-]+\.\w+):(\d+)\b
+ *
+ * Verification uses fs.existsSync for files, grep for symbols.
+ * Returns summary with { total, verified, missing, ratio }.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Common English words to filter when detecting CamelCase symbols
+const COMMON_ENGLISH = new Set([
+  'The', 'A', 'An', 'And', 'Or', 'But', 'In', 'On', 'At', 'To', 'For',
+  'From', 'With', 'By', 'As', 'Is', 'Are', 'Was', 'Were', 'Be', 'Been',
+  'Have', 'Has', 'Had', 'Do', 'Does', 'Did', 'Can', 'Could', 'Will',
+  'Would', 'Should', 'May', 'Might', 'Must', 'Shall', 'If', 'Then',
+  'Else', 'Not', 'No', 'Yes', 'So', 'This', 'That', 'These', 'Those',
+  'I', 'You', 'He', 'She', 'It', 'We', 'They', 'Me', 'Him', 'Her',
+  'Us', 'Them', 'What', 'Which', 'Who', 'Whom', 'Whose', 'Where',
+  'When', 'Why', 'How', 'Get', 'Set', 'Make', 'Take', 'Put', 'Let',
+  'Call', 'Find', 'Use', 'Build', 'Create', 'Add', 'Remove', 'Delete',
+  'Update', 'Read', 'Write', 'Check', 'Verify', 'Test', 'Run', 'Start',
+  'Stop', 'Send', 'Receive', 'Process', 'Handle', 'Return', 'Export',
+  'Import', 'Module', 'Class', 'Function', 'Method', 'Property',
+  // Common markdown/documentation headers and structure
+  'Objective', 'Tasks', 'Task', 'Files', 'Action', 'Done', 'Step', 'Steps',
+  'Section', 'Sections', 'Example', 'Examples', 'Note', 'Notes', 'Warning',
+  'Warnings', 'Description', 'Descriptions', 'Process', 'Processes',
+]);
+
+/**
+ * Extract candidate file paths and symbol names from text.
+ *
+ * Returns:
+ *   {
+ *     files: [ "src/auth.ts", "package.json", ... ],
+ *     symbols: [ "handle_login", "ClassName", ... ],
+ *     fileLines: [ { file: "src/auth.ts", line: 42 }, ... ]
+ *   }
+ */
+function extractReferences(text) {
+  const files = new Set();
+  const symbols = new Set();
+  const fileLines = [];
+
+  if (!text) return { files: [], symbols: [], fileLines: [] };
+
+  // Pattern 1: Files — matches file paths with known extensions
+  // \b[\w/.-]+\.(py|ts|tsx|js|jsx|md|yaml|yml|json|sh|cjs|mjs|rs|go|java|rb)\b
+  const filePattern = /\b([\w/.-]+\.(py|ts|tsx|js|jsx|md|yaml|yml|json|sh|cjs|mjs|rs|go|java|rb))\b/gi;
+  let match;
+  while ((match = filePattern.exec(text)) !== null) {
+    files.add(match[1]);
+  }
+
+  // Pattern 2: File:line references — matches "path.ext:NN"
+  // \b([\w/.-]+\.\w+):(\d+)\b
+  const fileLinePattern = /\b([\w/.-]+\.\w+):(\d+)\b/g;
+  while ((match = fileLinePattern.exec(text)) !== null) {
+    fileLines.push({ file: match[1], line: parseInt(match[2], 10) });
+    files.add(match[1]); // also collect as a file reference
+  }
+
+  // Pattern 3: Snake_case function names — matches "function_name("
+  // \b[a-z_][a-z0-9_]+\(
+  const snakeCasePattern = /\b([a-z_][a-z0-9_]+)\(/g;
+  while ((match = snakeCasePattern.exec(text)) !== null) {
+    symbols.add(match[1]);
+  }
+
+  // Pattern 4: CamelCase class/type names (filter common words)
+  // \b[A-Z][A-Za-z0-9]+\b
+  const camelCasePattern = /\b([A-Z][A-Za-z0-9]+)\b/g;
+  while ((match = camelCasePattern.exec(text)) !== null) {
+    const word = match[1];
+    // Skip common English words, very short names, and known common types
+    if (
+      !COMMON_ENGLISH.has(word) &&
+      word.length > 2 &&
+      !['String', 'Number', 'Boolean', 'Array', 'Object', 'Error', 'Promise',
+        'Map', 'Set', 'Date', 'Math', 'Json', 'Regex', 'Node', 'Error'].includes(word)
+    ) {
+      symbols.add(word);
+    }
+  }
+
+  return {
+    files: Array.from(files),
+    symbols: Array.from(symbols),
+    fileLines: fileLines,
+  };
+}
+
+/**
+ * Verify references against the project root.
+ *
+ * Returns:
+ *   {
+ *     verified: { files: [...], symbols: [...] },
+ *     missing: { files: [...], symbols: [...] },
+ *     summary: { total: N, verified: M, missing: K, ratio: 0.X }
+ *   }
+ */
+function verifyReferences(refs, projectRoot) {
+  const verified = { files: [], symbols: [] };
+  const missing = { files: [], symbols: [] };
+
+  if (!refs || (!refs.files && !refs.symbols)) {
+    return {
+      verified,
+      missing,
+      summary: { total: 0, verified: 0, missing: 0, ratio: 1.0 },
+    };
+  }
+
+  // Verify files
+  if (refs.files && Array.isArray(refs.files)) {
+    for (const file of refs.files) {
+      const fullPath = path.join(projectRoot, file);
+      if (fs.existsSync(fullPath)) {
+        verified.files.push(file);
+      } else {
+        missing.files.push(file);
+      }
+    }
+  }
+
+  // Verify symbols — check if symbol appears in any source file
+  if (refs.symbols && Array.isArray(refs.symbols)) {
+    const verifiedSymbols = new Set();
+    const missingSymbols = new Set();
+
+    for (const symbol of refs.symbols) {
+      // Try grep to find symbol in the project
+      try {
+        // Search for the symbol as a whole word (with word boundaries)
+        // Pattern: \bsymbol\b or \bsymbol\( to catch function definitions or calls
+        const cmd = `grep -r "\\b${symbol}\\b" "${projectRoot}" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" --include="*.go" --include="*.rs" 2>/dev/null | head -1`;
+        const output = execSync(cmd, { encoding: 'utf8', stdio: 'pipe' });
+        if (output && output.trim()) {
+          verifiedSymbols.add(symbol);
+        } else {
+          missingSymbols.add(symbol);
+        }
+      } catch {
+        // grep failed or found nothing
+        missingSymbols.add(symbol);
+      }
+    }
+
+    verified.symbols = Array.from(verifiedSymbols);
+    missing.symbols = Array.from(missingSymbols);
+  }
+
+  // Calculate summary
+  const totalFiles = refs.files ? refs.files.length : 0;
+  const totalSymbols = refs.symbols ? refs.symbols.length : 0;
+  const total = totalFiles + totalSymbols;
+  const verifiedCount = verified.files.length + verified.symbols.length;
+  const missingCount = missing.files.length + missing.symbols.length;
+  const ratio = total > 0 ? verifiedCount / total : 1.0;
+
+  return {
+    verified,
+    missing,
+    summary: {
+      total,
+      verified: verifiedCount,
+      missing: missingCount,
+      ratio: Math.round(ratio * 100) / 100,
+    },
+  };
+}
+
+module.exports = {
+  extractReferences,
+  verifyReferences,
+};

package/rihal/bin/lib/config.cjs

@@ -0,0 +1,146 @@
+/**
+ * Config — dotted-path get/set for .rihal/config.yaml.
+ *
+ * Supports single-level nested YAML (e.g. `workflow:\n  discuss_mode: adaptive`)
+ * in addition to flat `key: value`. Stdlib-only.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function configPathFor(projectRoot) {
+  return path.join(projectRoot, '.rihal', 'config.yaml');
+}
+
+/** Parse YAML text into a nested object. Supports one level of indentation. */
+function parseNestedYaml(text) {
+  const out = {};
+  const lines = text.split('\n');
+  let currentSection = null;
+  for (const raw of lines) {
+    const line = raw.replace(/#.*$/, '').replace(/\s+$/, '');
+    if (!line.trim()) continue;
+
+    const indent = line.match(/^\s*/)[0].length;
+    const colonAt = line.indexOf(':');
+    if (colonAt === -1) continue;
+
+    const key = line.slice(indent, colonAt).trim();
+    let val = line.slice(colonAt + 1).trim();
+
+    if (indent === 0) {
+      if (val === '') {
+        // Section header
+        currentSection = key;
+        out[key] = {};
+      } else {
+        currentSection = null;
+        out[key] = stripQuotes(val);
+      }
+    } else if (currentSection) {
+      if (typeof out[currentSection] !== 'object' || out[currentSection] === null) {
+        out[currentSection] = {};
+      }
+      out[currentSection][key] = stripQuotes(val);
+    }
+  }
+  return out;
+}
+
+function stripQuotes(v) {
+  if (v.startsWith('"') && v.endsWith('"')) return v.slice(1, -1);
+  if (v.startsWith("'") && v.endsWith("'")) return v.slice(1, -1);
+  return v;
+}
+
+function serialise(config) {
+  const lines = [];
+  // Emit scalar keys first, then sections (mimics common YAML convention).
+  const scalars = [];
+  const sections = [];
+  for (const [k, v] of Object.entries(config)) {
+    if (v && typeof v === 'object' && !Array.isArray(v)) sections.push([k, v]);
+    else scalars.push([k, v]);
+  }
+  for (const [k, v] of scalars) {
+    lines.push(`${k}: ${quoteIfNeeded(v)}`);
+  }
+  for (const [k, v] of sections) {
+    lines.push(`${k}:`);
+    for (const [sk, sv] of Object.entries(v)) {
+      lines.push(`  ${sk}: ${quoteIfNeeded(sv)}`);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+function quoteIfNeeded(v) {
+  if (v === null || v === undefined) return '';
+  const s = String(v);
+  if (/[\s:#]/.test(s) && !(s.startsWith('"') && s.endsWith('"'))) {
+    return `"${s.replace(/"/g, '\\"')}"`;
+  }
+  return s;
+}
+
+function getAt(config, dottedKey) {
+  const parts = String(dottedKey).split('.');
+  let cur = config;
+  for (const p of parts) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+function setAt(config, dottedKey, value) {
+  const parts = String(dottedKey).split('.');
+  let cur = config;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const p = parts[i];
+    if (typeof cur[p] !== 'object' || cur[p] === null || Array.isArray(cur[p])) {
+      cur[p] = {};
+    }
+    cur = cur[p];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+
+/**
+ * config-get <dotted.key>
+ * Prints scalar directly (no JSON). Empty output + exit 0 if missing.
+ * Returns a string (or null for missing) the caller should print with console.log
+ * WITHOUT JSON-wrapping.
+ */
+function cmdGet(projectRoot, dottedKey) {
+  if (!dottedKey) throw new Error('Usage: config-get <dotted.key>');
+  const cp = configPathFor(projectRoot);
+  if (!fs.existsSync(cp)) return null;
+  const config = parseNestedYaml(fs.readFileSync(cp, 'utf8'));
+  const val = getAt(config, dottedKey);
+  if (val === undefined || val === null) return null;
+  if (typeof val === 'object') return JSON.stringify(val);
+  return String(val);
+}
+
+function cmdSet(projectRoot, dottedKey, value) {
+  if (!dottedKey) throw new Error('Usage: config-set <dotted.key> <value>');
+  if (value === undefined) throw new Error('Usage: config-set <dotted.key> <value>');
+  const cp = configPathFor(projectRoot);
+  fs.mkdirSync(path.dirname(cp), { recursive: true });
+  const existing = fs.existsSync(cp) ? fs.readFileSync(cp, 'utf8') : '';
+  const config = parseNestedYaml(existing);
+  setAt(config, dottedKey, value);
+  const out = serialise(config);
+  const tmp = cp + '.tmp';
+  fs.writeFileSync(tmp, out, 'utf8');
+  fs.renameSync(tmp, cp);
+  return { ok: true, key: dottedKey, value, path: cp };
+}
+
+module.exports = {
+  cmdGet,
+  cmdSet,
+  parseNestedYaml,
+  serialise,
+};