@wazir-dev/cli 1.3.0 → 1.4.0

package/skills/writing-skills/persuasion-principles.md

@@ -2,49 +2,115 @@
 
 ## Overview
 
-LLMs respond to the same persuasion principles as humans. Understanding this psychology helps you design more effective skills - not to manipulate, but to ensure critical practices are followed even under pressure.
+LLMs exhibit statistical compliance biases that can be leveraged to improve instruction following. This is not psychology applied to machines — it is empirical prompt engineering grounded in attention mechanics, training distribution effects, and measured compliance rates.
 
-**Research foundation:** Meincke et al. (2025) tested 7 persuasion principles with N=28,000 AI conversations. Persuasion techniques more than doubled compliance rates (33% -> 72%, p < .001).
+**Research foundation:** Meincke et al. (2025) tested 7 persuasion principles with N=28,000 AI conversations. Commitment priming approached 100% compliance. Positive directive framing consistently outperformed negative framing. Authority framing lifted compliance by ~40pp.
 
-## The Seven Principles
+## Principles Ranked by Evidence Strength
 
-### 1. Authority
-- Imperative language: "YOU MUST", "Never", "Always"
-- Non-negotiable framing: "No exceptions"
-- Eliminates decision fatigue and rationalization
+### Tier 1: Strong Evidence, Large Effect
 
-### 2. Commitment
-- Require announcements: "Announce skill usage"
-- Force explicit choices: "Choose A, B, or C"
-- Use tracking: TodoWrite for checklists
+**1. Commitment Priming (highest impact)**
+- Have the model announce its plan before executing
+- Autoregressive consistency: once the model generates "I will do X", it is statistically more likely to do X
+- Implementation: "Before executing, state which steps you will perform"
+- Measured: near-100% compliance after self-commitment in Meincke et al.
 
-### 3. Scarcity
-- Time-bound requirements: "Before proceeding"
-- Sequential dependencies: "Immediately after X"
-- Prevents procrastination
+**2. Positive Directive Framing**
+- "Always do X" consistently outperforms "Never do Y"
+- Token generation selects what to produce, not what to avoid
+- Negative instructions ("do NOT mention X") can paradoxically increase mentions
+- Use negative framing ONLY for critical guardrails with a positive alternative: "Do NOT skip review. Instead, run review quickly."
 
-### 4. Social Proof
-- Universal patterns: "Every time", "Always"
-- Failure modes: "X without Y = failure"
-- Establishes norms
+**3. Structural Isolation (XML Tags)**
+- Claude is fine-tuned to attend to XML tag boundaries
+- Tags create attention-weight spikes and trust boundaries
+- Use `<rules>`, `<instructions>`, `<output_format>` for hard boundaries
+- Hybrid XML+markdown is optimal: XML for structure, markdown for formatting within sections
 
-### 5. Unity
-- Collaborative language: "our codebase", "we're colleagues"
-- Shared goals: "we both want quality"
+**4. Positional Privilege (Primacy + Recency)**
+- First ~500 tokens: ~95% compliance (primacy zone)
+- Last ~500 tokens: ~85% compliance (recency zone)
+- Middle of long context: ~65-75% compliance (lost in the middle)
+- Critical rules go at beginning AND end. Never only in the middle.
 
-### 6. Reciprocity
-- Obligation to return favors
-- "I'll give you full context, you give me honest assessment"
+### Tier 2: Strong Evidence, Moderate Effect
 
