@lifeaitools/rdc-skills 0.9.33 → 0.9.35

package/guides/agents/verify.md

@@ -1,38 +1,38 @@
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
-> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
-
-
-# rdc:verify — Verification Before Completion
-
-> Adapted from obra/superpowers `verification-before-completion`.
-> Stack-specific: uses `npx vitest run` + `npx tsc --noEmit`. NEVER `pnpm build` (crashes machine — 800MB/process).
-
-## The Iron Law
-
-**NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.**
-
-You may not say "done", "complete", "working", "fixed", "passing", or imply success until you have:
-
-1. **Identified** the exact commands that prove the claim
-2. **Run** those commands fresh in the current state (not memory, not "earlier", not "should")
-3. **Read** the full output
-4. **Verified** the output matches the claim
-5. Only THEN made the claim, quoting the evidence
-
-If you cannot run the commands, say so explicitly. Do not substitute reasoning for evidence.
-
-## Red Flags — Stop and Verify
-
-If you're about to write any of these, STOP:
-
-- "should work" / "should pass" / "should be fine"
-- "probably" / "seems to" / "looks good"
-- "I think the tests pass"
-- "the types check out" (without running tsc)
-- "everything compiles" (without fresh output)
-- Expressing satisfaction or wrapping up before the gate ran
-
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+
+# rdc:verify — Verification Before Completion
+
+> Adapted from obra/superpowers `verification-before-completion`.
+> Stack-specific: uses `npx vitest run` + `npx tsc --noEmit`. NEVER `pnpm build` (crashes machine — 800MB/process).
+
+## The Iron Law
+
+**NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.**
+
+You may not say "done", "complete", "working", "fixed", "passing", or imply success until you have:
+
+1. **Identified** the exact commands that prove the claim
+2. **Run** those commands fresh in the current state (not memory, not "earlier", not "should")
+3. **Read** the full output
+4. **Verified** the output matches the claim
+5. Only THEN made the claim, quoting the evidence
+
+If you cannot run the commands, say so explicitly. Do not substitute reasoning for evidence.
+
+## Red Flags — Stop and Verify
+
+If you're about to write any of these, STOP:
+
+- "should work" / "should pass" / "should be fine"
+- "probably" / "seems to" / "looks good"
+- "I think the tests pass"
+- "the types check out" (without running tsc)
+- "everything compiles" (without fresh output)
+- Expressing satisfaction or wrapping up before the gate ran
+
 ## The Gate — Commands for This Stack
 
 Run these in order. All must pass. Capture output.
@@ -55,97 +55,97 @@ Required work item evidence:
 If this check fails, stop validation for that item and reopen it. Do not mark a work item `done` when the checklist itself is not decomposed enough to prove completion.
 
 ### 1. Per-package vitest (every package touched)
