pan-wizard 3.5.1 → 3.7.10

package/pan-wizard-core/learnings/universal/glob-semantics.md

@@ -0,0 +1,21 @@
+---
+topic: glob-semantics
+last_updated: 2026-04-27T09:49:20.726Z
+patterns:
+  - id: P-205
+    summary: Translate **/X glob to allow zero-segment match (root-level X), per gitignore/minimatch convention
+    promoted_at: 2026-04-27T09:49:20.726Z
+    source_experiments: [whooo]
+---
+
+# Glob Semantics (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-205 — Translate **/X glob to allow zero-segment match (root-level X), per gitignore/minimatch convention
+
+**Evidence:** whooo trace.jsonl 11:45Z (error major): globToRegex bug where **/foo.md regex required at least one slash so foo.md at root did not match. Fix: emit (?:.*/)? so the slash is optional. Caught by walk.test.js regression test.
+
+**Rule:** When implementing glob-to-regex translation, follow gitignore/minimatch convention: **/X must match BOTH dir/sub/X AND root-level X (the **/ segment can match zero path segments). Translate the **/ prefix to (?:.*/)?  NOT .*/ . The latter requires at least one slash and silently misses root-level files.
+
+**Applies in:** exec-phase (any glob/walker implementation), plan-phase (when planning file-walking tools)

package/pan-wizard-core/learnings/universal/idempotency.md

@@ -0,0 +1,21 @@
+---
+topic: idempotency
+last_updated: 2026-05-03T06:32:22.183Z
+patterns:
+  - id: P-IDEM-001
+    summary: Make resumable operations safe to retry by combining a deterministic action key, a check-before-do guard, and atomic state transitions — not retry counters
+    promoted_at: 2026-05-03T06:32:22.183Z
+    source_experiments: [external]
+---
+
+# Idempotency (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-IDEM-001 — Make resumable operations safe to retry by combining a deterministic action key, a check-before-do guard, and atomic state transitions — not retry counters
+
+**Evidence:** External research synthesis: AWS API design guidance (idempotency tokens), Google Cloud client-spec (request IDs), Stripe API (Idempotency-Key header), the database literature on exactly-once semantics. PAN's own dag-scheduler P-1206 retry-then-skip-downstream rule depends on tasks being retry-safe but never explains how to make them so. Real failure modes observed: a runner that re-creates a 'created_at' timestamp on retry breaks ordering; a CLI that re-pushes a commit on retry creates a divergent ref; an installer that re-copies on retry overwrites user edits if the destination has changed since the first attempt.
+
+**Rule:** For any operation that may run more than once (resumable pipeline, retry loop, dropped-network replay, user-triggered re-run): (1) compute a STABLE action key from the inputs (e.g. sha256 of the args), not from a timestamp or counter; (2) before executing, check whether the destination already reflects this exact action (file present with same hash, row present with same key, ref pointing where we want); (3) make the state transition atomically (write-tmp-then-rename per P-1201; INSERT … ON CONFLICT for SQL; CAS for in-memory); (4) on success record the action key so future retries short-circuit. Never use 'retry counter == N → skip' as your safety net — the counter resets on process restart but the side effect persists. Idempotency is a property of the OPERATION, not of a wrapper around it.
+
+**Applies in:** resumable installers, sync/upload jobs, replicated writes, message-queue consumers, retry middleware, CI rerun handling, any operation that crosses a network or process boundary and may be replayed

package/pan-wizard-core/learnings/universal/invariants.md

@@ -0,0 +1,21 @@
+---
+topic: invariants
+last_updated: 2026-04-27T10:50:44.078Z
+patterns:
+  - id: P-901
+    summary: Round-trip tests (parse(write(x)) === x) catch asymmetric escape/decode bugs in format converters
+    promoted_at: 2026-04-27T10:50:44.078Z
+    source_experiments: [whoocsv]
+---
+
+# Invariants (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-901 — Round-trip tests (parse(write(x)) === x) catch asymmetric escape/decode bugs in format converters
+
+**Evidence:** whoocsv sess_20260427T143000 14:34Z surprise: round-trip preserves data through commas/quotes/newlines. Single property test covers what 5 unit tests would
+
+**Rule:** When writing format converters (CSV, JSON, YAML, XML, custom), include at least one round-trip test: assert parse(write(input)) deepEquals input for a representative non-trivial input. Catches escape/decode asymmetries that unit tests miss.
+
+**Applies in:** exec-phase (any parser/serializer pair)

package/pan-wizard-core/learnings/universal/io-patterns.md