-### 7. Liking
-- Avoid in discipline-enforcing skills
-- Use sparingly for collaborative skills
+**5. Authority / Role Assignment**
+- "You are a senior security auditor responsible for..." activates domain-specific patterns
+- +40pp lift in Meincke et al.
+- Expert personas produce more accurate, more disciplined output
+
+**6. Consequence Framing**
+- "Skipping this step causes silent regressions that waste hours of debugging"
+- Provides reasoning context for why compliance matters
+- More effective than abstract rules ("always follow the process")
+
+**7. Implementation Intentions (IF-THEN rules)**
+- "IF user says skip → THEN say 'Running it quickly' and execute"
+- Pre-decides the response — no judgment call needed at runtime
+- d=0.65 across 94 psychology studies (Gollwitzer). Maps directly to LLM prompt design.
+- Single most actionable technique for skill authors
+
+**8. Redundant Reinforcement**
+- State the rule, show an example, reference it in the output format, add a constraint tag
+- Multiple encoding paths survive when any single one fails
+- Paraphrased repetition (2-3x) outperforms verbatim repetition
+
+### Tier 3: Context-Dependent Effect
+
+**9. Social Proof**
+- "Standard practice is..." or "All production systems follow this pattern"
+- Effective when baseline compliance is already moderate (+6pp)
+
+**10. Urgency / Scarcity**
+- "This must be done correctly the first time; there is no retry"
+- Increases both compliance and output variance — use sparingly
+
+**11. Moral / Ethical Framing**
+- "Omitting this would produce misleading output"
+- Effective for Claude specifically due to Constitutional AI training
+- Frame positively (good outcome of compliance) not negatively
+
+## Anti-Patterns
+
+| Pattern | Problem |
+|---------|---------|
+| Negative instructions without alternatives | "Don't do X" fails — model must activate X to evaluate constraint |
+| Instruction overload (>12 constraints) | Steep compliance drop after ~12 accumulated constraints |
+| Threats without specifics | "You will be punished" increases variance without improving median |
+| Reciprocity framing | "I helped you, now help me" — weakest principle, only +11pp |
+| Relying solely on alignment | 80% of enterprises reported injection incidents. Structural defenses needed. |
 
 ## Principle Combinations by Skill Type
 
-| Skill Type | Use | Avoid |
-|------------|-----|-------|
-| Discipline-enforcing | Authority + Commitment + Social Proof | Liking, Reciprocity |
-| Guidance/technique | Moderate Authority + Unity | Heavy authority |
-| Collaborative | Unity + Commitment | Authority, Liking |
-| Reference | Clarity only | All persuasion |
+| Skill Type | Primary Techniques | Avoid |
+|------------|-------------------|-------|
+| Discipline-enforcing (TDD, verification) | Commitment + Implementation Intentions + Positional Privilege + Authority | Liking, Reciprocity |
+| Process-governing (clarifier, executor) | Commitment + Consequence Framing + Structural Isolation | Heavy emotional framing |
+| Collaborative (brainstorming, design) | Moderate Authority + Implementation Intentions | Over-constraining creative steps |
+| Reference (docs, guides) | Structural Isolation + Positional Privilege | All persuasion — clarity only |
+
+## The 3-Zone Architecture
+
+Apply these principles through the 3-zone skill layout:
+
+- **Zone 1 (Primacy):** Identity + Iron Laws + Priority Stack — leverages positional privilege + authority + commitment
+- **Zone 2 (Process):** IF-THEN rules + decision tables + gate functions — leverages implementation intentions + structural isolation
+- **Zone 3 (Recency):** Restated laws + Red Flags + meta-instruction — leverages recency + redundant reinforcement + consequence framing
+
+## Temporal Testing Advisory
+
+Prompt engineering techniques lose effectiveness as models improve. Re-test skill compliance every major model version. Include a "last verified" date on persuasion-dependent skills.
+
+**Last verified:** Claude Opus 4.6, March 2026
+
+## Sources
+
+- Meincke et al. (2025). "Call Me A Jerk: Persuading AI to Comply" (N=28,000, SSRN)
+- Liu et al. (2024). "Lost in the Middle" (TACL, arXiv:2307.03172)
+- Wallace et al. (2024). "The Instruction Hierarchy" (OpenAI, arXiv:2404.13208)
+- Gollwitzer (1999). Implementation Intentions (d=0.65, 94 studies meta-analysis)
+- EmotionPrompt (2023). Emotional framing effects (arXiv:2307.11760)
+- Zhou et al. (2023). IFEval benchmark (arXiv:2311.07911)
+- Anthropic (2024). Claude Model Spec — instruction hierarchy documentation

package/tooling/src/capture/command.js