-
-```bash
-cd <repo-root>
-for pkg in <changed-packages>; do
-  npx vitest run --dir packages/$pkg 2>&1 | tee /tmp/verify-$pkg.log
-done
-```
-
-Or for a single package:
-```bash
-npx vitest run --dir packages/<pkg>
-npx vitest run --dir apps/<app>
-```
-
-**NEVER** run `pnpm build` or `pnpm test` at the repo root — spawns 5-7 node processes at 800MB each and crashes the machine.
-
-### 2. Typecheck per package
-
-```bash
-npx tsc --noEmit --project packages/<pkg>/tsconfig.json
-npx tsc --noEmit --project apps/<app>/tsconfig.json
-```
-
-One package at a time. Read the full output — zero errors required.
-
-### 3. Lint (if configured for the package)
-
-```bash
-npx eslint <paths> --max-warnings=0
-```
-
-### 4. Smoke check exports (if package adds public API)
-
-```bash
-node -e "const m = require('<pkg>'); console.log(Object.keys(m));"
-```
-
-Or for ESM:
-```bash
-node --input-type=module -e "import * as m from '<pkg>'; console.log(Object.keys(m));"
-```
-
-## Rationalization Prevention
-
-| You're tempted to think... | Reality |
-|---|---|
-| "Tests passed earlier, should still pass" | Run them now. Code changed. |
-| "TypeScript is strict, if it built it works" | You didn't build. Run tsc. |
-| "Small change, no need to retest" | Small changes are where regressions hide. |
-| "I'll note it as pending verification" | No. Verify now or mark incomplete. |
-| "The test file looks right" | Reading ≠ running. Run it. |
-
-## Output Format — Required
-
-When reporting completion, use this structure:
-
-```
-## Verification Evidence
-
-### vitest
-$ npx vitest run --dir packages/hail
- Test Files  12 passed (12)
-      Tests  147 passed (147)
-
-### tsc
-$ npx tsc --noEmit --project packages/hail/tsconfig.json
-(no output — clean)
-
+
+```bash
+cd <repo-root>
+for pkg in <changed-packages>; do
+  npx vitest run --dir packages/$pkg 2>&1 | tee /tmp/verify-$pkg.log
+done
+```
+
+Or for a single package:
+```bash
+npx vitest run --dir packages/<pkg>
+npx vitest run --dir apps/<app>
+```
+
+**NEVER** run `pnpm build` or `pnpm test` at the repo root — spawns 5-7 node processes at 800MB each and crashes the machine.
+
+### 2. Typecheck per package
+
+```bash
+npx tsc --noEmit --project packages/<pkg>/tsconfig.json
+npx tsc --noEmit --project apps/<app>/tsconfig.json
+```
+
+One package at a time. Read the full output — zero errors required.
+
+### 3. Lint (if configured for the package)
+
+```bash
+npx eslint <paths> --max-warnings=0
+```
+
+### 4. Smoke check exports (if package adds public API)
+
+```bash
+node -e "const m = require('<pkg>'); console.log(Object.keys(m));"
+```
+
+Or for ESM:
+```bash
+node --input-type=module -e "import * as m from '<pkg>'; console.log(Object.keys(m));"
+```
+
+## Rationalization Prevention
+
+| You're tempted to think... | Reality |
+|---|---|
+| "Tests passed earlier, should still pass" | Run them now. Code changed. |
+| "TypeScript is strict, if it built it works" | You didn't build. Run tsc. |
+| "Small change, no need to retest" | Small changes are where regressions hide. |
+| "I'll note it as pending verification" | No. Verify now or mark incomplete. |
+| "The test file looks right" | Reading ≠ running. Run it. |
+
+## Output Format — Required
+
+When reporting completion, use this structure:
+
+```
+## Verification Evidence
+
+### vitest
+$ npx vitest run --dir packages/hail
+ Test Files  12 passed (12)
+      Tests  147 passed (147)
+
+### tsc
+$ npx tsc --noEmit --project packages/hail/tsconfig.json
+(no output — clean)
+
 ### Status
 Checklist quality: PASS
 PASS — safe to mark tasks done.
 ```
 
 If any step fails: do NOT claim completion. Report the failure, fix it, re-run the entire gate.
-
-## When to Invoke
-
-- **End of `/rdc:build`** — mandatory final phase before marking epic done
-- **During `/rdc:review`** — verification gate after fixes applied
-- **Before any "done" declaration** — if an agent or supervisor is about to say work is complete
-- **After merging waves** — when parallel agents finish and their work is combined
-
-## Agent Delegation
-
-When dispatching a verification agent, give them:
-- Exact list of packages/apps to verify
+
+## When to Invoke
+
+- **End of `/rdc:build`** — mandatory final phase before marking epic done
+- **During `/rdc:review`** — verification gate after fixes applied
+- **Before any "done" declaration** — if an agent or supervisor is about to say work is complete
+- **After merging waves** — when parallel agents finish and their work is combined
+
+## Agent Delegation
+
+When dispatching a verification agent, give them:
+- Exact list of packages/apps to verify
 - Explicit ban on `pnpm build` / `pnpm test` / `pnpm -r`
 - Work item checklists and the matching plan doc so `decomp-*` quality can be verified first
 - Required output format (above)
 - Instruction: "If any command fails, STOP and report. Do not fix. Do not continue."
-
-## The Bottom Line
-
-Evidence before claims. Fresh evidence, not remembered evidence. Full output, not selective reading. If you skip the gate, you are lying about the work being done.
+
+## The Bottom Line
+
+Evidence before claims. Fresh evidence, not remembered evidence. Full output, not selective reading. If you skip the gate, you are lying about the work being done.

package/guides/agents/viz.md

@@ -1,106 +1,106 @@
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
-> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
-
-> If dispatching subagents or running as a subagent: read `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md` first (fallback: `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md`).
-
-
-# rdc:viz — Visualization Agent
-
-## Mandatory First Steps
-
-Read BOTH guides before ANY code:
-```
-{PROJECT_ROOT}/.rdc/guides/frontend.md (fallback: {PROJECT_ROOT}/.rdc/guides/frontend.md)
-{PROJECT_ROOT}/.rdc/guides/design.md (fallback: {PROJECT_ROOT}/.rdc/guides/design.md)
-```
-
-## Before Writing Any Code
-
-1. **Check for existing prototypes:**
-   ```sql
-   SELECT name, component, source_path, status, notes
-   FROM prototype_registry
-   WHERE status IN ('prototype', 'converting')
-   ORDER BY created_at DESC;
-   ```
-   Source path is usually `docs/source/`. **Read it first.**
-
-2. **Check design decisions:**
-   ```sql
-   SELECT topic, summary FROM design_context
-   WHERE topic ILIKE '%<viz-name>%';
-   ```
-
-## SVG Layout Patterns
-
-When building new SVG-based viz:
-- Define all layout constants at top (`W`, `H`, column x-centers, box dimensions)
-- Build path builders as pure functions
-- Separate data from rendering
-- Use `viewBox` for responsive scaling
-- Animate with appropriate motion libraries
-
-```tsx
-const W = 980, H = 570;
-const COL_A = 80, COL_B = 240, COL_C = 435;
-
-function pathTo(x1: number, y1: number, x2: number, y2: number): string {
-  const mx = (x1 + x2) / 2;
-  return `M ${x1} ${y1} C ${mx} ${y1} ${mx} ${y2} ${x2} ${y2}`;
-}
-```
-
-## Viz Component Contract
-
-```tsx
-"use client";
-import * as React from "react";
-import { cva, type VariantProps } from "class-variance-authority";
-import { cn } from "../lib/utils";
-
-// CVA variants required on every new viz component
-const myVizVariants = cva("relative w-full", {
-  variants: {
-    layout: { single: "", double: "flex flex-col", grid: "" },
-    density: { compact: "", comfortable: "", spacious: "" },
-  },
-  defaultVariants: { layout: "single", density: "comfortable" },
-});
-
-interface MyVizProps
-  extends React.HTMLAttributes<HTMLDivElement>,
-    VariantProps<typeof myVizVariants> {}
-
-const MyViz = React.forwardRef<HTMLDivElement, MyVizProps>(
-  ({ className, layout, density, ...props }, ref) => (
-    <div ref={ref} className={cn(myVizVariants({ layout, density }), className)} {...props} />
-  )
-);
-MyViz.displayName = "MyViz";
-export { MyViz, myVizVariants };
-```
-
-Export from package's index after building.
-
-## Registering New Viz Components
-
-After completing:
-```sql
-INSERT INTO prototype_registry (name, component, source_path, notes, created_by)
-VALUES (
-  'MyViz v1.0',
-  'MyViz',
-  'packages/ui/src/components/my-viz.tsx',
-  'Production component. Props: <list key props>',
-  'agent'
-);
-```
-
-## Safety Rules
-
-- Branch: development branch — auto-commit
-- NEVER run `pnpm build`
-- Reduce motion: always wrap animations with appropriate hooks
-- NEVER overlap with other agents on the same component file
-- Write tests FIRST — red → implement → green
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+> If dispatching subagents or running as a subagent: read `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md` first (fallback: `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md`).
+
+
+# rdc:viz — Visualization Agent
+
+## Mandatory First Steps
+
+Read BOTH guides before ANY code:
+```
+{PROJECT_ROOT}/.rdc/guides/frontend.md (fallback: {PROJECT_ROOT}/.rdc/guides/frontend.md)
+{PROJECT_ROOT}/.rdc/guides/design.md (fallback: {PROJECT_ROOT}/.rdc/guides/design.md)
+```
+
+## Before Writing Any Code
+
+1. **Check for existing prototypes:**
+   ```sql
+   SELECT name, component, source_path, status, notes
+   FROM prototype_registry
+   WHERE status IN ('prototype', 'converting')
+   ORDER BY created_at DESC;
+   ```
+   Source path is usually `docs/source/`. **Read it first.**
+
+2. **Check design decisions:**
+   ```sql
+   SELECT topic, summary FROM design_context
+   WHERE topic ILIKE '%<viz-name>%';
+   ```
+
+## SVG Layout Patterns
+
+When building new SVG-based viz:
+- Define all layout constants at top (`W`, `H`, column x-centers, box dimensions)
+- Build path builders as pure functions
+- Separate data from rendering
+- Use `viewBox` for responsive scaling
+- Animate with appropriate motion libraries
+
+```tsx
+const W = 980, H = 570;
+const COL_A = 80, COL_B = 240, COL_C = 435;
+
+function pathTo(x1: number, y1: number, x2: number, y2: number): string {
+  const mx = (x1 + x2) / 2;
+  return `M ${x1} ${y1} C ${mx} ${y1} ${mx} ${y2} ${x2} ${y2}`;
+}
+```
+
+## Viz Component Contract
+
+```tsx
+"use client";
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../lib/utils";
+
+// CVA variants required on every new viz component
+const myVizVariants = cva("relative w-full", {
+  variants: {
+    layout: { single: "", double: "flex flex-col", grid: "" },
+    density: { compact: "", comfortable: "", spacious: "" },
+  },
+  defaultVariants: { layout: "single", density: "comfortable" },
+});
+
+interface MyVizProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof myVizVariants> {}
+
+const MyViz = React.forwardRef<HTMLDivElement, MyVizProps>(
+  ({ className, layout, density, ...props }, ref) => (
+    <div ref={ref} className={cn(myVizVariants({ layout, density }), className)} {...props} />
+  )
+);
+MyViz.displayName = "MyViz";
+export { MyViz, myVizVariants };
+```
+
+Export from package's index after building.
+
+## Registering New Viz Components
+
+After completing:
+```sql
+INSERT INTO prototype_registry (name, component, source_path, notes, created_by)
+VALUES (
+  'MyViz v1.0',
+  'MyViz',
+  'packages/ui/src/components/my-viz.tsx',
+  'Production component. Props: <list key props>',
+  'agent'
+);
+```
+
+## Safety Rules
+
+- Branch: development branch — auto-commit
+- NEVER run `pnpm build`
+- Reduce motion: always wrap animations with appropriate hooks
+- NEVER overlap with other agents on the same component file
+- Write tests FIRST — red → implement → green

package/guides/engineering-behavior.md

@@ -0,0 +1,43 @@
+# Engineering Behavior
+
+Use this with `agent-bootstrap.md` for implementation and review work. These
+rules adapt general coding-agent hygiene into the RDC work-item contract.
+
+## Before Editing
+
+- State material assumptions in the work-item report; ask or block when the
+  ambiguity changes architecture, data shape, security, or user-visible scope.
+- Prefer the smallest change that satisfies the assigned checklist rows.
+- Do not add features, abstractions, configurability, or fallback behavior that
+  is not required by the work item.
+- If a simpler path exists than the apparent request, report the tradeoff before
+  widening the implementation.
+
+## While Editing
+
+- Stay inside the assigned files, package, route, or work-item boundary.
+- Match the local style and contracts already in the touched files.
+- Do not reformat, rename, or refactor adjacent code unless the checklist row
+  explicitly requires it.
+- Clean up only the unused imports, variables, files, or branches created by
+  your own change.
+- If existing code looks dead or wrong but is outside scope, list it as a
+  blocker or follow-up. Do not remove it.
+
+## Verification
+
+- Every completed row needs evidence: test output, route probe, SQL result,
+  screenshot artifact, type-check output, CLI transcript, or reviewer citation.
+- Finding an existing file is not evidence. Verify the required behavior.
+- Tick each `decomp-*` and `test-*` checklist item immediately after proving
+  that exact behavior. Do not batch ticks at the end.
+- Record assumptions, deviations, uncertainty, blockers, files changed, and
+  verification in `submit_implementation_report()` before moving to `review`.
+
+## Escalation
+
+- Stop and report `BLOCKED` when the fix requires files outside scope, a broader
+  architectural choice, a missing credential, or a second repeated failure.
+- In unattended mode, choose the most conservative valid path only when the
+  acceptance criteria remain unchanged; otherwise escalate through the advisor
+  path required by the active skill.

package/hooks/rdc-invocation-marker.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * UserPromptExpansion/UserPromptSubmit hook — mark active rdc:* invocations.
+ *
+ * This does not enforce compliance. It primes the turn with the RDC contract
+ * and leaves a session marker for rdc-output-contract-gate.js to enforce at
+ * Stop time.
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const hookLog = require('./hook-logger');
+
+const RDC_COMMANDS = new Set([
+  'build',
+  'co-develop',
+  'collab',
+  'deploy',
+  'design',
+  'fixit',
+  'fs-mcp',
+  'handoff',
+  'help',
+  'overnight',
+  'plan',
+  'preplan',
+  'prototype',
+  'release',
+  'report',
+  'review',
+  'self-test',
+  'status',
+  'terminal-config',
+  'watch',
+  'workitems',
+]);
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => resolve(input));
+    process.stdin.resume();
+  });
+}
+
+function markerDir() {
+  return path.join(os.homedir(), '.claude', 'rdc-active');
+}
+
+function markerPath(sessionId) {
+  const safe = String(sessionId || 'unknown').replace(/[^a-zA-Z0-9_.-]/g, '_');
+  return path.join(markerDir(), `${safe}.json`);
+}
+
+function normalizeCommandName(value) {
+  return String(value || '')
+    .trim()
+    .replace(/^\/+/, '')
+    .replace(/^rdc[:-]/i, '')
+    .toLowerCase();
+}
+
+function detectRdc(raw) {
+  const event = raw.hook_event_name || '';
+  if (event === 'UserPromptExpansion') {
+    if (raw.command_source && raw.command_source !== 'plugin') return null;
+    const command = normalizeCommandName(raw.command_name);
+    if (command === 'help' && !/^\/rdc[:-]help\b/i.test(String(raw.prompt || ''))) return null;
+    if (RDC_COMMANDS.has(command)) return command;
+    return null;
+  }
+
+  if (event === 'UserPromptSubmit') {
+    const prompt = String(raw.prompt || '').trim();
+    const m = prompt.match(/^\/(?:rdc[:-])?([a-z][a-z0-9-]*)\b/i);
+    if (!m) return null;
+    const command = normalizeCommandName(m[1]);
+    if (RDC_COMMANDS.has(command)) return command;
+  }
+
+  return null;
+}
+
+function writeMarker(raw, command) {
+  fs.mkdirSync(markerDir(), { recursive: true });
+  const marker = {
+    session_id: raw.session_id || null,
+    command,
+    command_name: raw.command_name || null,
+    command_args: raw.command_args || null,
+    prompt: raw.prompt || null,
+    cwd: raw.cwd || null,
+    transcript_path: raw.transcript_path || null,
+    started_at: new Date().toISOString(),
+    hook_event_name: raw.hook_event_name || null,
+  };
+  fs.writeFileSync(markerPath(raw.session_id), JSON.stringify(marker, null, 2));
+  return marker;
+}
+
+function outputContext(eventName, command) {
+  const additionalContext = [
+    `RDC CONTRACT ACTIVE for /${command}.`,
+    'Before responding, follow the project-local guide contracts:',
+    '- .rdc/guides/output-contract.md: show one checklist for this invocation, update it as work progresses, and end with the required verdict line.',
+    '- .rdc/guides/engineering-behavior.md: assumptions, scope, evidence, deviations, blockers, and verification must be explicit.',
+    'Runtime enforcement is on emitted artifacts: the final assistant message must contain at least one checklist row and a verdict line.',
+  ].join('\n');
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      additionalContext,
+    },
+  }));
+}
+
+async function main() {
+  let raw;
+  try { raw = JSON.parse(await readStdin()); } catch { process.exit(0); }
+  const command = detectRdc(raw);
+  if (!command) process.exit(0);
+
+  try {
+    const marker = writeMarker(raw, command);
+    hookLog('rdc-invocation-marker', raw.hook_event_name || 'unknown', 'marked', {
+      command,
+      session_id: marker.session_id,
+    });
+    outputContext(raw.hook_event_name || 'UserPromptExpansion', command);
+  } catch (e) {
+    hookLog('rdc-invocation-marker', raw.hook_event_name || 'unknown', 'error', {
+      command,
+      error: e.message,
+    });
+  }
+}
+
+main().catch(() => process.exit(0));