pan-wizard 3.5.2 → 3.8.0

package/pan-wizard-core/bin/pan-tools.cjs

@@ -209,6 +209,12 @@ const bridge = require('./lib/bridge.cjs');
 const optimize = require('./lib/optimize.cjs');
 const git = require('./lib/git.cjs');
 const distill = require('./lib/distill.cjs');
+const experiment = require('./lib/experiment.cjs');
+const runner = require('./lib/runner.cjs');
+const docLint = require('./lib/doc-lint.cjs');
+const learnLint = require('./lib/learn-lint.cjs');
+const learnIndex = require('./lib/learn-index.cjs');
+const links = require('./lib/links.cjs');
 
 /**
  * Get the value following a flag in the args array.
@@ -367,15 +373,92 @@ async function main() {
       break;
     }
 
+    case 'experiment': {
+      const subcommand = args[1];
+      if (!subcommand) { error('experiment subcommand required. Available: new, list, manifest, run, status, stop, harvest, prune'); }
+      const root = getArgValue(args, '--root');
+
+      if (subcommand === 'new') {
+        const slug = args[2];
+        if (!slug || slug.startsWith('--')) { error('experiment new <slug> required'); }
+        const ideaPath = getArgValue(args, '--idea');
+        if (!ideaPath) { error('experiment new requires --idea <path>'); }
+        const runtime = getArgValue(args, '--runtime', 'claude');
+        const budgetStr = getArgValue(args, '--budget');
+        const budget = budgetStr != null ? parseInt(budgetStr, 10) : null;
+        const skipInstaller = args.includes('--skip-installer');
+        const result = experiment.newExperiment(slug, { ideaPath, runtime, root, budget, skipInstaller });
+        output(result, raw);
+      } else if (subcommand === 'list') {
+        const includeArchived = args.includes('--include-archived');
+        const result = experiment.listExperiments({ root, includeArchived });
+        output(result, raw);
+      } else if (subcommand === 'manifest') {
+        const slug = args[2];
+        if (!slug || slug.startsWith('--')) { error('experiment manifest <slug> required'); }
+        const result = experiment.getExperimentManifest(slug, { root });
+        output(result, raw);
+      } else if (subcommand === 'run') {
+        const slug = args[2];
+        if (!slug || slug.startsWith('--')) { error('experiment run <slug> required'); }
+        const prompt = getArgValue(args, '--prompt');
+        const timeoutStr = getArgValue(args, '--timeout');
+        const timeoutMs = timeoutStr ? parseInt(timeoutStr, 10) * 1000 : undefined;
+        const runtimeOverride = getArgValue(args, '--runtime-override');
+        const runOpts = { root };
+        if (prompt) runOpts.prompt = prompt;
+        if (timeoutMs) runOpts.timeoutMs = timeoutMs;
+        if (runtimeOverride) {
+          // For tests/dev: override="bin:arg1,arg2" — split on first colon, args by comma
+          const [bin, argsCsv] = runtimeOverride.split(':', 2);
+          runOpts.runtimeOverride = {
+            bin,
+            buildArgs: () => (argsCsv ? argsCsv.split(',') : []),
+          };
+        }
+        const result = runner.runExperiment(slug, runOpts);
+        output(result, raw);
+      } else if (subcommand === 'status') {
+        const slug = args[2];
+        if (!slug || slug.startsWith('--')) { error('experiment status <slug> required'); }
+        const result = runner.tailExperimentState(slug, { root });
+        output(result, raw);
+      } else if (subcommand === 'stop') {
+        const slug = args[2];
+        if (!slug || slug.startsWith('--')) { error('experiment stop <slug> required'); }
+        const result = runner.stopExperiment(slug, { root });
+        output(result, raw);
+      } else if (subcommand === 'harvest') {
+        const slug = args[2];
+        if (!slug || slug.startsWith('--')) { error('experiment harvest <slug> required'); }
+        const sourceRoot = getArgValue(args, '--source-root');
+        const force = args.includes('--force');
+        const harvestOpts = { root, force };
+        if (sourceRoot) harvestOpts.sourceRoot = sourceRoot;
+        const result = experiment.harvestExperiment(slug, harvestOpts);
+        output(result, raw);
+      } else if (subcommand === 'prune') {
+        const slug = args[2];
+        if (!slug || slug.startsWith('--')) { error('experiment prune <slug> required'); }
+        const hard = args.includes('--hard');
+        const result = experiment.pruneExperiment(slug, { root, hard });
+        output(result, raw);
+      } else {
+        error(`unknown experiment subcommand: ${subcommand}. Available: new, list, manifest, run, status, stop, harvest, prune`);
+      }
+      break;
+    }
+
     case 'commit': {
       const amend = args.includes('--amend');
       const force = args.includes('--force');
+      const failOnError = args.includes('--fail-on-error');
       const message = args[1] && !args[1].startsWith('--') ? args[1] : null;
       // Parse --files flag (collect args after --files, stopping at other flags)
       const filesIndex = args.indexOf('--files');
       const files = filesIndex !== -1 ? args.slice(filesIndex + 1).filter(a => !a.startsWith('--')) : [];
       const commitType = getArgValue(args, '--type');
-      commands.cmdCommit(cwd, message, files, raw, amend, { type: commitType, force });
+      commands.cmdCommit(cwd, message, files, raw, amend, { type: commitType, force, failOnError });
       break;
     }
 
@@ -581,7 +664,8 @@ async function main() {
         const standardsFlag = args.includes('--standards');
         const fullFlag = args.includes('--full');
         const driftFlag = args.includes('--drift');
-        verify.cmdValidateHealth(cwd, { repair: repairFlag, standards: standardsFlag, full: fullFlag, drift: driftFlag }, raw);
+        const linksFlag = args.includes('--links');
+        verify.cmdValidateHealth(cwd, { repair: repairFlag, standards: standardsFlag, full: fullFlag, drift: driftFlag, links: linksFlag }, raw);
       } else if (subcommand === 'deployment') {
         verify.cmdValidateDeployment(cwd, raw);
       } else {
@@ -1079,14 +1163,174 @@ async function main() {
       break;
     }
 
+    case 'doc-lint': {
+      const subcommand = args[1];
+      if (subcommand === 'schema-check') {
+        const schemaPath = args[2];
+        if (!schemaPath || schemaPath.startsWith('--')) { error('doc-lint schema-check <path> required'); }
+        docLint.cmdDocLintSchemaCheck(cwd, schemaPath, { raw });
+        break;
+      }
+      if (subcommand === 'counts') {
+        const dir = args[2];
+        if (!dir || dir.startsWith('--')) { error('doc-lint counts <dir> required'); }
+        const exclude = [];
+        for (let k = 0; k < args.length; k++) if (args[k] === '--exclude') exclude.push(args[k + 1]);
+        docLint.cmdDocLintCounts(cwd, dir, { raw, exclude });
+        break;
+      }
+      // Default: lint a directory
+      const dir = args[1];
+      if (!dir || dir.startsWith('--')) { error('doc-lint <dir> required (or doc-lint schema-check <path>, doc-lint counts <dir>)'); }
+      const schema = getArgValue(args, '--schema');
+      const format = getArgValue(args, '--format', 'human');
+      const strict = args.includes('--strict');
+      const exclude = [];
+      for (let k = 0; k < args.length; k++) if (args[k] === '--exclude') exclude.push(args[k + 1]);
+      docLint.cmdDocLint(cwd, dir, { schema, format, strict, exclude: exclude.filter(Boolean), raw });
+      break;
+    }
+
     case 'learn': {
-      // Convenience alias: pan-tools learn = optimize learn
+      const subcommand = args[1];
+
+      // W4: pan-tools learn promote/unpromote/list-promoted (self-improvement loop)
+      if (subcommand === 'promote') {
+        const patternId = getArgValue(args, '--pattern');
+        if (!patternId) { error('learn promote requires --pattern <id>'); }
+        const scope = getArgValue(args, '--scope');
+        const topic = getArgValue(args, '--topic');
+        if (!scope) { error('learn promote requires --scope universal|internal'); }
+        if (!topic) { error('learn promote requires --topic <name>'); }
+        const summary = getArgValue(args, '--summary') || '';
+        const evidence = getArgValue(args, '--evidence') || '';
+        const rule = getArgValue(args, '--rule') || '';
+        const appliesIn = getArgValue(args, '--applies-in') || '';
+        const sourceExpsCsv = getArgValue(args, '--source-experiments') || '';
+        const sourceExperiments = sourceExpsCsv
+          ? sourceExpsCsv.split(',').map(s => s.trim()).filter(Boolean)
+          : [];
+        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+
+        const result = optimize.promotePattern(
+          { id: patternId, summary, evidence, rule, applies_in: appliesIn, source_experiments: sourceExperiments },
+          { scope, topic, sourceRoot }
+        );
+        output(result, raw);
+        break;
+      }
+
+      if (subcommand === 'unpromote') {
+        const patternId = getArgValue(args, '--pattern');
+        const scope = getArgValue(args, '--scope');
+        const topic = getArgValue(args, '--topic');
+        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        if (!patternId || !scope || !topic) {
+          error('learn unpromote requires --pattern <id> --scope <s> --topic <t>');
+        }
+        const result = optimize.unpromotePattern(patternId, { scope, topic, sourceRoot });
+        output(result, raw);
+        break;
+      }
+
+      if (subcommand === 'list-promoted') {
+        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const result = optimize.listPromotedPatterns({ sourceRoot });
+        output(result, raw);
+        break;
+      }
+
+      if (subcommand === 'build-index') {
+        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const result = learnIndex.cmdBuildIndex(sourceRoot);
+        if (raw) {
+          output(result, true,
+            `Index written: ${result.written_to}\n` +
+            `Topics: ${result.topics}\nPatterns: ${result.patterns}\n` +
+            `Total tokens (est): ${result.total_tokens_est.toLocaleString()}\n` +
+            `Schema version: ${result.schema_version}`);
+        } else {
+          output(result, false);
+        }
+        break;
+      }
+
+      if (subcommand === 'topics-for') {
+        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const agent = getArgValue(args, '--agent');
+        if (!agent) { error('learn topics-for requires --agent <name>'); }
+        const minRelevance = getArgValue(args, '--min-relevance', 'medium');
+        const tokenBudget = parseInt(getArgValue(args, '--token-budget', '5000'), 10);
+        const result = learnIndex.cmdTopicsFor(sourceRoot, { agent, minRelevance, tokenBudget });
+        if (raw) {
+          const lines = [`Topics for "${agent}" (min ${minRelevance}, budget ${tokenBudget}):`, ``];
+          for (const t of result.selected) {
+            lines.push(`  [${t.relevance.padEnd(6)}] ${t.scope}/${t.name.padEnd(22)} ${t.tokens.toString().padStart(5)}t   ${t.patterns.join(', ')}`);
+          }
+          lines.push(``, `Selected: ${result.selected.length} topics, ${result.total_tokens} tokens`);
+          if (result.dropped.length > 0) {
+            lines.push(`Dropped (over budget): ${result.dropped.length} — ${result.dropped.map(d => d.name).join(', ')}`);
+          }
+          output(result, true, lines.join('\n'));
+        } else {
+          output(result, false);
+        }
+        break;
+      }
+
+      if (subcommand === 'lint') {
+        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const scope = getArgValue(args, '--scope');
+        const strict = args.includes('--strict');
+        const result = learnLint.cmdLearnLint(sourceRoot, { scope, strict });
+        if (raw) {
+          const lines = [`Learn-Lint: ${result.summary.status.toUpperCase()}`,
+            ``,
+            `Patterns scanned: ${result.pattern_count} across ${result.file_count} files`,
+            `Errors:   ${result.summary.errors}`,
+            `Warnings: ${result.summary.warnings}`,
+            ``,
+          ];
+          for (const v of result.violations) {
+            lines.push(`[${v.severity.toUpperCase()}] ${v.code} ${v.pattern_id}: ${v.message}`);
+          }
+          output(result, true, lines.join('\n'));
+        } else {
+          output(result, false);
+        }
+        if (result.summary.status === 'fail') process.exit(1);
+        break;
+      }
+
+      // Default: convenience alias for optimize learn (existing behavior)
       optimize.cmdOptimizeLearn(cwd, {
         sessionId: getArgValue(args, '--session'),
       }, raw);
       break;
     }
 
+    case 'links': {
+      const subcommand = args[1];
+      if (subcommand === 'validate' || !subcommand) {
+        const collectMulti = (flag) => {
+          const vals = [];
+          for (let i = 0; i < args.length; i++) {
+            if (args[i] === flag && i + 1 < args.length) vals.push(args[i + 1]);
+          }
+          return vals.length ? vals : null;
+        };
+        const opts = {
+          docRoots: collectMulti('--doc-root'),
+          sourceRoots: collectMulti('--source-root'),
+          strict: args.includes('--strict'),
+          raw,
+        };
+        links.cmdLinksValidate(cwd, opts);
+        break;
+      }
+      error(`Unknown links subcommand: ${subcommand}. Available: validate`);
+    }
+
     default:
       error(`Unknown command: ${command}. Run pan-tools without arguments to see available commands.`);
   }

package/pan-wizard-core/learnings/README.md

@@ -0,0 +1,70 @@
+# Learnings (AI-derived patterns)
+
+This directory holds AI-derived behavioral patterns extracted from real PAN
+Wizard sessions via the **self-improvement loop** (v3.7.0+, see
+[ADR-0026](../../docs/decisions/ADR-0026-self-improvement-loop.md)).
+
+Patterns are produced by running `pan-tools learn promote --pattern <id>` over
+harvested experiment data. They are **advisory** — orchestrators weight them
+against current context, not as hard rules.
+
+## Two-tier layout
+
+| Tier | Path | Shipped to user installs? | Purpose |
+|------|------|---------------------------|---------|
+| **Universal** | `universal/` | ✅ yes | Patterns that generalize across projects (test conventions, commit hygiene, deviation rules). Workflows reference these. |
+| **Internal**  | `internal/`  | ❌ no  | PAN-development-specific patterns (installer quirks, source-repo conventions). Useful only when working on PAN itself. |
+
+The installer ships `learnings/universal/` to all 5 runtime install dirs
+(`.claude/`, `.codex/`, `.gemini/`, `.opencode/`, `.github/`) alongside
+`references/`. `learnings/internal/` is **never installed** — it stays in
+the source repo. Negative tests in
+`tests/scenarios/learnings-installed.test.cjs` enforce this.
+
+## Topic file structure
+
+Each topic file is markdown with YAML frontmatter:
+
+```markdown
+---
+topic: <name>
+last_updated: <ISO-8601>
+patterns:
+  - id: P-001
+    summary: <one-line>
+    promoted_at: <ISO-8601>
+    source_experiments: [<slug>, ...]
+---
+
+# <Topic Name> (AI-derived)
+
+## P-001 — <one-line>
+**Evidence:** <count> trace events across experiments <list>
+**Rule:** <imperative statement>
+**Applies in:** <workflow names>
+```
+
+## Lifecycle
+
+1. **Promote** — `pan-tools learn promote --pattern <id> --scope universal --topic <name>` appends a pattern to the topic file (creates the file if absent).
+2. **Unpromote** — `pan-tools learn unpromote --pattern <id> --topic <name>` removes a pattern (for rollback).
+3. **List** — `pan-tools learn list-promoted` shows the inventory across both tiers.
+
+## Why two tiers
+
+PAN-internal patterns risk being shipped as universal advice when they only
+apply when the project *is* PAN. Examples:
+
+- **PAN-internal**: "Always commit individually, never `git add -A`" (because of source repo's pre-commit hooks)
+- **Universal**: "Run the full test suite before marking a phase complete"
+
+The promote step uses a heuristic filter on file paths in the pattern's
+evidence. References to `pan-wizard-core/`, `bin/install.js`, `commands/pan/*`
+suggest `internal` scope. The human running `promote` makes the final call.
+
+## Maintenance
+
+These files are **AI-managed**. Direct human edits create drift between
+the frontmatter `pattern_ids` list and the body content. For human-authored
+behavioral content, use `references/` instead — that's the canonical
+hand-authored channel (e.g., `references/guardrails.md` shipped in v3.6.0).