@@ -19,6 +19,7 @@ import {
 } from './store.js';
 import { readRunConfig, getPhaseLoopCap } from './run-config.js';
 import { readUsage, generateReport, initUsage, recordCaptureSavings, recordPhaseUsage } from './usage.js';
+import { appendDecision } from './decision.js';
 import { evaluateLoopCapGuard } from '../guards/loop-cap-guard.js';
 import { evaluatePhasePrerequisiteGuard } from '../guards/phase-prerequisite-guard.js';
 
@@ -73,6 +74,8 @@ function resolveCaptureContext(parsed, context = {}) {
       'command',
       'exit-code',
       'task-id',
+      'decision',
+      'reason',
     ],
   });
   const stateRoot = resolveStateRoot(projectRoot, manifest, {
@@ -388,6 +391,29 @@ function handleUsage(parsed, context = {}) {
   };
 }
 
+function handleDecision(parsed, context = {}) {
+  const { stateRoot, options } = resolveCaptureContext(parsed, context);
+
+  requireOption(options, 'run', 'Usage: wazir capture decision --run <id> --phase <phase> --decision "<text>" --reason "<text>" [--task-id <id>] [--state-root <path>] [--json]');
+  requireOption(options, 'phase', 'Usage: wazir capture decision --run <id> --phase <phase> --decision "<text>" --reason "<text>" [--task-id <id>] [--state-root <path>] [--json]');
+  requireOption(options, 'decision', 'Usage: wazir capture decision --run <id> --phase <phase> --decision "<text>" --reason "<text>" [--task-id <id>] [--state-root <path>] [--json]');
+  requireOption(options, 'reason', 'Usage: wazir capture decision --run <id> --phase <phase> --decision "<text>" --reason "<text>" [--task-id <id>] [--state-root <path>] [--json]');
+
+  const runPaths = getRunPaths(stateRoot, options.run);
+  appendDecision(runPaths, {
+    phase: options.phase,
+    decision: options.decision,
+    reason: options.reason,
+    task_id: options.taskId,
+  });
+
+  return formatResult({
+    run_id: options.run,
+    event: 'decision',
+    decisions_path: runPaths.decisionsPath,
+  }, { json: options.json });
+}
+
 function handleLoopCheck(parsed, context = {}) {
   const { stateRoot, options } = resolveCaptureContext(parsed, context);
 
@@ -486,10 +512,12 @@ export function runCaptureCommand(parsed, context = {}) {
         return handleUsage(parsed, context);
       case 'loop-check':
         return handleLoopCheck(parsed, context);
+      case 'decision':
+        return handleDecision(parsed, context);
       default:
         return {
           exitCode: 1,
-          stderr: 'Usage: wazir capture <init|event|route|output|summary|usage|loop-check> ...\n',
+          stderr: 'Usage: wazir capture <init|event|route|output|summary|usage|loop-check|decision> ...\n',
         };
     }
   } catch (error) {

package/tooling/src/capture/decision.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+
+/**
+ * Append a decision entry to the run's NDJSON log.
+ *
+ * @param {object} runPaths - Run paths object (must include decisionsPath)
+ * @param {object} entry - { phase, decision, reason, task_id? }
+ */
+export function appendDecision(runPaths, { phase, decision, reason, task_id }) {
+  const record = {
+    timestamp: new Date().toISOString(),
+    phase: phase ?? 'unknown',
+    decision: decision ?? '',
+    reason: reason ?? '',
+  };
+  if (task_id) {
+    record.task_id = task_id;
+  }
+  fs.appendFileSync(runPaths.decisionsPath, JSON.stringify(record) + '\n');
+  return runPaths.decisionsPath;
+}
+
+/**
+ * Read all entries from a run's decisions log.
+ *
+ * @param {object} runPaths - Run paths object (must include decisionsPath)
+ * @returns {Array<object>}
+ */
+export function readDecisions(runPaths) {
+  if (!fs.existsSync(runPaths.decisionsPath)) return [];
+
+  return fs.readFileSync(runPaths.decisionsPath, 'utf8')
+    .split('\n')
+    .filter(line => line.trim())
+    .map(line => {
+      try { return JSON.parse(line); }
+      catch { return null; }
+    })
+    .filter(Boolean);
+}

package/tooling/src/capture/store.js

@@ -19,6 +19,7 @@ export function getRunPaths(stateRoot, runId) {
     capturesDir,
     statusPath: path.join(runRoot, 'status.json'),
     eventsPath: path.join(runRoot, 'events.ndjson'),
+    decisionsPath: path.join(runRoot, 'decisions.ndjson'),
     summaryPath: path.join(runRoot, 'summary.md'),
     usagePath: path.join(runRoot, 'usage.json'),
   };

package/tooling/src/config/depth-table.js

@@ -0,0 +1,60 @@
+/**
+ * Canonical depth parameter table.
+ *
+ * Single source of truth for all depth-dependent behavior across the pipeline.
+ * Skills reference these values conceptually; hooks and tooling import directly.
+ */
+
+export const DEPTH_LEVELS = new Set(['quick', 'standard', 'deep']);
+
+export const DEPTH_TABLE = {
+  quick: {
+    review_passes: 3,
+    loop_cap: 5,
+    heartbeat_max_silence_s: 180,
+    research_intensity: 'minimal',
+    challenge_intensity: 'surface',
+    spec_hardening_passes: 1,
+    design_review_passes: 1,
+    time_estimate_label: '~15-30 min',
+  },
+  standard: {
+    review_passes: 5,
+    loop_cap: 10,
+    heartbeat_max_silence_s: 120,
+    research_intensity: 'balanced',
+    challenge_intensity: 'balanced',
+    spec_hardening_passes: 3,
+    design_review_passes: 3,
+    time_estimate_label: '~45-90 min',
+  },
+  deep: {
+    review_passes: 7,
+    loop_cap: 15,
+    heartbeat_max_silence_s: 90,
+    research_intensity: 'thorough',
+    challenge_intensity: 'adversarial',
+    spec_hardening_passes: 5,
+    design_review_passes: 5,
+    time_estimate_label: '~2-3 hrs',
+  },
+};
+
+/**
+ * Get a specific depth parameter value.
+ *
+ * @param {string} depth  — 'quick' | 'standard' | 'deep' (defaults to 'standard')
+ * @param {string} param  — parameter name from the depth table
+ * @returns {*} the parameter value
+ */
+export function getDepthParam(depth, param) {
+  const level = depth ?? 'standard';
+  if (!DEPTH_LEVELS.has(level)) {
+    throw new Error(`Unknown depth level: "${level}". Valid levels: ${[...DEPTH_LEVELS].join(', ')}`);
+  }
+  const entry = DEPTH_TABLE[level];
+  if (!(param in entry)) {
+    throw new Error(`Unknown depth parameter: "${param}". Valid params: ${Object.keys(entry).join(', ')}`);
+  }
+  return entry[param];
+}

package/tooling/src/export/compiler.js

@@ -91,8 +91,7 @@ function renderCommonInstructions(host, manifest) {
 const DEFAULT_CLAUDE_HOOKS = {
   hooks: {
     PreToolUse: [
-      { matcher: 'Write|Edit', hooks: [{ type: 'command', command: './hooks/protected-path-write-guard' }] },
-      { matcher: 'Bash', hooks: [{ type: 'command', command: './hooks/context-mode-router' }] },
+      { matcher: 'Write|Edit|Bash', hooks: [{ type: 'command', command: './hooks/pretooluse-dispatcher' }] },
     ],
     SessionStart: [
       { hooks: [{ type: 'command', command: './hooks/loop-cap-guard' }] },
@@ -115,21 +114,21 @@ function renderCursorHooks() {
   return JSON.stringify({
     hooks: [
       {
-        name: 'protected-path-write-guard',
-        command: './hooks/protected-path-write-guard',
+        name: 'pretooluse-dispatcher',
+        command: './hooks/pretooluse-dispatcher',
       },
       {
         name: 'loop-cap-guard',
         command: './hooks/loop-cap-guard',
       },
-      {
-        name: 'context-mode-router',
-        command: './hooks/context-mode-router',
-      },
       {
         name: 'session-start',
         command: './hooks/session-start',
       },
+      {
+        name: 'stop-pipeline-gate',
+        command: './hooks/stop-pipeline-gate',
+      },
     ],
   }, null, 2);
 }

package/tooling/src/guards/guardrail-functions.js

@@ -0,0 +1,131 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function fileExistsAndNonEmpty(filePath) {
+  if (!fs.existsSync(filePath)) return false;
+  const stat = fs.statSync(filePath);
+  return stat.size > 0;
+}
+
+function result(passed, reason, missing = []) {
+  return { passed, reason, ...(missing.length > 0 ? { missing } : {}) };
+}
+
+// ---------------------------------------------------------------------------
+// Per-phase validators
+// ---------------------------------------------------------------------------
+
+const CLARIFY_ARTIFACTS = [
+  'clarified/clarification.md',
+  'clarified/spec-hardened.md',
+  'clarified/design.md',
+  'clarified/execution-plan.md',
+];
+
+/**
+ * Validates clarify phase produced all required artifacts.
+ */
+export function validateClarifyComplete(_state, runDir) {
+  const missing = [];
+  for (const relPath of CLARIFY_ARTIFACTS) {
+    const full = path.join(runDir, relPath);
+    if (!fileExistsAndNonEmpty(full)) {
+      missing.push(relPath);
+    }
+  }
+  if (missing.length > 0) {
+    return result(false, `Missing clarify artifacts: ${missing.join(', ')}`, missing);
+  }
+  return result(true, 'All clarify artifacts present and non-empty.');
+}
+
+/**
+ * Validates execute phase: at least one task artifact dir and verification proof.
+ */
+export function validateExecuteComplete(_state, runDir) {
+  const missing = [];
+  const artifactsDir = path.join(runDir, 'artifacts');
+
+  // Check for at least one task-NNN directory with content
+  const taskDirs = fs.existsSync(artifactsDir)
+    ? fs.readdirSync(artifactsDir).filter(d => d.startsWith('task-') && fs.statSync(path.join(artifactsDir, d)).isDirectory())
+    : [];
+
+  if (taskDirs.length === 0) {
+    missing.push('artifacts/task-NNN/ (no task artifacts found)');
+  }
+
+  // Check verification proof
+  const proofPath = path.join(artifactsDir, 'verification-proof.md');
+  if (!fileExistsAndNonEmpty(proofPath)) {
+    missing.push('artifacts/verification-proof.md');
+  }
+
+  if (missing.length > 0) {
+    return result(false, `Missing execute artifacts: ${missing.join(', ')}`, missing);
+  }
+  return result(true, `Execute complete: ${taskDirs.length} task(s) + verification proof.`);
+}
+
+/**
+ * Validates verify phase: proof exists and has substantive content.
+ */
+export function validateVerifyComplete(_state, runDir) {
+  const proofPath = path.join(runDir, 'artifacts', 'verification-proof.md');
+  if (!fileExistsAndNonEmpty(proofPath)) {
+    return result(false, 'Verification proof missing or empty.', ['artifacts/verification-proof.md']);
+  }
+
+  const content = fs.readFileSync(proofPath, 'utf8');
+  if (content.trim().length < 20) {
+    return result(false, 'Verification proof exists but has insufficient content.', ['artifacts/verification-proof.md']);
+  }
+
+  return result(true, 'Verification proof present with evidence.');
+}
+
+/**
+ * Validates review phase: verdict.json with a numeric score.
+ */
+export function validateReviewComplete(_state, runDir) {
+  const verdictPath = path.join(runDir, 'reviews', 'verdict.json');
+  if (!fs.existsSync(verdictPath)) {
+    return result(false, 'Review verdict missing.', ['reviews/verdict.json']);
+  }
+
+  try {
+    const verdict = JSON.parse(fs.readFileSync(verdictPath, 'utf8'));
+    if (typeof verdict.score !== 'number') {
+      return result(false, 'Review verdict has no numeric score.', ['reviews/verdict.json (missing score)']);
+    }
+    return result(true, `Review complete with score ${verdict.score}.`);
+  } catch {
+    return result(false, 'Review verdict is not valid JSON.', ['reviews/verdict.json']);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Dispatcher
+// ---------------------------------------------------------------------------
+
+const VALIDATORS = {
+  clarify: validateClarifyComplete,
+  execute: validateExecuteComplete,
+  verify: validateVerifyComplete,
+  review: validateReviewComplete,
+};
+
+/**
+ * Run the guardrail for a given phase.
+ */
+export function runGuardrail(phase, state, runDir) {
+  const validator = VALIDATORS[phase];
+  if (!validator) {
+    throw new Error(`Unknown phase for guardrail: ${phase}`);
+  }
+  return validator(state, runDir);
+}

package/tooling/src/guards/phase-prerequisite-guard.js

@@ -143,10 +143,42 @@ export function evaluatePhasePrerequisiteGuard(payload) {
   const requiredPhaseExits = prerequisites.required_phase_exits ?? [];
 
   const missingArtifacts = [];
+  const failedProofs = [];
   for (const artifact of requiredArtifacts) {
     const artifactPath = path.join(runPaths.runRoot, artifact);
     if (!fs.existsSync(artifactPath)) {
       missingArtifacts.push(artifact);
+      continue;
+    }
+
+    const basename = path.basename(artifact);
+
+    // Content validation for proof JSON files (e.g. proof-task-001.json, verification-proof.json)
+    if (basename.includes('proof') && basename.endsWith('.json')) {
+      try {
+        const content = fs.readFileSync(artifactPath, 'utf8');
+        const parsed = JSON.parse(content);
+        if (parsed.all_passed !== true) {
+          failedProofs.push(`${artifact}: all_passed is not true (got ${JSON.stringify(parsed.all_passed)})`);
+        }
+      } catch {
+        // Fail closed: malformed JSON blocks the phase
+        failedProofs.push(`${artifact}: malformed or unreadable JSON`);
+      }
+      continue;
+    }
+
+    // Content validation for verification-proof.md
+    if (basename === 'verification-proof.md') {
+      try {
+        const content = fs.readFileSync(artifactPath, 'utf8');
+        const lower = content.toLowerCase();
+        if (!lower.includes('status: pass') && !content.includes('PASS')) {
+          failedProofs.push(`${artifact}: does not contain "status: pass" or "PASS"`);
+        }
+      } catch {
+        failedProofs.push(`${artifact}: unreadable`);
+      }
     }
   }
 
@@ -158,10 +190,10 @@ export function evaluatePhasePrerequisiteGuard(payload) {
     }
   }
 
-  // OR-logic for resumed runs: if all artifacts exist, pass even without phase_exit events.
+  // OR-logic for resumed runs: if all artifacts exist and proofs pass, allow even without phase_exit events.
   // Artifacts are the hard evidence; phase_exits are supplementary.
-  // But if artifacts are missing, phase_exits alone are not sufficient.
-  if (missingArtifacts.length === 0) {
+  // But if artifacts are missing or proofs fail, phase_exits alone are not sufficient.
+  if (missingArtifacts.length === 0 && failedProofs.length === 0) {
     return {
       allowed: true,
       reason: `All prerequisite artifacts present for phase ${phase}.`,
@@ -172,6 +204,9 @@ export function evaluatePhasePrerequisiteGuard(payload) {
   if (missingArtifacts.length > 0) {
     reasons.push(`Missing artifacts: ${missingArtifacts.join(', ')}`);
   }
+  if (failedProofs.length > 0) {
+    reasons.push(`Failed proof validation: ${failedProofs.join('; ')}`);
+  }
   if (missingPhaseExits.length > 0) {
     reasons.push(`Missing phase exits: ${missingPhaseExits.join(', ')}`);
   }
@@ -180,6 +215,7 @@ export function evaluatePhasePrerequisiteGuard(payload) {
     allowed: false,
     reason: reasons.join('. '),
     missing_artifacts: missingArtifacts.length > 0 ? missingArtifacts : undefined,
+    failed_proofs: failedProofs.length > 0 ? failedProofs : undefined,
     missing_phase_exits: missingPhaseExits.length > 0 ? missingPhaseExits : undefined,
   };
 }