@wazir-dev/cli 1.3.0 → 1.4.0

package/tooling/src/state/pipeline-state.js

@@ -0,0 +1,262 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const PHASE_ORDER = ['init', 'clarify', 'execute', 'verify', 'review', 'complete'];
+
+const STATE_FILE = 'pipeline-state.json';
+
+// ---------------------------------------------------------------------------
+// Atomic file write — temp + rename to prevent corruption
+// ---------------------------------------------------------------------------
+
+function atomicWriteJson(filePath, data) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmpPath = `${filePath}.${process.pid}.tmp`;
+  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmpPath, filePath);
+}
+
+function statePath(stateRoot) {
+  return path.join(stateRoot, STATE_FILE);
+}
+
+// ---------------------------------------------------------------------------
+// Read / Create
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the current pipeline state. Returns null if no state file exists.
+ */
+export function readPipelineState(stateRoot) {
+  const fp = statePath(stateRoot);
+  if (!fs.existsSync(fp)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(fp, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create a fresh pipeline state for a new run.
+ */
+export function createPipelineState(runId, stateRoot) {
+  const state = {
+    run_id: runId,
+    current_phase: 'init',
+    phase_history: [],
+    allowed_transitions: ['clarify'],
+    stop_hook_active: false,
+    artifacts: {},
+    guardrail_results: {},
+    session_id: crypto.randomUUID(),
+    updated_at: new Date().toISOString(),
+  };
+  atomicWriteJson(statePath(stateRoot), state);
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// Transitions
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a transition from currentPhase to nextPhase is valid.
+ * Only forward, sequential transitions are allowed.
+ */
+export function isTransitionAllowed(currentPhase, nextPhase) {
+  const currentIdx = PHASE_ORDER.indexOf(currentPhase);
+  const nextIdx = PHASE_ORDER.indexOf(nextPhase);
+  if (currentIdx === -1 || nextIdx === -1) return false;
+  return nextIdx === currentIdx + 1;
+}
+
+/**
+ * Transition to the next phase. Validates the transition is legal.
+ * Throws on invalid transition or missing state.
+ */
+export function transitionPhase(stateRoot, nextPhase) {
+  const state = readPipelineState(stateRoot);
+  if (!state) {
+    throw new Error('No pipeline state found. Call createPipelineState first.');
+  }
+
+  if (!isTransitionAllowed(state.current_phase, nextPhase)) {
+    throw new Error(
+      `Invalid transition: ${state.current_phase} → ${nextPhase}. ` +
+      `Allowed: ${state.current_phase} → ${PHASE_ORDER[PHASE_ORDER.indexOf(state.current_phase) + 1] ?? 'none'}`,
+    );
+  }
+
+  const now = new Date().toISOString();
+
+  // Record the outgoing phase in history
+  state.phase_history.push({
+    phase: state.current_phase,
+    entered_at: state.phase_entered_at ?? state.updated_at,
+    exited_at: now,
+    status: 'completed',
+  });
+
+  // Move to new phase
+  state.current_phase = nextPhase;
+  state.phase_entered_at = now;
+
+  // Compute next allowed transition
+  const nextIdx = PHASE_ORDER.indexOf(nextPhase);
+  state.allowed_transitions = nextIdx < PHASE_ORDER.length - 1
+    ? [PHASE_ORDER[nextIdx + 1]]
+    : [];
+
+  state.updated_at = now;
+  atomicWriteJson(statePath(stateRoot), state);
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// Phase completion (artifact recording)
+// ---------------------------------------------------------------------------
+
+/**
+ * Mark the current phase as having produced artifacts.
+ * artifacts: { name: { path: string } }
+ */
+export function completePhase(stateRoot, phase, artifacts = {}) {
+  const state = readPipelineState(stateRoot);
+  if (!state) {
+    throw new Error('No pipeline state found.');
+  }
+
+  const now = new Date().toISOString();
+
+  for (const [name, meta] of Object.entries(artifacts)) {
+    const digest = meta.path ? computeArtifactDigest(meta.path) : null;
+    state.artifacts[name] = {
+      path: meta.path,
+      digest,
+      created_at: now,
+    };
+  }
+
+  state.guardrail_results[phase] = { passed: true, checked_at: now };
+  state.updated_at = now;
+  atomicWriteJson(statePath(stateRoot), state);
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// Stop hook flag
+// ---------------------------------------------------------------------------
+
+/**
+ * Set or clear the stop_hook_active flag to prevent infinite loops.
+ */
+export function setStopHookActive(stateRoot, active) {
+  const state = readPipelineState(stateRoot);
+  if (!state) {
+    throw new Error('No pipeline state found.');
+  }
+  state.stop_hook_active = !!active;
+  state.updated_at = new Date().toISOString();
+  atomicWriteJson(statePath(stateRoot), state);
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// Artifact dependency graph
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical artifact dependency graph for the pipeline.
+ * Each artifact lists the artifacts it requires as inputs.
+ */
+export const ARTIFACT_DEPENDENCY_GRAPH = {
+  'clarification.md': { requires: [] },
+  'spec-hardened.md': { requires: ['clarification.md'] },
+  'design.md': { requires: ['spec-hardened.md'] },
+  'execution-plan.md': { requires: ['design.md'] },
+};
+
+/**
+ * Store artifact dependencies in pipeline state.
+ */
+export function setArtifactDependencies(stateRoot, depGraph) {
+  const state = readPipelineState(stateRoot);
+  if (!state) throw new Error('No pipeline state found.');
+  state.artifact_dependencies = depGraph;
+  state.updated_at = new Date().toISOString();
+  atomicWriteJson(statePath(stateRoot), state);
+  return state;
+}
+
+/**
+ * Compute all artifacts downstream of a changed artifact.
+ * Walks the dependency graph to find everything that transitively requires
+ * the changed artifact.
+ *
+ * @param {string} changedArtifact — the artifact that was modified
+ * @param {object} depGraph — the dependency graph
+ * @returns {string[]} downstream artifact names
+ */
+export function computeDownstreamArtifacts(changedArtifact, depGraph) {
+  const downstream = [];
+  const visited = new Set();
+
+  function walk(target) {
+    for (const [name, meta] of Object.entries(depGraph)) {
+      if (visited.has(name)) continue;
+      if (meta.requires.includes(target)) {
+        visited.add(name);
+        downstream.push(name);
+        walk(name);
+      }
+    }
+  }
+
+  walk(changedArtifact);
+  return downstream;
+}
+
+/**
+ * Classify the mutation level of a changed artifact.
+ *
+ * - L0 (cosmetic): unknown artifact, no graph impact
+ * - L1 (local): leaf artifact with no downstream dependents
+ * - L2 (structural): mid-graph artifact with some downstream dependents
+ * - L3 (fundamental): root artifact — everything downstream is affected
+ *
+ * @param {string} changedArtifact
+ * @param {object} depGraph
+ * @returns {'L0'|'L1'|'L2'|'L3'}
+ */
+export function classifyMutation(changedArtifact, depGraph) {
+  if (!(changedArtifact in depGraph)) return 'L0';
+
+  const downstream = computeDownstreamArtifacts(changedArtifact, depGraph);
+  const entry = depGraph[changedArtifact];
+
+  // Root artifact (no requirements) with downstream dependents
+  if (entry.requires.length === 0 && downstream.length > 0) return 'L3';
+
+  // Mid-graph: has downstream dependents
+  if (downstream.length > 0) return 'L2';
+
+  // Leaf: no downstream dependents
+  return 'L1';
+}
+
+// ---------------------------------------------------------------------------
+// Artifact digest
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute sha256 digest of a file. Returns null if file doesn't exist.
+ */
+export function computeArtifactDigest(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const content = fs.readFileSync(filePath);
+  const hash = crypto.createHash('sha256').update(content).digest('hex');
+  return `sha256:${hash}`;
+}

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