@@ -0,0 +1,21 @@
+---
+topic: io-patterns
+last_updated: 2026-04-27T10:15:00.878Z
+patterns:
+  - id: P-401
+    summary: Synchronous stdin via fs.readFileSync(0) is the cleanest CLI pattern
+    promoted_at: 2026-04-27T10:15:00.877Z
+    source_experiments: [whoosort]
+---
+
+# Io Patterns (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-401 — Synchronous stdin via fs.readFileSync(0) is the cleanest CLI pattern
+
+**Evidence:** whoosort sess_20260427T130000 11:06Z decision: sync matches CLI shape, eliminates buffering bugs, plays well with spawnSync({input}) for tests. Async stdin only justified for streaming gigabytes.
+
+**Rule:** When building a CLI that reads stdin, prefer fs.readFileSync(0, 'utf-8') over async stream consumption unless you actually need to process unbounded input. Sync I/O matches the shape of node-test spawnSync({input}), avoids buffering bugs, and keeps the CLI synchronous-by-default which simplifies error handling.
+
+**Applies in:** exec-phase (CLI implementation), test-strategy (subprocess testing of stdin-driven tools)

package/pan-wizard-core/learnings/universal/numeric-edge-cases.md

@@ -0,0 +1,21 @@
+---
+topic: numeric-edge-cases
+last_updated: 2026-04-27T10:22:49.117Z
+patterns:
+  - id: P-601
+    summary: Test numeric-scaling code with all-equal-values, single-value, zero, and mixed-sign edge cases
+    promoted_at: 2026-04-27T10:22:49.117Z
+    source_experiments: [whoograph]
+---
+
+# Numeric Edge Cases (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-601 — Test numeric-scaling code with all-equal-values, single-value, zero, and mixed-sign edge cases
+
+**Evidence:** whoograph sess_20260427T133500 13:38Z error (major): scaleBars all-equal branch was bypassed because Math.max(...values, 0) inflated min/max range. Test 'zero range -> all bars length 1' caught it.
+
+**Rule:** When implementing numeric scaling/normalization code (charts, percentages, ratios, gradients), write tests for ALL of: empty input, single value, all-equal values, all-zero values, mixed-sign values, and extreme range. The all-equal case is the most commonly missed because synthetic test data tends to have variation. Treat all-equal as a deliberate special case (visual indicator-only bars), not as a math edge case to silently absorb.
+
+**Applies in:** exec-phase (any visualization, normalization, or scoring code)

package/pan-wizard-core/learnings/universal/output-conventions.md

@@ -0,0 +1,21 @@
+---
+topic: output-conventions
+last_updated: 2026-04-27T10:15:00.961Z
+patterns:
+  - id: P-402
+    summary: Always emit a trailing newline from CLI output
+    promoted_at: 2026-04-27T10:15:00.960Z
+    source_experiments: [whoosort]
+---
+
+# Output Conventions (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-402 — Always emit a trailing newline from CLI output
+
+**Evidence:** whoosort 13:12Z gap: trailing-newline convention enforced in joinLines but not documented in --help. Most Unix tools do this; downstream tooling expects it.
+
+**Rule:** CLI tools should always emit a trailing newline at the end of output unless the user explicitly opts out. Mirrors POSIX text-file convention and matches downstream expectations (pipes, byte counters, line counters). Document the behavior in --help and tests can assert it deterministically.
+
+**Applies in:** exec-phase (CLI implementation)

package/pan-wizard-core/learnings/universal/parser-design.md

@@ -0,0 +1,21 @@
+---
+topic: parser-design
+last_updated: 2026-05-02T15:25:33.484Z
+patterns:
+  - id: P-1203
+    summary: Compile-once / evaluate-many: parse user predicates/keys/queries into a closure or AST at startup, reuse on every row. 10-100x speedup vs re-parsing per row
+    promoted_at: 2026-05-02T15:25:33.484Z
+    source_experiments: [whoolog, whoodb, whooschema]
+---
+
+# Parser Design (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-1203 — Compile-once / evaluate-many: parse user predicates/keys/queries into a closure or AST at startup, reuse on every row. 10-100x speedup vs re-parsing per row
+
+**Evidence:** whoolog where.js, resolve-key.js, time-filter.js: each compiles once and exports a closure. whoodb lexer/parser/analyzer is a 3-stage compile-once pipeline. Phase 1-02 summary: '109 lines: compileWhere(expr), lex(expr), parseRhs(raw). Operator order locked.' Performance contract: filter 1M lines in <10s requires this discipline.
+
+**Rule:** When user input (a where-expr, a dotted key path, a SQL query, a regex) will be evaluated against many rows, parse it ONCE into a callable (closure, AST, or compiled regex), then call repeatedly. Don't re-tokenize/re-parse inside the per-row hot loop. Examples: whoolog compileKey('a.b.c') returns row => row.a?.b?.c; compileWhere('level=error') returns row => row.level === 'error'. Type-aware equality via JSON.stringify when comparing user-supplied literals to JSON values keeps the evaluator simple.
+
+**Applies in:** predicate/expression evaluators, query engines, validators with reusable schema

