@wazir-dev/cli 1.2.0 → 1.4.0

package/tooling/src/verify/proof-collector.js

@@ -0,0 +1,299 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const WEB_FRAMEWORKS = ['next', 'vite', 'react-scripts', '@angular/cli', 'nuxt', 'astro', 'gatsby'];
+const API_FRAMEWORKS = ['express', 'fastify', 'hono', 'koa', '@nestjs/core', '@hapi/hapi'];
+
+/**
+ * Detect whether a project produces runnable output and what type.
+ *
+ * @param {string} projectRoot
+ * @returns {'web' | 'api' | 'cli' | 'library'}
+ */
+export function detectRunnableType(projectRoot) {
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(pkgPath)) return 'library';
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  } catch {
+    return 'library';
+  }
+
+  const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  if (WEB_FRAMEWORKS.some((fw) => fw in allDeps)) return 'web';
+  if (API_FRAMEWORKS.some((fw) => fw in allDeps)) return 'api';
+  if (pkg.bin) return 'cli';
+
+  return 'library';
+}
+
+/**
+ * Run a command safely using execFileSync (no shell injection).
+ *
+ * @param {string} cmd - The executable
+ * @param {string[]} args - Arguments array
+ * @param {string} cwd
+ * @returns {{ exit_code: number, stdout: string, stderr: string }}
+ */
+function runCommand(cmd, args, cwd) {
+  try {
+    const stdout = execFileSync(cmd, args, {
+      cwd,
+      encoding: 'utf8',
+      timeout: 60000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return { exit_code: 0, stdout: stdout.trim(), stderr: '' };
+  } catch (err) {
+    return {
+      exit_code: err.status ?? 1,
+      stdout: (err.stdout ?? '').trim(),
+      stderr: (err.stderr ?? '').trim(),
+    };
+  }
+}
+
+/**
+ * Summarize command output to a short string.
+ *
+ * @param {string} stdout
+ * @param {number} maxLen
+ * @returns {string}
+ */
+function summarize(stdout, maxLen = 200) {
+  if (!stdout) return '';
+  const lines = stdout.split('\n');
+  if (lines.length <= 5) return stdout.slice(0, maxLen);
+  return [...lines.slice(0, 3), `... (${lines.length} lines total)`, ...lines.slice(-2)]
+    .join('\n')
+    .slice(0, maxLen);
+}
+
+/**
+ * Check if a package.json has a specific script.
+ *
+ * @param {string} projectRoot
+ * @param {string} scriptName
+ * @returns {boolean}
+ */
+function hasScript(projectRoot, scriptName) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
+    return !!(pkg.scripts && pkg.scripts[scriptName]);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a config file exists for a tool.
+ *
+ * @param {string} projectRoot
+ * @param {string[]} candidates
+ * @returns {boolean}
+ */
+function hasConfigFile(projectRoot, candidates) {
+  return candidates.some((f) => fs.existsSync(path.join(projectRoot, f)));
+}
+
+/**
+ * Collect library-type proof: tests, lint, format, type-check.
+ *
+ * @param {string} projectRoot
+ * @returns {{ tool: string, command: string, exit_code: number, stdout_summary: string, passed: boolean }[]}
+ */
+function collectLibraryEvidence(projectRoot) {
+  const evidence = [];
+
+  // npm test
+  if (hasScript(projectRoot, 'test')) {
+    const result = runCommand('npm', ['test'], projectRoot);
+    evidence.push({
+      tool: 'npm test',
+      command: 'npm test',
+      exit_code: result.exit_code,
+      stdout_summary: summarize(result.stdout),
+      passed: result.exit_code === 0,
+    });
+  }
+
+  // TypeScript type check
+  if (
+    hasConfigFile(projectRoot, ['tsconfig.json']) ||
+    hasScript(projectRoot, 'typecheck')
+  ) {
+    const cmd = hasScript(projectRoot, 'typecheck')
+      ? ['npm', ['run', 'typecheck']]
+      : ['npx', ['tsc', '--noEmit']];
+    const result = runCommand(cmd[0], cmd[1], projectRoot);
+    evidence.push({
+      tool: 'tsc',
+      command: cmd[0] + ' ' + cmd[1].join(' '),
+      exit_code: result.exit_code,
+      stdout_summary: summarize(result.exit_code === 0 ? 'No type errors' : result.stdout || result.stderr),
+      passed: result.exit_code === 0,
+    });
+  }
+
+  // ESLint
+  if (
+    hasConfigFile(projectRoot, ['.eslintrc', '.eslintrc.js', '.eslintrc.json', '.eslintrc.yml', 'eslint.config.js', 'eslint.config.mjs']) ||
+    hasScript(projectRoot, 'lint')
+  ) {
+    const cmd = hasScript(projectRoot, 'lint')
+      ? ['npm', ['run', 'lint']]
+      : ['npx', ['eslint', '.']];
+    const result = runCommand(cmd[0], cmd[1], projectRoot);
+    evidence.push({
+      tool: 'eslint',
+      command: cmd[0] + ' ' + cmd[1].join(' '),
+      exit_code: result.exit_code,
+      stdout_summary: summarize(result.exit_code === 0 ? 'No lint errors' : result.stdout || result.stderr),
+      passed: result.exit_code === 0,
+    });
+  }
+
+  // Prettier
+  if (
+    hasConfigFile(projectRoot, ['.prettierrc', '.prettierrc.js', '.prettierrc.json', '.prettierrc.yml', 'prettier.config.js', 'prettier.config.mjs']) ||
+    hasScript(projectRoot, 'format:check')
+  ) {
+    const cmd = hasScript(projectRoot, 'format:check')
+      ? ['npm', ['run', 'format:check']]
+      : ['npx', ['prettier', '--check', '.']];
+    const result = runCommand(cmd[0], cmd[1], projectRoot);
+    evidence.push({
+      tool: 'prettier',
+      command: cmd[0] + ' ' + cmd[1].join(' '),
+      exit_code: result.exit_code,
+      stdout_summary: summarize(result.exit_code === 0 ? 'All files formatted' : result.stdout || result.stderr),
+      passed: result.exit_code === 0,
+    });
+  }
+
+  return evidence;
+}
+
+/**
+ * Collect web-type proof: build + library checks.
+ *
+ * @param {string} projectRoot
+ * @returns {{ tool: string, command: string, exit_code: number, stdout_summary: string, passed: boolean }[]}
+ */
+function collectWebEvidence(projectRoot) {
+  const evidence = [];
+
+  // Build
+  if (hasScript(projectRoot, 'build')) {
+    const result = runCommand('npm', ['run', 'build'], projectRoot);
+    evidence.push({
+      tool: 'build',
+      command: 'npm run build',
+      exit_code: result.exit_code,
+      stdout_summary: summarize(result.stdout),
+      passed: result.exit_code === 0,
+    });
+  }
+
+  // Also run library checks (tests, lint, etc.)
+  evidence.push(...collectLibraryEvidence(projectRoot));
+
+  return evidence;
+}
+
+/**
+ * Collect API-type proof: library checks (server start/stop is complex, defer to manual).
+ *
+ * @param {string} projectRoot
+ * @returns {{ tool: string, command: string, exit_code: number, stdout_summary: string, passed: boolean }[]}
+ */
+function collectApiEvidence(projectRoot) {
+  return collectLibraryEvidence(projectRoot);
+}
+
+/**
+ * Collect CLI-type proof: --help output + library checks.
+ *
+ * @param {string} projectRoot
+ * @returns {{ tool: string, command: string, exit_code: number, stdout_summary: string, passed: boolean }[]}
+ */
+function collectCliEvidence(projectRoot) {
+  const evidence = [];
+
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
+    const binEntry = typeof pkg.bin === 'string' ? pkg.bin : Object.values(pkg.bin || {})[0];
+    if (binEntry) {
+      const binPath = path.join(projectRoot, binEntry);
+      if (fs.existsSync(binPath)) {
+        const result = runCommand('node', [binPath, '--help'], projectRoot);
+        evidence.push({
+          tool: 'cli --help',
+          command: `node ${binEntry} --help`,
+          exit_code: result.exit_code,
+          stdout_summary: summarize(result.stdout),
+          passed: result.exit_code === 0,
+        });
+      }
+    }
+  } catch { /* ignore */ }
+
+  evidence.push(...collectLibraryEvidence(projectRoot));
+
+  return evidence;
+}
+
+/**
+ * Collect proof of implementation for a task.
+ *
+ * @param {{ id: string, title: string }} taskSpec
+ * @param {{ projectRoot: string, runId?: string, stateRoot?: string }} runConfig
+ * @returns {Promise<{ task_id: string, type: string, timestamp: string, evidence: object[], status: string, all_passed: boolean }>}
+ */
+export async function collectProof(taskSpec, runConfig) {
+  const { projectRoot } = runConfig;
+  const type = detectRunnableType(projectRoot);
+
+  let evidence;
+  switch (type) {
+    case 'web':
+      evidence = collectWebEvidence(projectRoot);
+      break;
+    case 'api':
+      evidence = collectApiEvidence(projectRoot);
+      break;
+    case 'cli':
+      evidence = collectCliEvidence(projectRoot);
+      break;
+    default:
+      evidence = collectLibraryEvidence(projectRoot);
+  }
+
+  const allPassed = evidence.length === 0 || evidence.every((e) => e.passed);
+
+  const result = {
+    task_id: taskSpec.id,
+    type,
+    timestamp: new Date().toISOString(),
+    evidence,
+    status: allPassed ? 'pass' : 'fail',
+    all_passed: allPassed,
+  };
+
+  // Save to artifacts if runId provided
+  if (runConfig.runId && runConfig.stateRoot) {
+    const artifactDir = path.join(runConfig.stateRoot, 'runs', runConfig.runId, 'artifacts');
+    if (fs.existsSync(artifactDir)) {
+      fs.writeFileSync(
+        path.join(artifactDir, `proof-${taskSpec.id}.json`),
+        JSON.stringify(result, null, 2) + '\n',
+      );
+    }
+  }
+
+  return result;
+}

package/wazir.manifest.yaml

@@ -97,6 +97,9 @@ required_hooks:
   - protected_path_write_guard
   - loop_cap_guard
   - context_mode_router
+  - stop_pipeline_gate
+  - pretooluse_pipeline_guard
+  - pretooluse_dispatcher
 protected_paths:
   - input
   - roles

package/workflows/learn.md

@@ -2,37 +2,90 @@
 
 ## Purpose
 
-Extract durable scoped learnings and experiments from the completed run.
+Extract durable scoped learnings from the completed run using the 4-stage promotion pipeline.
 
 ## Phase entry
 
 On entering this phase, run:
-`wazir capture event --run <run-id> --event phase_enter --phase <phase-name> --status in_progress`
+`wazir capture event --run <run-id> --event phase_enter --phase learn --status in_progress`
 
 ## Inputs
 
 - run artifacts
-- review findings
+- review findings (all passes, all tiers)
 - verification proof
 
 ## Primary Role
 
 - `learner`
 
+## Pipeline Stages
+
+The learning pipeline follows a 4-stage promotion model (Tally → Candidate → Promote → Active):
+
+### Stage 1: TALLY (Automatic)
+
+Every finding from the run is:
+1. Canonicalized (file paths, line numbers, identifiers stripped)
+2. Hashed for dedup
+3. Clustered by semantic similarity in `finding_clusters` table
+4. Category-tagged (from the reviewer's finding category)
+
+Also:
+- Read `.wazir/runs/<id>/decisions.ndjson` for recurring patterns
+- Append summary to `memory/findings/cumulative-findings.md`
+
+Implementation: `tooling/src/learn/pipeline.js` → `tallyFinding()`
+
+### Stage 2: CANDIDATE (Automatic)
+
+Clusters meeting the promotion threshold are flagged:
+- **Occurrence threshold:** 3+ findings with the same canonical pattern
+- **Run threshold:** Pattern must appear across 2+ distinct runs
+- **Drift cap:** No promotion if active antipatterns count >= 30
+
+Implementation: `tooling/src/learn/pipeline.js` → `identifyCandidates()` + `promoteToCandidates()`
+
+### Stage 3: PROMOTE (Human Gate)
+
+Candidates are proposed for user review:
+- Written to `memory/learnings/proposed/<run-id>-<NNN>.md`
+- User reviews and accepts/rejects via `/wazir audit learnings`
+- Accepted candidates move to `status: accepted` in `antipattern_candidates` table
+
+### Stage 4: ACTIVE (Automatic)
+
+Accepted antipatterns are loaded into reviewer context for future runs:
+- Injected as project-level learnings alongside expertise modules
+- Hit-rate tracked: if an antipattern triggers in <5% of runs over 90 days, it's demoted
+- Max 30 active project-level antipatterns (drift prevention)
+
+## Drift Prevention
+
+- **Cap:** 30 active project antipatterns maximum
+- **TTL:** 90-day expiry on unreviewed candidates
+- **Demotion:** Antipatterns with <5% hit rate over 90 days are auto-demoted
+- **Consolidation:** When count exceeds 25, similar antipatterns are merged
+
 ## Outputs
 
-- proposed learning artifacts
-- experiment summaries
+- Tallied findings in `finding_clusters` table
+- Promoted candidates in `antipattern_candidates` table
+- Proposed learning artifacts in `memory/learnings/proposed/`
+- Cumulative findings appended to `memory/findings/cumulative-findings.md`
 
 ## Approval Gate
 
-- accepted learnings require explicit review and scope tags
+- Accepted learnings require explicit user review and scope tags
+- Learnings are NEVER auto-applied to future runs without user acceptance
 
 ## Phase exit
 
 On completing this phase, run:
-`wazir capture event --run <run-id> --event phase_exit --phase <phase-name> --status completed`
+`wazir capture event --run <run-id> --event phase_exit --phase learn --status completed`
 
 ## Failure Conditions
 
-- auto-applied learning drift
+- auto-applied learning drift (bypassing human gate)
+- candidate count exceeds cap without consolidation
+- stale candidates not expired

package/workflows/plan-review.md

@@ -39,7 +39,9 @@ On completing this phase, run:
 
 ## Loop Structure
 
-Follows the review loop pattern in `docs/reference/review-loop-pattern.md` with plan dimensions. The planner role resolves findings. Pass count determined by depth. No extension.
+Follows the review loop pattern in `docs/reference/review-loop-pattern.md` with 8 plan dimensions (including Input Coverage). The planner role resolves findings. Pass count determined by depth. No extension.
+
+**Input Coverage dimension:** The reviewer reads the original input/briefing, counts distinct items, and compares against tasks in the plan. If `tasks_in_plan < items_in_input`, this is a HIGH finding listing the missing items. This prevents silent scope reduction where 21 input items become 5 tasks.
 
 ## Failure Conditions
 

package/workflows/verify.md

@@ -14,6 +14,16 @@ On entering this phase, run:
 - changed files
 - claimed outcomes
 - acceptance criteria
+- project type (detected via `detectRunnableType(projectRoot)` → web | api | cli | library, from `tooling/src/verify/proof-collector.js`)
+
+## Process
+
+1. **Detect project type:** Run `detectRunnableType(projectRoot)` to determine verification strategy
+2. **Collect evidence:** Run `collectProof(taskSpec, runConfig)` with the detected type
+3. **For runnable output (web/api/cli):** Run the application and capture runtime evidence (build output, screenshots, curl responses, CLI output)
+4. **For non-runnable output (library/config/skills):** Run lint, format check, type check, and tests — all must pass
+5. **Save evidence:** Write to `.wazir/runs/<id>/artifacts/proof-<task>.json`
+6. **Validate:** Ensure every acceptance criterion has at least one evidence item mapped to it
 
 ## Primary Role
 
@@ -21,7 +31,11 @@ On entering this phase, run:
 
 ## Outputs
 
-- verification proof artifact
+- verification proof artifact (produced by `collectProof` from `tooling/src/verify/proof-collector.js`)
+
+## Proof Collection
+
+Use `detectRunnableType` to classify the project, then `collectProof` to gather evidence. The proof-collector runs type-appropriate commands (build, test, lint, type-check) using `execFileSync` and returns structured `{ type, evidence }`.
 
 ## Approval Gate
 
@@ -32,6 +46,19 @@ On entering this phase, run:
 On completing this phase, run:
 `wazir capture event --run <run-id> --event phase_exit --phase <phase-name> --status completed`
 
+## Proof of Implementation
+
+The verifier detects whether the project output is runnable and collects appropriate evidence:
+
+| Project Type | Detection | Evidence Collected |
+|-------------|-----------|-------------------|
+| `web` | next/vite/react-scripts in deps | Build output, Playwright screenshot (if available), curl response |
+| `api` | express/fastify/hono in deps | curl endpoint responses with status codes |
+| `cli` | `bin` field in package.json | `--help` output, test run with sample args |
+| `library` | default (no runnable markers) | npm test, tsc, eslint, prettier — all must pass |
+
+Evidence is saved to `.wazir/runs/<id>/artifacts/proof-<task>.json` using `collectProof()` from `tooling/src/verify/proof-collector.js`.
+
 ## Relationship to Review Loops
 
 Verification is invoked per-task during execution, not as a review loop. It produces deterministic proof, not adversarial findings.
@@ -39,3 +66,5 @@ Verification is invoked per-task during execution, not as a review loop. It prod
 ## Failure Conditions
 
 - stale or partial verification
+- proof-collector reports `status: "fail"` for any evidence item
+- runnable type detected but no evidence collected