@wazir-dev/cli 1.0.0 → 1.2.0

package/tooling/src/state/db.js

@@ -0,0 +1,287 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+function getStateDatabasePath(stateRoot) {
+  return path.join(stateRoot, 'state', 'state.sqlite');
+}
+
+function hashDescription(description) {
+  return crypto.createHash('sha256').update(description).digest('hex');
+}
+
+function ensureStateSchema(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS learnings (
+      id TEXT PRIMARY KEY,
+      source_run TEXT NOT NULL,
+      category TEXT NOT NULL,
+      scope_roles TEXT DEFAULT '',
+      scope_stacks TEXT DEFAULT '',
+      scope_concerns TEXT DEFAULT '',
+      confidence TEXT DEFAULT 'medium' CHECK(confidence IN ('low','medium','high')),
+      recurrence_count INTEGER DEFAULT 1,
+      content TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      last_applied TEXT,
+      expires_at TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS findings (
+      id TEXT PRIMARY KEY,
+      run_id TEXT NOT NULL,
+      phase TEXT NOT NULL,
+      source TEXT NOT NULL CHECK(source IN ('internal','codex','self-audit','gemini')),
+      severity TEXT NOT NULL CHECK(severity IN ('critical','high','medium','low')),
+      description TEXT NOT NULL,
+      resolved INTEGER DEFAULT 0,
+      finding_hash TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS audit_history (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      run_id TEXT NOT NULL,
+      date TEXT NOT NULL DEFAULT (date('now')),
+      finding_count INTEGER DEFAULT 0,
+      fix_count INTEGER DEFAULT 0,
+      manual_count INTEGER DEFAULT 0,
+      quality_score_before REAL,
+      quality_score_after REAL
+    );
+
+    CREATE TABLE IF NOT EXISTS usage_aggregate (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      run_id TEXT NOT NULL,
+      date TEXT NOT NULL DEFAULT (date('now')),
+      tokens_saved INTEGER DEFAULT 0,
+      bytes_avoided INTEGER DEFAULT 0,
+      savings_ratio REAL DEFAULT 0.0,
+      index_queries INTEGER DEFAULT 0,
+      routing_decisions INTEGER DEFAULT 0
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_learnings_category ON learnings(category);
+    CREATE INDEX IF NOT EXISTS idx_findings_run_id ON findings(run_id);
+    CREATE INDEX IF NOT EXISTS idx_findings_finding_hash ON findings(finding_hash);
+    CREATE INDEX IF NOT EXISTS idx_audit_history_run_id ON audit_history(run_id);
+    CREATE INDEX IF NOT EXISTS idx_usage_aggregate_run_id ON usage_aggregate(run_id);
+  `);
+}
+
+// ---------------------------------------------------------------------------
+// Database lifecycle
+// ---------------------------------------------------------------------------
+
+export function openStateDb(stateRoot) {
+  const databasePath = getStateDatabasePath(stateRoot);
+  fs.mkdirSync(path.dirname(databasePath), { recursive: true });
+  const db = new DatabaseSync(databasePath, { timeout: 5000 });
+  ensureStateSchema(db);
+  return db;
+}
+
+export function closeStateDb(db) {
+  db.close();
+}
+
+// ---------------------------------------------------------------------------
+// Learnings CRUD
+// ---------------------------------------------------------------------------
+
+export function insertLearning(db, record) {
+  const id = crypto.randomUUID();
+  const createdAt = new Date().toISOString();
+
+  db.prepare(`
+    INSERT INTO learnings (id, source_run, category, scope_roles, scope_stacks, scope_concerns, confidence, content, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    id,
+    record.source_run,
+    record.category,
+    record.scope_roles ?? '',
+    record.scope_stacks ?? '',
+    record.scope_concerns ?? '',
+    record.confidence ?? 'medium',
+    record.content,
+    createdAt,
+  );
+
+  return id;
+}
+
+export function getLearningsByScope(db, filters = {}) {
+  const conditions = [];
+  const params = [];
+
+  if (filters.roles) {
+    conditions.push("scope_roles LIKE ?");
+    params.push(`%${filters.roles}%`);
+  }
+
+  if (filters.stacks) {
+    conditions.push("scope_stacks LIKE ?");
+    params.push(`%${filters.stacks}%`);
+  }
+
+  if (filters.concerns) {
+    conditions.push("scope_concerns LIKE ?");
+    params.push(`%${filters.concerns}%`);
+  }
+
+  if (filters.confidence) {
+    conditions.push("confidence = ?");
+    params.push(filters.confidence);
+  }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+  const limit = filters.limit ? `LIMIT ${Number(filters.limit)}` : '';
+
+  return db.prepare(`
+    SELECT * FROM learnings ${where} ORDER BY created_at DESC ${limit}
+  `).all(...params);
+}
+
+export function updateLearningRecurrence(db, id) {
+  const now = new Date().toISOString();
+
+  db.prepare(`
+    UPDATE learnings
+    SET recurrence_count = recurrence_count + 1,
+        last_applied = ?
+    WHERE id = ?
+  `).run(now, id);
+}
+
+export function getRecurringLearnings(db, minCount) {
+  return db.prepare(`
+    SELECT * FROM learnings
+    WHERE recurrence_count >= ?
+    ORDER BY recurrence_count DESC
+  `).all(minCount);
+}
+
+// ---------------------------------------------------------------------------
+// Findings CRUD
+// ---------------------------------------------------------------------------
+
+export function insertFinding(db, record) {
+  const id = crypto.randomUUID();
+  const findingHash = record.finding_hash ?? hashDescription(record.description);
+  const createdAt = new Date().toISOString();
+
+  db.prepare(`
+    INSERT INTO findings (id, run_id, phase, source, severity, description, finding_hash, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    id,
+    record.run_id,
+    record.phase,
+    record.source,
+    record.severity,
+    record.description,
+    findingHash,
+    createdAt,
+  );
+
+  return id;
+}
+
+export function getFindingsByRun(db, runId) {
+  return db.prepare(`
+    SELECT * FROM findings
+    WHERE run_id = ?
+    ORDER BY created_at ASC
+  `).all(runId);
+}
+
+export function getRecurringFindingHashes(db, minOccurrences) {
+  return db.prepare(`
+    SELECT finding_hash, COUNT(*) AS count
+    FROM findings
+    GROUP BY finding_hash
+    HAVING COUNT(*) >= ?
+    ORDER BY count DESC
+  `).all(minOccurrences);
+}
+
+export function resolveFinding(db, id) {
+  db.prepare(`
+    UPDATE findings SET resolved = 1 WHERE id = ?
+  `).run(id);
+}
+
+// ---------------------------------------------------------------------------
+// Audit history
+// ---------------------------------------------------------------------------
+
+export function insertAuditRecord(db, record) {
+  db.prepare(`
+    INSERT INTO audit_history (run_id, finding_count, fix_count, manual_count, quality_score_before, quality_score_after)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(
+    record.run_id,
+    record.finding_count ?? 0,
+    record.fix_count ?? 0,
+    record.manual_count ?? 0,
+    record.quality_score_before ?? null,
+    record.quality_score_after ?? null,
+  );
+}
+
+export function getAuditTrend(db, limit) {
+  const limitClause = limit ? `LIMIT ${Number(limit)}` : '';
+
+  return db.prepare(`
+    SELECT * FROM audit_history
+    ORDER BY date DESC, id DESC
+    ${limitClause}
+  `).all();
+}
+
+// ---------------------------------------------------------------------------
+// Usage
+// ---------------------------------------------------------------------------
+
+export function insertUsageRecord(db, record) {
+  db.prepare(`
+    INSERT INTO usage_aggregate (run_id, tokens_saved, bytes_avoided, savings_ratio, index_queries, routing_decisions)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(
+    record.run_id,
+    record.tokens_saved ?? 0,
+    record.bytes_avoided ?? 0,
+    record.savings_ratio ?? 0.0,
+    record.index_queries ?? 0,
+    record.routing_decisions ?? 0,
+  );
+}
+
+export function getUsageSummary(db) {
+  const row = db.prepare(`
+    SELECT
+      COALESCE(SUM(tokens_saved), 0) AS total_tokens_saved,
+      COALESCE(SUM(bytes_avoided), 0) AS total_bytes_avoided,
+      CASE WHEN COUNT(*) > 0 THEN AVG(savings_ratio) ELSE 0.0 END AS avg_savings_ratio,
+      COALESCE(SUM(index_queries), 0) AS total_index_queries,
+      COUNT(*) AS run_count
+    FROM usage_aggregate
+  `).get();
+
+  return row;
+}
+
+// ---------------------------------------------------------------------------
+// Stats (for CLI)
+// ---------------------------------------------------------------------------
+
+export function getStateCounts(db) {
+  return {
+    learning_count: db.prepare('SELECT COUNT(*) AS count FROM learnings').get().count,
+    finding_count: db.prepare('SELECT COUNT(*) AS count FROM findings').get().count,
+    audit_count: db.prepare('SELECT COUNT(*) AS count FROM audit_history').get().count,
+    usage_count: db.prepare('SELECT COUNT(*) AS count FROM usage_aggregate').get().count,
+  };
+}

package/tooling/src/status/command.js

@@ -5,6 +5,46 @@ import { parseCommandOptions } from '../command-options.js';
 import { readYamlFile } from '../loaders.js';
 import { findProjectRoot } from '../project-root.js';
 import { resolveStateRoot } from '../state-root.js';
+import { estimateTokens } from '../capture/usage.js';
+
+function readUsageSavingsSummary(stateRoot, runId) {
+  const usagePath = path.join(stateRoot, 'runs', runId, 'usage.json');
+
+  if (!fs.existsSync(usagePath)) {
+    return null;
+  }
+
+  try {
+    const usage = JSON.parse(fs.readFileSync(usagePath, 'utf8'));
+    const cr = usage.savings?.capture_routing ?? {};
+    const cm = usage.savings?.context_mode ?? {};
+    const co = usage.savings?.compaction ?? {};
+    const iq = usage.savings?.index_queries ?? {};
+
+    const crTokensSaved = cr.estimated_tokens_avoided ?? 0;
+    const cmRawTokens = estimateTokens(Math.round((cm.raw_kb ?? 0) * 1024));
+    const cmAfterTokens = estimateTokens(Math.round((cm.context_kb ?? 0) * 1024));
+    const cmTokensSaved = cmRawTokens - cmAfterTokens;
+    const coTokensSaved = (co.pre_compaction_tokens_est ?? 0) - (co.post_compaction_tokens_est ?? 0);
+    const iqTokensSaved = iq.estimated_tokens_saved ?? 0;
+
+    const totalSaved = crTokensSaved + cmTokensSaved + coTokensSaved + iqTokensSaved;
+
+    if (totalSaved === 0) {
+      return null;
+    }
+
+    const crRawTokens = crTokensSaved + estimateTokens(cr.summary_bytes ?? 0);
+    const withoutSavings = crRawTokens + cmRawTokens + (co.pre_compaction_tokens_est ?? 0);
+    const pct = withoutSavings > 0
+      ? `${((totalSaved / withoutSavings) * 100).toFixed(0)}%`
+      : '0%';
+
+    return `Context savings: ~${totalSaved.toLocaleString('en-US')} tokens saved (${pct} reduction)`;
+  } catch {
+    return null;
+  }
+}
 
 function success(payload, options = {}) {
   if (options.json) {
@@ -14,9 +54,15 @@ function success(payload, options = {}) {
     };
   }
 
+  let output = `${payload.run_id} ${payload.phase} ${payload.status}\n`;
+
+  if (payload.savings_summary) {
+    output += `${payload.savings_summary}\n`;
+  }
+
   return {
     exitCode: 0,
-    stdout: `${payload.run_id} ${payload.phase} ${payload.status}\n`,
+    stdout: output,
   };
 }
 
@@ -61,6 +107,12 @@ export function runStatusCommand(parsed, context = {}) {
       status_path: statusPath,
     };
 
+    const savingsSummary = readUsageSavingsSummary(stateRoot, options.run);
+
+    if (savingsSummary) {
+      payload.savings_summary = savingsSummary;
+    }
+
     return success(payload, { json: options.json });
   } catch (error) {
     return {

package/wazir.manifest.yaml

@@ -47,20 +47,31 @@ workflows:
   - prepare_next
   - run_audit
 phases:
-  - clarify
-  - discover
-  - specify
-  - spec_challenge
-  - author
-  - design
-  - design_review
-  - plan
-  - plan_review
-  - execute
-  - verify
-  - review
-  - learn
-  - prepare_next
+  - init
+  - clarifier
+  - executor
+  - final_review
+phase_prerequisites:
+  init: {}
+  clarifier: {}
+  executor:
+    required_artifacts:
+      - clarified/clarification.md
+      - clarified/spec-hardened.md
+      - clarified/design.md
+      - clarified/execution-plan.md
+    required_phase_exits:
+      - clarifier
+  final_review:
+    required_artifacts:
+      - clarified/clarification.md
+      - clarified/spec-hardened.md
+      - clarified/design.md
+      - clarified/execution-plan.md
+      - artifacts/verification-proof.md
+    required_phase_exits:
+      - clarifier
+      - executor
 roles:
   - clarifier
   - researcher
@@ -85,6 +96,7 @@ required_hooks:
   - stop_handoff_harvest
   - protected_path_write_guard
   - loop_cap_guard
+  - context_mode_router
 protected_paths:
   - input
   - roles
@@ -92,11 +104,8 @@ protected_paths:
   - schemas
   - exports/hosts
 prohibited_terms:
-  - Agent OS
-  - daemon
   - HTTP control plane
   - web UI
-  - OpenAI Symphony
   - Elixir
 adapters:
   context_mode:

package/workflows/clarify.md

@@ -24,6 +24,10 @@ On entering this phase, run:
 - unresolved questions list
 - scope summary
 
+## Review Loop
+
+Clarification artifact is reviewed by the reviewer role using the review loop pattern with spec/clarification dimensions. The reviewer is invoked with `--mode clarification-review`. The clarifier resolves findings. Clarification does not flow to specify until all review passes complete.
+
 ## Approval Gate
 
 - no formal approval gate, but unresolved material ambiguity must be escalated

package/workflows/design-review.md

@@ -39,6 +39,10 @@ On rejection: `wazir capture event --run <run-id> --event gate_rejected --phase
 On completing this phase, run:
 `wazir capture event --run <run-id> --event phase_exit --phase <phase-name> --status completed`
 
+## Loop Structure
+
+Follows the review loop pattern in `docs/reference/review-loop-pattern.md` with the canonical design-review dimensions (spec coverage, design-spec consistency, accessibility, visual consistency, exported-code fidelity). The designer role resolves findings. Starts when the approved design artifact enters the `design_review` phase. Pass count determined by depth. No extension.
+
 ## Failure Conditions
 
 - vague findings without visual evidence

package/workflows/design.md

@@ -33,6 +33,10 @@ On entering this phase, run:
 
 - explicit human approval required before design-review
 
+## Review Loop
+
+After user approval, design artifact is reviewed via the design-review workflow (`workflows/design-review.md`) using the review loop pattern with the canonical design-review dimensions (spec coverage, design-spec consistency, accessibility, visual consistency, exported-code fidelity). The reviewer is invoked with `--mode design-review`. Design does not flow to planning until all review passes complete.
+
 ## Phase exit
 
 On completing this phase, run:

package/workflows/discover.md

@@ -23,6 +23,10 @@ On entering this phase, run:
 - research artifact
 - cited findings
 
+## Review Loop
+
+Research artifact is reviewed by the reviewer role using the review loop pattern (`docs/reference/review-loop-pattern.md`) with research dimensions (coverage, source quality, relevance, gaps, contradictions). The reviewer is invoked with `--mode research-review`. The researcher resolves findings. Research does not flow to specify until all review passes complete.
+
 ## Approval Gate
 
 - no formal approval gate, but unsupported research cannot flow forward

package/workflows/execute.md

@@ -34,6 +34,10 @@ If either check fails:
 - code and docs changes
 - execution notes
 
+## Per-Task Review
+
+Each task's output is reviewed using the review loop pattern with the 5 task-execution dimensions (correctness, tests, wiring, drift, quality). The reviewer is invoked with `--mode task-review --task-id <NNN>`. This is NOT the final review -- it is a per-task gate. Review happens BEFORE commit. Review logs use task-scoped filenames: `<phase>-task-<NNN>-review-pass-<N>.md`. See `docs/reference/review-loop-pattern.md` for code review scoping rules.
+
 ## Approval Gate
 
 - no new scope without explicit approval

package/workflows/plan-review.md

@@ -37,6 +37,10 @@ On rejection: `wazir capture event --run <run-id> --event gate_rejected --phase
 On completing this phase, run:
 `wazir capture event --run <run-id> --event phase_exit --phase <phase-name> --status completed`
 
+## 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.
+
 ## Failure Conditions
 
 - sequence gaps survive review

package/workflows/plan.md

@@ -25,6 +25,10 @@ On entering this phase, run:
 - implementation plan artifact
 - ordered tasks and verification steps
 
+## Review Loop
+
+Plan artifact is reviewed via the plan-review workflow (`workflows/plan-review.md`) using the review loop pattern with plan dimensions. The reviewer is invoked with `--mode plan-review`.
+
 ## Approval Gate
 
 - explicit human approval required before execution

package/workflows/spec-challenge.md

@@ -36,6 +36,10 @@ On rejection: `wazir capture event --run <run-id> --event gate_rejected --phase
 On completing this phase, run:
 `wazir capture event --run <run-id> --event phase_exit --phase <phase-name> --status completed`
 
+## Loop Structure
+
+This workflow IS a review loop. Follows the pattern in `docs/reference/review-loop-pattern.md` with spec/clarification dimensions. The specifier role resolves findings. Loop count tracked via `wazir capture loop-check --mode spec-challenge`. Pass count determined by depth (quick=3, standard=5, deep=7). No extension beyond depth pass count.
+
 ## Failure Conditions
 
 - rubber-stamp review

package/workflows/specify.md

@@ -24,6 +24,10 @@ On entering this phase, run:
 - acceptance criteria
 - assumptions and non-goals
 
+## Review Loop
+
+Spec artifact is reviewed via the spec-challenge workflow (`workflows/spec-challenge.md`) using the review loop pattern with spec dimensions. The reviewer is invoked with `--mode spec-challenge`. The specifier resolves findings.
+
 ## Approval Gate
 
 - explicit human approval required before planning

package/workflows/verify.md

@@ -32,6 +32,10 @@ On entering this phase, run:
 On completing this phase, run:
 `wazir capture event --run <run-id> --event phase_exit --phase <phase-name> --status completed`
 
+## Relationship to Review Loops
+
+Verification is invoked per-task during execution, not as a review loop. It produces deterministic proof, not adversarial findings.
+
 ## Failure Conditions
 
 - stale or partial verification