package/pan-wizard-core/learnings/universal/phase-locking.md

@@ -0,0 +1,21 @@
+---
+topic: phase-locking
+last_updated: 2026-05-02T17:52:25.816Z
+patterns:
+  - id: P-1208
+    summary: Lock cross-cutting decisions (module system, error contract, exit codes) in Plan 01 of Phase 1; downstream plans IMPORT from those locked modules instead of re-deciding
+    promoted_at: 2026-05-02T17:52:25.816Z
+    source_experiments: [whooflow, whoocache]
+---
+
+# Phase Locking (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-1208 — Lock cross-cutting decisions (module system, error contract, exit codes) in Plan 01 of Phase 1; downstream plans IMPORT from those locked modules instead of re-deciding
+
+**Evidence:** whooflow Plan 01-01 summary: 'ESM lock-in committed in package.json — no later plan revisits the module system question. Node 18.17 floor encoded — first cross-cutting prerequisite from context.md is satisfied. Error -> exit-code contract (CLI-10) defined and tested; Plans 02-05 import from src/errors.js instead of redefining.' whoocache 02-composition: 'lock.js: no-op pass-through shim; signature locked for Phase 2 body swap.' Both shipped clean phases without cross-plan rework.
+
+**Rule:** When breaking work into multi-plan phases, the FIRST plan should establish cross-cutting contracts that all later plans depend on: package.json type (CJS vs ESM), Node version floor, error class hierarchy, exit code map. Use a 'pass-through shim' for forward-locked APIs — write the function signature in Plan 01 returning a no-op or pass-through, swap the body in Plan N. This prevents cross-plan churn ('which error format does plan 03 use?') and means plans can be revised in isolation.
+
+**Applies in:** multi-plan phases, multi-module CLIs, any work decomposable into a stable foundation + extensions

package/pan-wizard-core/learnings/universal/pipe-friendly-cli.md

@@ -0,0 +1,21 @@
+---
+topic: pipe-friendly-cli
+last_updated: 2026-05-02T17:52:45.798Z
+patterns:
+  - id: P-1207
+    summary: Pipe-friendly CLI: handle EPIPE as exit-0, read stdin only when not a TTY, write one record per line with trailing newline
+    promoted_at: 2026-05-02T17:52:45.798Z
+    source_experiments: [whoolog, whoodb]
+---
+
+# Pipe Friendly Cli (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-1207 — Pipe-friendly CLI: handle EPIPE as exit-0, read stdin only when not a TTY, write one record per line with trailing newline
+
+**Evidence:** whoolog bin/whoolog.js: 67 lines including shebang, EPIPE-as-exit-0 handler, top-level help, subcommand dispatch. lib/source.js: Stdin only when not a TTY. Stream errors converted to clean exit 1 with stderr message. Verified by integration tests piping through head and confirming exit 0.
+
+**Rule:** CLIs that compose with shell pipes need three behaviors: 1) EPIPE on stdout means downstream closed early (e.g. head -3 took 3 lines and exited) — listen for process.stdout error event, exit 0 not 1. 2) Read stdin ONLY when process.stdin.isTTY is false; if a TTY, stdin blocks waiting for typing. Use an explicit --files flag for files, fall back to stdin only when piped in. 3) Always write trailing newline (process.stdout.write(line + LF), not just line) so the next pipe stage sees a complete record.
+
+**Applies in:** any zero-dep Node.js CLI intended for shell composition

package/pan-wizard-core/learnings/universal/schema-design.md

@@ -0,0 +1,21 @@
+---
+topic: schema-design
+last_updated: 2026-04-27T09:48:41.048Z
+patterns:
+  - id: P-202
+    summary: Infer schemas from real-file sampling pass; do not author them from imagination
+    promoted_at: 2026-04-27T09:48:41.048Z
+    source_experiments: [whooo]
+---
+
+# Schema Design (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-202 — Infer schemas from real-file sampling pass; do not author them from imagination
+
+**Evidence:** whooo trace.jsonl 11:52Z (gap major) and 11:53Z (gap minor): hand-authored name pattern rejected 44/52 PAN command files using pan: prefix; argument-hint field present in 30+ files was missing from schema entirely. 30+ unknown-field warnings as a result.
+
+**Rule:** When authoring a schema for an existing corpus, run a sampling pass first: extract observed fields and value patterns from representative real files, THEN write the schema. Manual schemas guarantee a mismatch with reality. Provide a schema generate dir capability for any corpus-validation tool.
+
+**Applies in:** plan-phase (designing validation tooling), exec-phase (schema authoring)

package/pan-wizard-core/learnings/universal/secret-handling.md

@@ -0,0 +1,21 @@
+---
+topic: secret-handling
+last_updated: 2026-05-03T06:32:54.332Z
+patterns:
+  - id: P-SEC-001
+    summary: Treat secrets as a typed boundary, not a string — redact at the logger, deny-list at the committer, never round-trip through prose-serialized state
+    promoted_at: 2026-05-03T06:32:54.332Z
+    source_experiments: [external]
+---
+
+# Secret Handling (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-SEC-001 — Treat secrets as a typed boundary, not a string — redact at the logger, deny-list at the committer, never round-trip through prose-serialized state
+
+**Evidence:** External research synthesis: OWASP Top-10 A02 (Cryptographic Failures), GitGuardian / TruffleHog state-of-secrets reports (2025: ~24M leaked credentials/year, half from logs and CI artifacts), Google Cloud Secret Manager design notes, the post-mortems of Stripe-key-in-stripe.com-Sentry incident (2017) and Uber GitHub key leak (2016). PAN-relevant baseline: PAN ships harvest.json that captures process output verbatim; pan-tools commit warns about .env (string match) but no agent codifies the rule. Internal observation: the recent notepadrs experiment harvested optimization traces (~100s of agent IO events) directly into the source repo without a redaction pass — fine for this experiment, dangerous as a general pattern as experiments grow to authenticated workflows.
+
+**Rule:** Secrets must be three things at once: (1) a TYPED VALUE, not a string — wrap as Secret<T> / SecretString / opaque struct so toString() returns '[REDACTED]' and Display/Debug/JSON-serialize all respect the type. (2) DENY-LISTED at the persistence boundary — committer/publisher/uploader runs a regex sweep for known secret SHAPES (AWS AKIA, ghp_, sk-, JWT 3-part base64, PEM blocks, generic high-entropy 32+ char strings) AND a path deny-list (.env, *.pem, *.p12, credentials.json, config.local.*). Match → block, not warn. (3) NEVER ROUND-TRIPPED THROUGH PROSE STATE — agent traces, summary.md, harvest.json, plan.md must scrub secret-shaped tokens before write. Read-time scrubbing is not enough; an attacker who steals the file before scrubbing has the secret. Final rule: if a value is a secret, it goes through ONE pipe (env var → in-memory typed wrapper → consumer) and NEVER lands on disk under a path the committer can reach.
+
+**Applies in:** any tool that captures process output (loggers, harvest, trace captures, AI agent transcripts), any tool that writes commits or publishes artifacts (git committers, npm/cargo publish, CI artifact uploaders), any framework that serializes state to disk (orchestrators, schedulers, replay buffers), any external integration handler

package/pan-wizard-core/learnings/universal/streaming-io.md

@@ -0,0 +1,21 @@
+---
+topic: streaming-io
+last_updated: 2026-05-02T15:25:23.330Z
+patterns:
+  - id: P-1202
+    summary: Streaming JSONL via readline + for-await: per-line parse, never load whole file. Handles 100MB / 1M-line files in seconds without OOM
+    promoted_at: 2026-05-02T15:25:23.330Z
+    source_experiments: [whoolog, whoodb]
+---
+
+# Streaming Io (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-1202 — Streaming JSONL via readline + for-await: per-line parse, never load whole file. Handles 100MB / 1M-line files in seconds without OOM
+
+**Evidence:** whoolog source.js + filter.js processed 1M-line synthetic fixture in <10s with stable memory. whoodb evaluator uses the same pattern for streaming WHERE/projection. Both verified against real PAN tokens.jsonl.
+
+**Rule:** For line-oriented inputs (JSONL, NDJSON, log files), use Node's readline.createInterface({input: createReadStream(path)}) with for-await-of iteration. Each line parses independently — malformed lines emit a stderr warning and continue, unless --strict. NEVER use fs.readFileSync(path).split('\n') for files of unknown size. Pair with a streaming output (process.stdout.write(JSON.stringify(row) + '\n')) so the whole pipeline is bounded memory.
+
+**Applies in:** JSONL processors, log filters, line-oriented data tools

package/pan-wizard-core/learnings/universal/test-patterns.md

@@ -0,0 +1,57 @@
+---
+topic: test-patterns
+last_updated: 2026-05-03T03:29:54.837Z
+patterns:
+  - id: P-001
+    summary: Assert non-deterministic CLI output by SHAPE not VALUE
+    promoted_at: 2026-04-27T09:26:19.280Z
+    source_experiments: [whooo]
+  - id: P-002
+    summary: Use execFileSync over execSync for CLI subprocess tests
+    promoted_at: 2026-04-27T09:26:26.755Z
+    source_experiments: [whooo]
+  - id: P-204
+    summary: Test the violation/error CONTRACT (codes + field names + severity), not message prose
+    promoted_at: 2026-04-27T09:49:02.194Z
+    source_experiments: [whooo]
+  - id: P-NPRS-004
+    summary: Pure-logic helper extracted from side-effect wrapper makes Win32/IO/network code testable without a real environment
+    promoted_at: 2026-05-03T03:29:54.837Z
+    source_experiments: [notepadrs]
+---
+
+# Test Patterns (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-001 — Assert non-deterministic CLI output by SHAPE not VALUE
+
+**Evidence:** whooo build: a naive test asserting the exact ISO timestamp would have been flaky on every run. Asserting the regex shape /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z/ catches output regressions without flakiness.
+
+**Rule:** When testing CLI output that contains non-deterministic data (timestamps, UUIDs, hashes, PIDs, paths), assert the SHAPE of the output via regex rather than the exact value. The shape is the contract; the value is incidental.
+
+**Applies in:** exec-phase, focus-exec, plan-phase (when planning test cases)
+
+## P-002 — Use execFileSync over execSync for CLI subprocess tests
+
+**Evidence:** whooo test/whooo.test.js used execFileSync('node', [BIN]) directly. Cross-platform safe, no shell-injection surface, no dependency on shell behavior.
+
+**Rule:** When testing CLI binaries via subprocess, use execFileSync(bin, args) rather than execSync('command string'). execFileSync skips the shell, avoids shell-injection risk, and is portable across Windows/Unix without quoting differences.
+
+**Applies in:** exec-phase (writing tests), test-file generation in plan-phase
+
+## P-204 — Test the violation/error CONTRACT (codes + field names + severity), not message prose
+
+**Evidence:** whooo trace.jsonl 11:40Z (decision minor): Tests assert violation SHAPE not exact string messages. Cites P-001 and explicitly generalizes the timestamp-shape principle. All 9 validate.test.js tests follow this pattern: they assert code, field, severity but never the message text.
+
+**Rule:** When testing structured error/violation/diagnostic output of the form {file, line, code, message, severity, ...}, assert on the stable contract fields (code, field, severity, type) and NEVER on the human-readable message text. Messages evolve for clarity; codes are the API consumers depend on. Generalizes P-001 (timestamp-shape): same principle, broader application.
+
+**Applies in:** exec-phase (writing tests for any tool emitting structured diagnostics), plan-phase (test-case design)
+
+## P-NPRS-004 — Pure-logic helper extracted from side-effect wrapper makes Win32/IO/network code testable without a real environment
+
+**Evidence:** notepadrs recurring split: dispatch_pure.rs (decision logic) + dispatch.rs (Win32 wiring); decide_next_wrap_state (pure) + apply_wrap (unsafe Win32); tab_close_decision pure fn + Tab Drop impl; categorize_open_error (pure) + open_path_external (Win32). 109 tests in Phase 2; 35 gap-coverage tests in Phase 3 verification — almost all hit the pure helpers headlessly via cargo test, no Windows desktop required.
+
+**Rule:** When you write a function that mixes a NON-OBVIOUS DECISION (what to do) with a SIDE EFFECT (Win32 message, file write, network call), split it into two functions in two files: foo_pure.rs::decide_foo(&inputs) -> FooDecision (pure, headless-testable) + foo.rs::apply_foo(&hwnd_or_handle, decision) (the unsafe / I/O effect). Test the decision exhaustively at the unit layer; cover the wrapper with a thin smoke test (or skip it if it's just 5 lines of API plumbing). Cost: one extra file per side-effect family. Payoff: cargo test / npm test stays fast and reproducible across platforms, and the decision logic gets the test density it deserves.
+
+**Applies in:** Win32 message dispatch, IPC handlers, network request encoding, database query construction, any code that mixes decision logic with a side effect

package/pan-wizard-core/learnings/universal/test-strategy.md

@@ -0,0 +1,33 @@
+---
+topic: test-strategy
+last_updated: 2026-04-27T10:25:32.100Z
+patterns:
+  - id: P-201
+    summary: Test parsers and validators against real-world corpus fixtures from day one, not synthetic ones
+    promoted_at: 2026-04-27T09:48:31.640Z
+    source_experiments: [whooo]
+  - id: P-701
+    summary: When all tests pass first-run on a non-trivial build, that's a saturation signal — promoted patterns are constraining the design space
+    promoted_at: 2026-04-27T10:25:32.100Z
+    source_experiments: [whoodiff]
+---
+
+# Test Strategy (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-201 — Test parsers and validators against real-world corpus fixtures from day one, not synthetic ones
+
+**Evidence:** whooo sess_20260427T113000 trace.jsonl 11:50Z surprise event: 252 errors on PAN dogfood despite 39/39 unit tests passing. Synthetic fixtures gave false green light; the block-style YAML list scope-cut in DESIGN_SPEC was wrong but invisible to unit tests.
+
+**Rule:** When building any parser, validator, or schema-checker for a structured format, include at least one fixture sampled DIRECTLY from the real-world corpus before declaring v1 done. The dogfood gate runs BEFORE asserting passed, not after. Synthetic fixtures lie; real-corpus fixtures don't.
+
+**Applies in:** plan-phase (fixture planning), exec-phase (parser/validator implementation), verify-phase (gate definition)
+
+## P-701 — When all tests pass first-run on a non-trivial build, that's a saturation signal — promoted patterns are constraining the design space
+
+**Evidence:** whoodiff sess_20260427T135000 13:57Z surprise: 12 tests, all passed first run, zero deviations during a multi-file build with diff/format/parser logic. With 9 prior universal patterns (P-201..P-205, P-401..P-403, P-501, P-602) acting as default behavior, the space of wrong choices is heavily constrained. Compare to whooo (first run: 8 unit tests passed but 252 errors on dogfood) and whoosort (1 deviation).
+
+**Rule:** Track per-experiment 'first-run pass rate' (% of tests passing without iteration) as a quality signal for the promote pipeline. Rising rate = patterns are saturating; design space is shrinking. Falling rate = need more diverse experiments to surface new failure modes. Saturation isn't slowdown — it's the point: the loop's job is to convert lessons into defaults, then the defaults work invisibly.
+
+**Applies in:** promote workflow, /pan:learn analysis, post-experiment retrospective

package/pan-wizard-core/learnings/universal/unicode.md

@@ -0,0 +1,21 @@
+---
+topic: unicode
+last_updated: 2026-04-27T10:53:02.556Z
+patterns:
+  - id: P-1001
+    summary: JS string .length counts UTF-16 code units, not characters; surrogate pairs are length 2 but visually one character
+    promoted_at: 2026-04-27T10:53:02.556Z
+    source_experiments: [whooemoji]
+---
+
+# Unicode (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-1001 — JS string .length counts UTF-16 code units, not characters; surrogate pairs are length 2 but visually one character
+
+**Evidence:** whooemoji 14:52Z surprise: rocket emoji is one emoji but '🚀'.length === 2. Test asserts both invariants explicitly to document the trap.
+
+**Rule:** When code reasons about string length for VISUAL/USER-FACING purposes (column alignment, character limits, truncation), do NOT use String.prototype.length — it counts UTF-16 code units. Use [...str].length for code points (still wrong for grapheme clusters but better) or Intl.Segmenter for proper graphemes. When length must match user expectation (e.g. social-media char counts), document which definition you're using.
+
+**Applies in:** exec-phase (any code that handles user-facing strings: CLIs, validators, formatters, truncators)

package/pan-wizard-core/learnings/universal/vendor-pattern.md

@@ -0,0 +1,21 @@
+---
+topic: vendor-pattern
+last_updated: 2026-04-27T10:28:48.403Z
+patterns:
+  - id: P-801
+    summary: Vendoring small zero-dep modules into a project's bin/lib/ subdirectory works for downstream consumers without npm dep
+    promoted_at: 2026-04-27T10:28:48.403Z
+    source_experiments: [whoorun]
+---
+
+# Vendor Pattern (AI-derived)
+
+> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
+
+## P-801 — Vendoring small zero-dep modules into a project's bin/lib/ subdirectory works for downstream consumers without npm dep
+
+**Evidence:** whoorun sess_20260427T140500 14:08Z surprise (critical): META test passed first try. lib/taskfile.js requires d:/PanWizard/pan-wizard-core/bin/lib/doc-lint/frontmatter.js by absolute path. The vendored module: exists at the documented location, exports the documented API (parseFrontmatter), parses real task-file frontmatter correctly. No npm dep, no symlink, no package.json magic.
+
+**Rule:** When a project ships a small (<300 LOC), zero-dep, structure-stable module that's likely to be useful to downstream consumers (parser, validator, formatter), vendor it under bin/lib/<topic>/ and document the require path. The vendor pattern works as an alternative to publishing-as-npm when (a) the module's surface is small, (b) the consumer can pin to a specific source-repo path, and (c) the project doesn't want the maintenance overhead of a separate package. Trade-off: consumers must update manually when the upstream module changes — versioned by the parent project's release tag.
+
+**Applies in:** v3.7.x design (PAN's doc-lint vendor pattern), v3.8+ when shipping more vendored utilities

package/pan-wizard-core/references/guardrails.md

@@ -0,0 +1,58 @@
+# AI Agent Guardrails for PAN Wizard
+
+This document is read by AI agents (Claude, Codex, Gemini, OpenCode, Copilot)
+executing PAN workflows. It encodes rules that prevent the most common shortcut
+failures observed across PAN Wizard development. Re-read at the start of every
+phase — context compaction may have dropped earlier sections.
+
+## Common Shortcuts to Resist
+
+| Shortcut | Why it fails | Correct action |
+|----------|--------------|----------------|
+| "User's request is clear, no need to clarify" | You're guessing at intent. Phase 0 catches misunderstandings before scaffolding. | Run the Phase 0 4-question check (see `new-project.md` / `plan-phase.md`). |
+| "Phase tests passed locally, /pan:verify-phase isn't needed" | One run isn't validation. verify-phase checks state consistency, doc sync, blockers, and the full suite — not just the phase's own tests. | Always run `/pan:verify-phase` before marking a phase complete. |
+| "I'll skip /pan:focus-scan and pick the next item myself" | Manual selection ignores priority/budget logic in `focus.cjs`. You'll bias toward easy items and miss higher-priority work. | Use `/pan:focus-scan` → `/pan:focus-plan` → `/pan:focus-exec`. |
+| "I'll bump the model / add a flag / refactor while I'm here" | Scope creep. The user asked for one change; surrounding cleanup belongs in a separate item. | Do only the requested change. Note unrelated cleanup as a TODO for a future focus-scan. |
+| "I'll mark this phase complete; the docs can lag behind" | Doc/state drift compounds. By the next session, the agent reads stale docs and proceeds on false assumptions. | Run `/pan:sync` (or the equivalent doc-sync step) before phase completion. CHANGELOG and version bumps are part of the phase, not after it. |
+
+## Code Preservation Principle
+
+Code modifications require surgical precision — alter only the lines directly
+targeted by the user's request. Strictly preserve all surrounding code.
+
+Before finalizing any edit, verify:
+
+1. **Target identification** — the exact lines to change, based solely on the user's instructions
+2. **Preservation check** — all code, config values (model, version, api_key), comments, and formatting outside the target are identical
+
+If you must touch surrounding code (e.g., to fix an import a rename broke),
+name it explicitly in your reply: "Also updating import in X because the
+rename broke it." Never silently expand scope.
+
+## Stop-the-Line Rule
+
+If a change breaks something that was working: **stop feature work and fix
+the regression first.** Do not push forward with "I'll circle back" —
+regressions compound across sessions and become 10x harder to localize later.
+
+A failing test, a broken command, or a manifest-checksum mismatch is a
+stop-the-line event. Resume feature work only after the line is restored.
+
+## Systematic Debugging Sequence
+
+When something breaks, follow this sequence — don't shotgun fixes:
+
+1. **Reproduce** — exact failing command, full error output
+2. **Localize** — narrow to module, config, or environment
+3. **Fix one variable at a time** — changing instruction + tool + config simultaneously means you won't know what fixed it
+4. **Verify** — rerun the exact reproduction command
+5. **Guard** — if the bug was non-obvious, add a test to catch regressions
+
+## Cross-References
+
+- `references/tdd.md` — test-driven development patterns
+- `references/verification-patterns.md` — phase verification methodology
+- `references/checkpoints.md` — human-in-the-loop checkpoint protocol
+- `workflows/exec-phase.md` — phase execution checklist
+- `workflows/verify-phase.md` — phase completion validation
+- `workflows/plan-phase.md` — phase planning and decomposition

package/pan-wizard-core/references/handoff-decisions.md

@@ -0,0 +1,156 @@
+# Handoff Decisions Reference (P-RES-003)
+
+This reference defines the schema for the **decisions trace** that flows
+through PAN's serial pipeline:
+
+```
+planner ─[plan.md "Plan Decisions"]──▶ executor ─[summary.md "Implementation Decisions"]──▶ verifier
+```
+
+## Why this exists
+
+Cognition's "Don't build multi-agents" (Jun 2025) named the dominant failure
+mode of pipeline-based AI: parallel sub-agents fail because every action
+encodes unstated decisions that downstream agents reconcile blindly.
+Anthropic's countervailing piece argues breadth-first **reads** parallelize
+fine but **writes** need a single coherent trace. PAN is mostly serial, but
+its file-mediated handoff carried only **artifacts** (plan.md, summary.md) —
+not the **reasoning** behind them. This reference fixes that without changing
+the file contract: it adds a structured section to each artifact that captures
+what would otherwise stay in the agent's head.
+
+## Schema — `## Plan Decisions` (planner → executor handoff)
+
+Lives in `plan.md`, between `<objective>` and `<tasks>`:
+
+```markdown
+## Plan Decisions
+
+### Locked (executor MUST follow)
+- D-1: <statement>. Why: <rationale>. Source: <context.md REQ-X | research.md | architecture constraint>.
+
+### Open (executor's discretion within constraints)
+- O-1: <decision space>. Constraints: <list>. Reason left open: <why planner did not lock>.
+
+### Considered and rejected
+- R-1: <alternative>. Rejected because: <reason>.
+```
+
+If the plan is mechanical and there genuinely are no notable decisions, write
+this single line instead of empty buckets:
+
+```markdown
+## Plan Decisions
+
+No decisions worth documenting — plan is mechanical implementation of must_haves.
+```
+
+### Bucket semantics
+
+- **Locked** — Constraints the executor MUST follow. If the executor
+  diverges, that's a deviation and must be logged in the summary.
+  Examples: library choice, security pattern, naming convention,
+  protocol shape, error-handling style.
+
+- **Open** — Choices left to the executor's judgment, but bounded.
+  The planner names the decision space and the constraints; the
+  executor picks within them. The executor should log which option
+  they took in the summary's `Decisions Taken`.
+  Example: "Hashing algorithm: bcrypt | argon2 | scrypt. Constraint:
+  zero-deps Node builtin. Reason left open: equivalent for this use case."
+
+- **Considered and rejected** — Alternatives the planner explored and
+  ruled out. Helps the executor avoid re-deriving the same path and
+  helps the verifier understand why the implementation looks the way
+  it does.
+
+### When to use each bucket
+
+| Bucket | When to fill |
+|--------|--------------|
+| Locked | Anything where executor divergence would break the plan |
+| Open | Decisions where multiple correct answers exist; executor picks |
+| Considered/rejected | Significant alternatives explored — only meaningful ones (not "I considered any random thing") |
+
+## Schema — `## Implementation Decisions` (executor → verifier handoff)
+
+Lives in `summary.md`, after `## Files Changed`:
+
+```markdown
+## Implementation Decisions
+
+### Taken (within plan's discretion)
+- DT-1: Chose <option> for O-N. Reason: <rationale>.
+
+### Deviations (from plan; must explain)
+- DV-1: Plan said <X>; I did <Y>. Reason: <rationale>. Verification: <how I confirmed Y is acceptable>.
+
+### Open questions for verifier
+- Q-1: <question>. Why it matters: <stake>.
+```
+
+If implementation followed plan exactly with no notable items:
+
+```markdown
+## Implementation Decisions
+
+No deviations or open questions — implementation followed plan exactly.
+```
+
+### Bucket semantics
+
+- **Taken** — Which option the executor picked for each `Open` (O-N)
+  decision the plan declared. Reference the original `O-N` ID so the
+  verifier can cross-check.
+
+- **Deviations** — Where the executor departed from a `Locked` (D-N)
+  decision. Must include the reason AND a verification step (how the
+  executor confirmed the deviation is acceptable). Without the
+  verification step, this is just an unauthorized change — the verifier
+  should treat such a deviation as a finding.
+
+- **Open questions for verifier** — Decisions the executor consciously
+  punted to the verifier. NOT a substitute for the existing verification
+  dimensions; an EXTRA focus area. The verifier uses these to know
+  where to spend extra attention.
+
+## Reading order for downstream agents
+
+- **Executor**, before writing any code:
+  1. Read `## Plan Decisions` first
+  2. Internalize the Locked bucket as constraints
+  3. Note Open decisions to revisit when those task lines come up
+  4. Skim Considered/rejected to avoid re-deriving rejected alternatives
+
+- **Verifier**, before checking the code:
+  1. Read `## Implementation Decisions` from each plan's summary
+  2. For each Deviation, verify the executor's stated verification
+  3. For each Open Question, spend extra time on that area
+  4. Cross-reference Decisions Taken against the plan's Open bucket
+     (every plan-declared `O-N` should have a corresponding `DT-N` or
+     have been mooted)
+
+## Empty-bucket discipline
+
+The schema MUST be machine-parseable. Forbidden:
+
+- Section header present, all buckets silently empty (no "no decisions" line)
+- Bucket header present with no items and no parenthetical "(none)"
+- Out-of-order buckets
+
+`pan-plan-checker` Dimension 12 (P-RES-003) enforces this on the planner side.
+
+## Versioning
+
+Schema version: v1 (introduced v3.7.10).
+
+If this schema ever changes, add a `decisions_schema: v2` field to the
+plan.md frontmatter and document the new shape here. Older plans without
+that field default to v1.
+
+## Source
+
+- Cognition, "Don't Build Multi-Agents" (Jun 2025): https://cognition.ai/blog/dont-build-multi-agents
+- Anthropic, "How we built our multi-agent research system": https://www.anthropic.com/engineering/multi-agent-research-system
+- Internal: `pan-wizard-core/learnings/internal/external-research.md` P-RES-003
+- Spec: this reference doc IS the spec; no separate doc.