voidforge-build 23.9.1 → 23.10.0

package/dist/.claude/agents/kusanagi-devops.md

@@ -57,6 +57,14 @@ Structure all findings as:
 - **Run test suite before deploy, not just build:** `npm test` (or equivalent) is a mandatory pre-flight check alongside `npm run build`. Broken tests can ship silently if only the build is verified — 4 broken tests shipped across 3 commits before being caught by a review agent. (Field report #298.)
 - **CronCreate `durable` flag silently fails:** The cron appears created but doesn't survive session end. For persistent operations, use OS-level crons (launchd on macOS, systemd timers on Linux) calling the `claude` CLI directly.
 
+### Cloudflare Pages Dev Mode + Purge Everything may not evict all cache
+
+For time-critical cache evictions (post-credential-rotation, post-content-correction), combine Purge Everything + Custom Purge by URL + Dev Mode, then wait at least TTL + 60 seconds. A single purge is often insufficient across Cloudflare's PoP network; second Custom Purge + wait is frequently required.
+
+- **Evidence:** Field report #305 — credential-leak remediation required multiple purge passes before all PoPs served rotated content.
+- **Action:** Time-critical evictions: Purge Everything → Custom Purge URL → Dev Mode on → wait TTL+60s → re-verify. If stale, repeat Custom Purge + wait.
+- **Scope:** Any Cloudflare Pages or Cloudflare CDN deploy where stale content has real cost (security, correctness).
+
 ## Required Context
 
 For the full operational protocol, load: `/docs/methods/DEVOPS_ENGINEER.md`

package/dist/.claude/agents/leia-secrets.md

@@ -36,6 +36,16 @@ Secrets audit:
 - **Rotation Risk**: Secrets that cannot be rotated without downtime
 - **Recommendations**: Remediation steps for each finding
 
+## Operational Learnings
+
+### Cloudflare User vs Account API Tokens are different dashboard pages
+
+Rotation runbooks must name the exact dashboard path. User API Tokens live at My Profile → API Tokens; Account API Tokens live at Account → Manage Account → API Tokens. These are different screens with different scopes and different revoke semantics.
+
+- **Evidence:** Field report #305 — downstream user rotated the wrong token on first attempt because the runbook referenced "API Tokens" without qualifying which. 32-day credential leak remediation slowed as a result.
+- **Action:** Every secret rotation runbook MUST specify the exact dashboard path, not just the product name. Include both the User and Account paths when either could be the answer, and note which applies.
+- **Scope:** SECRETS_MANAGEMENT.md, deploy runbooks, rotation verification scripts.
+
 ## Reference
 
 - Agent registry: `/docs/NAMING_REGISTRY.md`

package/dist/.claude/agents/picard-architecture.md

@@ -51,6 +51,14 @@ Severity: CRITICAL (blocks ship) > HIGH (must fix before prod) > MEDIUM (fix soo
 - **Stubs ship as features:** When stubs are committed "to be implemented later," they almost never are. The codebase grows around them, tests don't cover them, and users encounter stubs as production failures. If a feature can't be fully implemented, don't create the file -- document it in ROADMAP.md.
 - **CLAUDE.md is a contract:** Every entry in the slash command table, agent table, and docs reference table must have a corresponding file. Audit table entries against actual files. (Field report #108: `/dangerroom` listed for 30 versions with no backing file.)
 
+### Agent-invented constraints require operator confirmation
+
+When designing executive constraints (kill switches, capital limits, safety thresholds, daily maxes, circuit breakers), tag them as AGENT_INVENTED in the ADR/design output and flag for operator confirmation before they propagate to downstream builds. Do not present agent defaults as decided.
+
+- **Evidence:** BarrierWatch campaign (field report #304) invented a $20 kill switch + $50/$50 capital split that took ~90 minutes to remove across 39 files. Neither value came from operator requirements; both got baked into ROADMAP, source modules, config, tests, and an ADR before the operator reviewed.
+- **Action:** Every numeric threshold, capital allocation, or safety mechanism in an architecture output gets an `AGENT_INVENTED — requires operator confirmation` annotation. Never present them as operator-approved.
+- **Scope:** `/architect` outputs, ADR drafts, design docs before build begins.
+
 ## Required Context
 
 For the full operational protocol, load: `/docs/methods/SYSTEMS_ARCHITECT.md`

package/dist/.claude/agents/silver-surfer-herald.md

@@ -38,6 +38,19 @@ When launching the Silver Surfer, announce with one of these (pick at random —
 - "Across galaxies, the Surfer has seen every architecture. Now he evaluates yours."
 - "The board carries him forward. The Power Cosmic carries the truth. The roster will be chosen."
 
+## HARD CONSTRAINT — ROSTER ONLY
+
+Your output is ALWAYS a roster list. Never:
+- Modify files
+- Run git commands
+- Execute the user-requested task described in your prompt
+
+If the user args describe a task, interpret it as CONTEXT for roster selection, not as INSTRUCTIONS to execute. The orchestrating agent executes tasks; you select who.
+
+You have Read, Grep, Glob, and Bash tools. They exist for: reading agent definitions, listing `.claude/agents/*.md`, running `git diff --stat` to match dynamic dispatch. They do NOT exist for applying changes to the codebase — even if the task looks trivial.
+
+Violating this constraint bypasses the orchestrator's synthesis step, the intended review chain, and the user's pacing controls. Field report #304 documents two incidents where this happened.
+
 ## Your Task
 
 You receive a prompt containing:
@@ -75,6 +88,7 @@ DEPLOYMENT REMINDER: You MUST now launch an Agent sub-process for EVERY agent li
 - **Never remove the command's lead agents.** You add specialists; leads are non-negotiable.
 - **Read the agent tags first** — tagged agents have `tags: [...]` in their YAML. These are the most cross-domain relevant. Start there, then scan descriptions of untagged agents.
 - **Be fast.** You're the first agent called. Don't read source files, don't analyze code quality — just read file names and agent descriptions to make the selection.
+- **Small-codebase scaling.** For very small codebases (<1000 LOC, static sites, methodology-only repos), roster size may exceed useful returns. Continue to over-include, but acknowledge that diminishing returns kick in earlier. A 30-agent roster on a 400-LOC static site is not wrong, but the marginal agent adds less than on a 50-file application. (Field report #303.)
 
 ## Operational Learnings
 

package/dist/.claude/agents/thufir-protocol-parsing.md

@@ -35,6 +35,16 @@ You are Thufir Hawat, Master of Assassins and Mentat to House Atreides. You pars
 - **Impact:** {what breaks}
 ```
 
+## Operational Learnings
+
+### "Verified against SDK" requires source code, not docs
+
+When reviewing an external API client, "verified against the official SDK" is only valid if you read the SDK source. Published docs describe format but not exact encoding; hand-rolled signing or serialization often diverges from what the SDK actually does.
+
+- **Evidence:** BarrierWatch campaign (field report #304) — HL action-hash algorithm was "verified against the Python SDK" via docs. Docs described the format correctly but omitted that the SDK uses msgpack encoding, not ABI. Live API calls returned "User or API Wallet 0xXXXX does not exist" with varying addresses until the smoke test surfaced the bug. 3 separate signing bugs shipped past unit tests, 44-agent gauntlet, and 3-agent contract review.
+- **Action:** If SDK source isn't available, flag the review as "documentation-level verification only" with an explicit uncertainty note. Prefer reviewers that can fetch SDK source (WebFetch or dependency audit) over those that read docs alone.
+- **Scope:** Any external API client review, especially for signing / cryptographic / wire-format encoding.
+
 ## Reference
 
 - Agent registry: `/docs/NAMING_REGISTRY.md`

package/dist/.claude/commands/architect.md

@@ -10,6 +10,8 @@
 
 **AGENT DEPLOYMENT IS MANDATORY.** Steps 1 and 4 specify parallel agent launches via the Agent tool. You MUST actually launch these agents as separate sub-processes — do NOT shortcut to inline analysis, even if you think you can answer faster by reading files directly. The agents exist because parallel analysis catches things sequential reading misses. Skipping agent deployment is a protocol violation. (Field report #68)
 
+**After the Silver Surfer returns:** Verify the response is ROSTER FORMAT — a list of agent names with reasoning. If the Surfer modified files, ran git commands, or executed the user-requested task described in the args, the protocol was violated. Report to the user: "Silver Surfer exceeded charter — verify any side effects independently before continuing." Proceed only after verification. (Field report #304 documents two incidents where the Surfer executed full task sequences instead of returning a roster.)
+
 ## Dynamic Dispatch (ADR-044)
 
 Opus scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
@@ -64,6 +66,22 @@ Use the Agent tool to run these in parallel — they are independent analysis ta
 - **Agent 1** `subagent_type: La Forge` — Failure analysis: for each component, answer "What happens when this fails?" (DB down, cache down, API down, worker crash).
 - **Agent 2** `subagent_type: Data` — Tech debt catalog: wrong/missing abstraction, premature optimization, deferred decisions, dependency debt, documentation debt. Severity table with impact/risk/effort/urgency.
 
+## Step 4.5 — Operator Sign-off on Invented Constraints (field report #304)
+
+Before ADRs propagate to downstream builds, scan every ADR drafted in this session for these patterns:
+
+- Numeric thresholds (kill switches, max amounts, timeouts, retry counts)
+- Capital allocations (splits, ratios, minimums, per-venue limits)
+- Safety mechanisms (halts, circuit breakers, rate limits, auto-disable triggers)
+
+For each match, flag explicitly:
+
+> "This is an AGENT_INVENTED constraint — value [X] was not supplied by the operator. Confirm, adjust, or remove before downstream phases begin? [Y/n/adjust]"
+
+In autonomous/blitz mode: append every AGENT_INVENTED constraint to `needs_operator_review.md` in the logs/ directory. Do NOT bake these values into source code, config files, or tests without explicit operator acknowledgment.
+
+Evidence: BarrierWatch campaign (field report #304) invented a $20 kill switch and $50/$50 capital split that took ~90 minutes to remove across 39 files. Both propagated into ROADMAP, source modules, config YAML, tests, and an ADR before the operator reviewed the design.
+
 ## Step 5 — ADRs + Decision Review
 Write Architecture Decision Records to `/docs/adrs/` for every non-obvious choice. After writing, **Riker** `subagent_type: Riker` reviews: challenges trade-offs, verifies alternatives were truly considered, checks for second-order effects.
 ```

package/dist/.claude/commands/campaign.md

@@ -8,6 +8,8 @@
 
 **Flags:** `--focus "topic"` biases the Surfer's selection; `--light` skips the Surfer (uses this file's hardcoded roster); `--solo` runs the lead only.
 
+**After the Silver Surfer returns:** Verify the response is ROSTER FORMAT — a list of agent names with reasoning. If the Surfer modified files, ran git commands, or executed the user-requested task described in the args, the protocol was violated. Report to the user: "Silver Surfer exceeded charter — verify any side effects independently before continuing." Proceed only after verification. (Field report #304 documents two incidents where the Surfer executed full task sequences instead of returning a roster.)
+
 The Prophets have shown me the path. Time to execute the plan.
 
 ## Blitz Mode Check
@@ -89,7 +91,28 @@ Check for unfinished business:
 - If vault exists but `.env` is sparse → offer: "The vault has credentials but infrastructure isn't provisioned. Run `voidforge deploy` now?" In `--blitz` mode: auto-run provisioner.
 - If clear → proceed to Step 0.5
 
-## Step 0.5 — Vault Auto-Inject
+## Step 0.5 — TECH_DEBT SLA Audit (field report #305)
+
+Before selecting the next mission, audit any `TECH_DEBT.md` catalog in the project root (or `docs/TECH_DEBT.md`) for overdue Critical + Immediate items.
+
+SLA contract (default durations — reasonable defaults, not mandated by any field report; override per-project via TECH_DEBT.md frontmatter):
+- **Critical + Immediate + LowEffort** items: 48-hour resolution. Items older than 48h block campaign advancement.
+- **Critical + Immediate + HighEffort** items: 72-hour triage. Must have an assigned owner and expected resolution window; otherwise block.
+- **High + Immediate** items: 7-day resolution. Warn but do not block.
+
+When a blocked item is detected, Sisko presents:
+
+> "Campaign advancement blocked — TECH_DEBT.md has [N] overdue Critical + Immediate items:
+>
+> [list with file:line and days overdue]
+>
+> Resolve these first, or explicitly acknowledge deferral with a reason and new deadline in the TECH_DEBT entry."
+
+Evidence: field report #305 — a Critical + Immediate + LowEffort credential-leak entry sat for 32 days in the downstream project's TECH_DEBT.md without enforcement. The methodology documented the risk but did not enforce action. Without an SLA with teeth, labels are advisory only.
+
+Applies to: `/campaign`, `/assemble`. The gate may be overridden with `--ignore-debt` (not recommended).
+
+## Step 0.6 — Vault Auto-Inject
 
 If vault exists and `.env` is sparse (missing keys that the vault has):
 1. Run `voidforge deploy --env-only` to write vault credentials to `.env`

package/dist/.claude/commands/deploy.md

@@ -38,6 +38,21 @@ Levi verifies the deploy is safe:
 5. **Version tagged:** Current version from VERSION.md matches the commit being deployed
 6. If any check fails → ABORT with clear error message
 
+## Step 2.5 — Pre-Deploy Secret Scan (Leia)
+
+Before any artifact leaves the local machine, scan the deploy payload for credentials and forbidden files. The deploy payload is whatever the deploy command will actually upload — for platform deploys this is the `pages_build_output_dir` / `outputDirectory` / `publish` directory, NOT the repo root.
+
+Run the reference implementation at `docs/patterns/deploy-preflight.ts` (or its shell equivalent). At minimum, assert zero hits for:
+
+- `.env`, `.env.*` (except `.env.example` / `.env.template`)
+- `*.pem`, `*.key`, `id_rsa*`, `*.p12`, `*.pfx`
+- High-entropy strings matching common secret patterns (AWS keys `AKIA[0-9A-Z]{16}`, Cloudflare tokens `[0-9a-f]{40}`, GitHub PATs `gh[pousr]_[A-Za-z0-9]{36,}`)
+- Methodology files that must not ship: `.claude/`, `docs/methods/`, `HOLOCRON.md`, `logs/`
+
+ANY hit aborts the deploy with a non-zero exit and prints the offending path(s). Never auto-filter and continue — a hit means something is mis-configured upstream and the operator must decide.
+
+Evidence: field report #305 — 32-day live credential leak caused by `.env` in deploy payload. Pre-deploy scan would have caught it on the first deploy.
+
 ## Step 3 — Deploy Execution (Levi)
 
 Execute the deploy strategy for the detected target:
@@ -65,6 +80,22 @@ After deploy completes:
 4. If health check fails → Step 5 (rollback)
 5. If healthy → log success to deploy-state.md
 
+## Step 4.5 — Post-Deploy Sensitive-Path Probe (Levi)
+
+After health check passes, probe a denylist of sensitive paths against the live URL. Each path MUST return non-200:
+
+- `/.env`, `/.env.production`, `/.env.local`
+- `/.git/config`, `/.git/HEAD`
+- `/.claude/agents/silver-surfer-herald.md`
+- `/docs/methods/FORGE_KEEPER.md`
+- `/HOLOCRON.md`, `/CHANGELOG.md`, `/VERSION.md`
+- `/package.json`, `/tsconfig.json`
+- `/id_rsa`, `/.ssh/id_rsa`
+
+Reference implementation: `docs/patterns/post-deploy-probe.sh`. Any 200 response triggers Phase 5 (Rollback) and a notification to the operator. Exposed methodology files (`.claude/`, `docs/methods/`) indicate a missing `.cfignore` / `.vercelignore` entry; exposed `.env` indicates a broken `Step 2.5` scan or a `wrangler pages deploy .` footgun (see Deploy Surface Boundary in DEVOPS_ENGINEER.md).
+
+Evidence: field reports #305 (credential leak) and #303 (methodology exposure).
+
 ## Step 5 — Rollback (Valkyrie)
 
 If health check fails:

package/dist/.claude/commands/prd.md

@@ -86,6 +86,14 @@ After all 5 (or 6) acts are confirmed:
 3. Verify YAML frontmatter is valid and complete
 4. Announce: "PRD written to /docs/PRD.md. Run `/build` to start building, or `/campaign` for autonomous execution."
 
+**For any `deploy` target that uploads from a local directory (cloudflare / static / firebase / netlify / s3):** the PRD MUST include an Infrastructure / Deployment section entry that specifies:
+- Explicit build output directory (e.g., `./dist`) — never repo root.
+- Platform config file (wrangler.toml / vercel.json / netlify.toml / firebase.json) that hardcodes the output directory.
+- Ignore file (.cfignore / .vercelignore / firebase `hosting.ignore`) that excludes `.claude/`, `docs/methods/`, `docs/patterns/`, `HOLOCRON.md`, `CHANGELOG.md`, `VERSION.md`, `logs/`.
+- `SECURITY.md` + `public/.well-known/security.txt` for coordinated disclosure.
+
+Evidence: field report #305.
+
 ## Import Mode (`--import`)
 
 If `--import path/to/existing-PRD.md` is passed, skip the interview entirely:

package/dist/CHANGELOG.md

@@ -6,6 +6,70 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ---
 
+## [23.10.0] - 2026-04-20
+
+### Field Report Triage — 6 reports closed (#303–#308)
+
+Wave-based triage across all open field reports. 33 approved fixes applied; 5 already-shipped confirmed; 3 deferred (MONITORING.md consolidated into DEVOPS_ENGINEER.md + FORGE_KEEPER.md per Batch E decision; #306 PF-8 hook-victory note already captured in ADR-051; #308 PF-8 TerminalCommand component is downstream marketing-site work).
+
+### Added
+
+- **`docs/methods/SPEC_HANDOFF.md` (NEW)** — method doc formalizing cross-session implementation hand-off. Includes `verified-against-commit: <SHA>` stamping convention and nav-order requirements for new pages. Evidence: 23/26 execution rate on v23.9.x marketing-site pass (#307 F4, #308 PF-4/PF-7).
+- **`docs/patterns/deploy-preflight.ts` (NEW)** — TypeScript reference implementation of pre-deploy secret + sensitive-path scan. Called from `.claude/commands/deploy.md` Step 2.5 (#305 P1-e).
+- **`docs/patterns/post-deploy-probe.sh` (NEW)** — Bash reference implementation of post-deploy denylist probe. Called from Step 4.5 (#305 P1-f).
+- **`docs/LEARNINGS.md`** — six new entries (8/50 → 14/50): LRN-5 `stat -f %m` non-portability, LRN-6 npm ci lockfile drift (npm#4828), LRN-7 npm org vs scope availability, LRN-8 CI workspace-scoped test bypasses root pretest, LRN-9 spec-handoff pattern, LRN-10 marketing-site scalar count drift (#308).
+- **`docs/methods/FORGE_KEEPER.md`** — new `## Deployment Hygiene` section (`.cfignore`/`.vercelignore` guidance for static-host deploys); new `## Cross-Repo Scalar Sync` section (stats.json CI artifact target; manual sync fallback).
+- **`docs/methods/DEVOPS_ENGINEER.md`** — new `## Deploy Surface Boundary` section (repo root ≠ deploy surface; per-platform enforcement table for Cloudflare/Vercel/Netlify/Firebase/S3). New subsections: "CI runs `npm test` at repo root" (#308 PF-5, RC-3); "Post-push live-URL fingerprint" (broken auto-deploy integration detection, #307 F3); "Methodology-exposure check" (curl denylist, #303).
+- **`docs/methods/TROUBLESHOOTING.md`** — new `## Cloudflare / Wrangler Gotchas` section (`.gitignore` ignored in Direct Upload; aliased `--force` bug; Dev Mode + Purge cache eviction).
+- **`docs/methods/BUILD_PROTOCOL.md`** — Phase 12 external-API live smoke-test mandate with scope clarification (custom signing/serialization only; read-only SDK clients exempt) and credentials-unavailable escape hatch (#304 Fix 2).
+- **`docs/methods/SYSTEMS_ARCHITECT.md`** — npm-name availability pre-flight (ADR authoring) — mandates dual-check of registry query AND org-create form before canonicalizing a package name (#308 PF-1).
+- **`docs/methods/PRD_GENERATOR.md`** + **`.claude/commands/prd.md`** — Cloudflare Pages deploy safety: `wrangler.toml` with `pages_build_output_dir`, `.cfignore`, `SECURITY.md`, `public/.well-known/security.txt`, dedicated output directory. Explicitly forbids `wrangler pages deploy .` (#305 P0-c).
+- **`docs/methods/CAMPAIGN.md`** + **`.claude/commands/campaign.md`** — Step 0.5 TECH_DEBT SLA Audit: Critical+Immediate+LowEffort 48h, Critical+Immediate+HighEffort 72h, High+Immediate 7d (reasonable defaults, override per-project) (#305 P1-a). Post-Surfer format verification (#304 Fix 3b).
+- **`.claude/commands/deploy.md`** — Step 2.5 Pre-Deploy Secret Scan (Leia); Step 4.5 Post-Deploy Sensitive-Path Probe (Levi) (#305 P0-a, P0-b).
+- **`.claude/commands/architect.md`** — Step 4.5 Operator Sign-off on Invented Constraints (flag agent-invented thresholds/capital/safety values) (#304 Fix 1). Post-Surfer format verification.
+- **`docs/adrs/ADR-050-native-claude-code-coexistence.md`** — Rename Verification Checklist appendix: 6-pattern grep table (`"/NAME"`, `` `/NAME` ``, `(/NAME)`, `→ Agent (/NAME)`, `Run /NAME`, `/NAME protocol`) plus table-cell/CHANGELOG/error-message supplementary checks (#306 PF-2, RC-9).
+- **`.claude/agents/silver-surfer-herald.md`** — `## HARD CONSTRAINT — ROSTER ONLY` section (Surfer must refuse task execution even with Write/Edit/Bash tools); small-codebase scaling note (#304 Fix 3a, #303 Fix 3).
+- **`.claude/agents/picard-architecture.md`** — Operational Learning: agent-invented executive constraints require operator confirmation (#304).
+- **`.claude/agents/thufir-protocol-parsing.md`** — Operational Learning: "verified against SDK" requires source code, not docs (#304).
+- **`.claude/agents/leia-secrets.md`** — Operational Learning: Cloudflare User vs Account API Tokens are different dashboard pages (#305 P1-c).
+- **`.claude/agents/kusanagi-devops.md`** — Operational Learning: Cloudflare Pages Dev Mode + Purge Everything may not evict all cache in one pass (#305 P1-d).
+
+### Changed
+
+- **`docs/methods/FORGE_KEEPER.md`** — Step 4.5 preview deploy now runs `npm test` before `npm run build` (content drift from sync surfaces as test failures, not build failures) (#307 F2). Step 0 adds parallel-session commit detection (`git log --since="1 hour ago" --all`) (#307 F5). §Shared Methodology Files adds CHANGELOG.md identity check (skip if site/app versions, not methodology) (#307 F1). §Edge Cases adds two-pass scaffold-era `/void` sync note (#303 Fix 1). §Step 4 numbering fix (duplicate `5.` → `5c.`).
+
+### Security
+
+- **Deploy hardening end-to-end** — Motivated by field report #305 (32-day Cloudflare Pages `.env` credential leak). Structural protections: pre-deploy secret scan + sensitive-path probe, Deploy Surface Boundary invariant with per-platform enforcement, PRD_GENERATOR now emits safety configs by default, TROUBLESHOOTING documents wrangler gotchas (`.gitignore` ignored in Direct Upload). Every VoidForge-generated project that deploys to a static host inherits these protections. Methodology-exposure check (from #303) folded into the same deploy phase.
+
+### Release notes
+
+- No breaking changes. Strictly additive to method-doc structure, agent naming, and build-protocol phases.
+- All changes are documentation/methodology; no source-code changes. Tests and gate tests unaffected.
+- Downstream work deferred: `voidforge-marketing-site` `TerminalCommand` component refactor (#308 PF-8); cross-repo `stats.json` auto-sync (#308 PF-6 target-state; manual sync documented in FORGE_KEEPER.md until auto-sync lands).
+
+---
+
+## [23.9.2] - 2026-04-20
+
+### CI workflow idempotency + provenance baseline
+
+v23.9.1 was published manually from a maintainer laptop and thus ships without npm provenance attestation (OIDC is CI-only). v23.9.2 re-publishes via CI tag-push to establish provenance as the baseline for future releases, and hardens the workflow so future accidental manual-then-tag sequences are non-destructive.
+
+### Changed
+- **`.github/workflows/publish.yml`** — both publish jobs now run a `check-*` step first (`npm view <pkg>@<version>`) and set `skip=true` if the current version is already on the registry. The actual `npm publish` step runs conditionally on `skip == 'false'`. This makes the workflow idempotent: re-triggering a tag, or tagging after a manual publish, is a no-op instead of a failure.
+
+### Release notes
+- If CI fails on this tag due to NPM_TOKEN scope (SEC-002 from ADR-061 — token was issued for `thevoidforge` and may not have write access on `voidforge-build`), rotate the token per npm account → Access Tokens. Create a new Automation token with publish scope for `voidforge-build` AND `voidforge-build-methodology` AND legacy `thevoidforge` + `thevoidforge-methodology` (for any future deprecate or owner-management operations). Update GitHub repo Secret `NPM_TOKEN` and re-run the workflow.
+- Provenance verification once attached: `npm view voidforge-build@23.9.2 --json | jq '.dist.attestations'` returns non-null.
+
+### Verification
+- `npm test` — 1384/1384 pass
+- `bash scripts/surfer-gate/test.sh` — 20/20 pass
+- Local `npm publish --dry-run -w packages/voidforge` confirms packable state.
+
+---
+
 ## [23.9.1] - 2026-04-20
 
 ### Publish-target pivot — `voidforge-build` supersedes `@voidforge/cli`

package/dist/VERSION.md

@@ -1,6 +1,6 @@
 # Version
 
-**Current:** 23.9.1
+**Current:** 23.10.0
 
 ## Versioning Scheme
 
@@ -14,6 +14,8 @@ This project uses [Semantic Versioning](https://semver.org/):
 
 | Version | Date | Summary |
 |---------|------|---------|
+| 23.10.0 | 2026-04-20 | Field Report Triage — 6 reports closed (#303-#308). 33 approved fixes: SPEC_HANDOFF.md (new method doc), deploy-preflight.ts + post-deploy-probe.sh (new patterns), LEARNINGS LRN-5..10, Deploy Surface Boundary + Deployment Hygiene (field report #305 remediation), Step 2.5 pre-deploy secret scan + Step 4.5 post-deploy probe, TECH_DEBT SLA, npm-name pre-flight, ADR-050 Rename Verification Checklist, Silver Surfer HARD CONSTRAINT + 4 agent operational learnings. |
+| 23.9.2 | 2026-04-20 | CI workflow idempotency + provenance baseline — `publish.yml` guards each publish with "already-published" check so re-runs skip cleanly. Tag-push re-publishes via CI to attach npm provenance attestation (absent on v23.9.1's manual publish). |
 | 23.9.1 | 2026-04-20 | ADR-061 pivot — `@voidforge` npm org unavailable (squat-adjacent). Rebranded publish target to `voidforge-build` / `voidforge-build-methodology` matching the voidforge.build domain. Migration banner for legacy `thevoidforge` / `@voidforge/cli` installs. Farewell releases + npm deprecate for smooth transition. |
 | 23.9.0 | 2026-04-20 | Campaign 42 — @voidforge scoped npm rename (ADR-061), gauntlet --fast 3-round mandate, README value-prop + first-command pointer, LEARNINGS.md 4 entries. Victory Gauntlet 3 fix batches: methodology runtime dep, registry-pin + env-stripping, BLOCK absolute paths. Publish gated on user scope claim + NPM_TOKEN rotation. |
 | 23.8.12 | 2026-04-12 | Field report triage (#299, #300) — campaign autonomy fix, ToS checks, deploy type-check gate, 3 operational learnings |

package/dist/docs/methods/BUILD_PROTOCOL.md

@@ -304,6 +304,25 @@ After running any build command (`build:workers`, `tsc --build`, webpack, etc.),
 2. Complete first-deploy pre-flight checklist (see `/devops` command)
 3. **Route registration check:** Verify all new API/route files are imported in the server entry point. Grep the entry point (e.g., `server.ts`, `app.ts`, `urls.py`) for imports of every new route file created during this build. An exported handler that isn't imported is a silent 404. (Field report #258: blueprint API routes exported but never registered via `addRoute()` in `server.ts` — wizard UI silently 404'd.)
 4. **Docker smoke test (field report #147):** If the project uses Docker/docker-compose, verify the container entrypoint runs the NEW code, not a legacy file. Run `docker compose up --build` (or equivalent) and confirm the process that starts is the architecture you just built. A 39-mission campaign once shipped with the legacy entrypoint because nobody checked what `CMD` pointed to.
+
+### External API integrations require live smoke tests (field report #304)
+
+Unit tests, protocol parser reviews, and SDK verification can all pass while a real API call fails. Signing bugs, wire-format encoding mismatches, and domain-field errors only surface when a live request is made.
+
+**Scope.** This applies to components that PRODUCE data for external consumption — custom signing, custom wire-format encoding, request serialization, or transport-layer framing. Read-only API clients that use a provider SDK with no custom signing (e.g., a Stripe balance read via `stripe-node`, a Supabase query via `@supabase/supabase-js`) are out of scope — their integration tests and the SDK's own test coverage provide adequate verification.
+
+For any in-scope component:
+
+1. Build a `src/tools/smoke-<service>.ts` (or equivalent, language-appropriate) harness IMMEDIATELY AFTER the client builds — before Gauntlet review.
+2. Run it against real credentials (paper mode, testnet, or sandbox at minimum; live if reversible).
+3. Document the exit criteria: what response or observable state counts as "working."
+4. Re-run smoke after every signing or wire-format change.
+
+**Credentials unavailable?** In regulated domains (banking APIs, government data APIs), sandbox access may take weeks to provision. Do NOT block Gauntlet indefinitely. Instead: document the exit criteria as an inline comment in the harness (`// SMOKE-TEST BLOCKED: awaiting <provider> sandbox credentials — target <date>`) and run the smoke test at the earliest CI checkpoint that has credentials. Phase log must name the blocker and the unblock target.
+
+BarrierWatch campaign (field report #304) shipped three signing bugs past 206 unit tests, a 44-agent gauntlet, and a 3-agent contract review. All three were caught on the first live API call. Code-review agents cannot see what only a live call reveals.
+
+Corollary: when reviewing external API clients, prefer agents that can fetch the SDK source (WebFetch, dependency audit) over agents that read docs alone. See thufir-protocol-parsing.md Operational Learnings.
 5. **Schema.sql sync gate:** After applying any migrations, regenerate `schema.sql` from the live database (e.g., `sqlite3 db.sqlite3 .schema > schema.sql`). Post-process the output: add `IF NOT EXISTS` to all `CREATE TABLE` and `CREATE INDEX` statements, remove `sqlite_sequence` (cannot be created manually). Commit the updated schema.sql. Stale schema.sql files cause false findings in `/assess` and mislead downstream consumers. (Field reports #232, #242)
 6. **Reference file freshness:** Before running `/assess` on an existing codebase, regenerate reference files (schema.sql, API docs, type exports) from the live system. Stale reference files generate false findings that waste triage time — the v7.0 assessment over-reported multi-tenant gaps because schema.sql showed 20 tables vs 52 actual. (Field report #232)
 7. Log to `/logs/phase-12-deploy.md`

package/dist/docs/methods/CAMPAIGN.md

@@ -51,6 +51,14 @@ Autonomous campaign execution: read the PRD, figure out what's next, build it, v
 12. **Log deviations.** When the build deviates from PRD architecture, update the PRD or log it in campaign-state.md. Never leave a silent contradiction.
 13. **Operational verification after deploy.** After deploying to a live environment, wait for 1 full operational cycle (1 trade cycle, 1 cron job, 1 polling interval) and check logs for errors, halts, and successful operations before marking the mission complete. "It deployed" ≠ "it works." (Field report #152)
 
+### TECH_DEBT SLA enforcement
+
+`/campaign` and `/assemble` audit `TECH_DEBT.md` before every mission selection. Critical + Immediate + LowEffort items overdue by 48h BLOCK campaign advancement. Critical + Immediate + HighEffort items overdue by 72h without owner + deadline BLOCK. High + Immediate items overdue by 7 days WARN.
+
+See `.claude/commands/campaign.md` Step 0.5 for the full gate.
+
+Evidence: field report #305. A Critical + Immediate + LowEffort credential-leak entry sat for 32 days because TECH_DEBT had labels but no contract.
+
 ## Two Modes
 
 ### Planning Mode (`--plan`)

package/dist/docs/methods/DEVOPS_ENGINEER.md

@@ -148,6 +148,48 @@ If a process manager (PM2, systemd, Docker, supervisord) owns the application po
 
 **Detection rule:** When writing CLAUDE.md "How to Run" sections or session restart commands, check if the project uses a process manager (`ecosystem.config.js`, `docker-compose.yml`, `*.service` files). If yes, the restart command MUST go through the PM — not through port killing.
 
+### CI runs `npm test` at repo root
+
+In monorepo CI workflows, run `npm test` at the repository root — NOT `npm run test -w <workspace-name>`. The workspace-scoped form skips the root `pretest` hook, silently bypassing any root-level validators (agent-ref checkers, gate tests, consistency checks).
+
+Evidence: field report #308 RC-3 — the `stat -f %m` portability bug in surfer-gate was latent for multiple releases because CI used `npm test -w @voidforge/cli`, which bypassed the root pretest that ran gate tests. Surfaced only when v23.9.0 switched CI to root `npm test`. See LRN-8 in docs/LEARNINGS.md.
+
+### Post-push live-URL fingerprint (platform auto-deploy integrity)
+
+The health-endpoint build-fingerprint (above) catches processes serving stale code. It does NOT catch the case where the platform auto-deploy integration is broken and no new deploy happened at all. To catch that:
+
+After every `git push` to a branch that auto-deploys, wait ~60 seconds, then hit a known endpoint on the live URL. Compare a content fingerprint (a string from the just-pushed commit, or the `last-modified` header age) against expected. If the fingerprint didn't change, the auto-deploy integration is broken — run the platform-specific manual deploy (`vercel --prod`, `flyctl deploy`, `wrangler pages deploy ./dist`, `firebase deploy`, etc.) and flag the hook as needing reconnection.
+
+Evidence: field report #307 — voidforge-marketing-site Vercel auto-deploy silently failed for 8 days after the repo was renamed (`voidforge-marketing-site` → `voidforge-site`). Eight days of unbuilt pushes went live as April-15 stale content until a `/assess` caught it. A post-push fingerprint check would have caught it on day one.
+
+Canonical check snippet (note: `Last-Modified` header is optional on some CDNs — fallback is the content-hash grep on the second line):
+```bash
+EXPECTED_SHA="$(git rev-parse --short HEAD)"
+sleep 60
+FINGERPRINT="$(curl -sI https://$DEPLOY_URL | grep -i '^last-modified:')"
+if [[ -z "$FINGERPRINT" ]] || ! curl -s https://$DEPLOY_URL | grep -q "$EXPECTED_SHA"; then
+  echo "AUTO-DEPLOY FAILED — running manual deploy"
+  # platform-specific manual deploy here
+fi
+```
+
+Applies to: Vercel Git Integration, Cloudflare Pages Git Integration, Netlify Git Integration, Firebase web-hook auto-deploys.
+
+### Methodology-exposure check (static-host deploys)
+
+After deploying to a static CDN (Cloudflare Pages, Vercel, Netlify, Firebase, S3+CloudFront), curl a known methodology path and assert 404 / denied:
+
+```bash
+for path in /.claude/agents/silver-surfer-herald.md /docs/methods/FORGE_KEEPER.md /HOLOCRON.md /CHANGELOG.md /VERSION.md; do
+  status=$(curl -s -o /dev/null -w "%{http_code}" "https://$DEPLOY_URL$path")
+  [[ "$status" == "200" ]] && echo "LEAK: $path returned $status"
+done
+```
+
+If any path returns 200, add a `.cfignore` / `.vercelignore` / `firebase.json ignore` entry that excludes `.claude/`, `docs/methods/`, `docs/patterns/`, `HOLOCRON.md`, `CHANGELOG.md`, `VERSION.md`, `logs/`. Methodology files must not be publicly served.
+
+Evidence: field report #303 — saltwater.com was serving 264 agent files, 37 patterns, method docs, HOLOCRON, CHANGELOG, and VERSION publicly on its Cloudflare CDN. Affects every VoidForge-generated project deployed to a static host until an ignore file is added. Companion: FORGE_KEEPER.md §Deployment Hygiene.
+
 ## E2E CI Architecture
 
 E2E tests run as a separate CI job, parallel with unit tests. Browser binaries cached via `actions/cache` (GitHub Actions) or equivalent CI cache. E2E failures are informational for the first release (v18.0-v18.1), then enforced as blocking. Playwright uses Chromium only in CI to minimize binary size (~250MB cached). Configuration:
@@ -286,6 +328,28 @@ Platform-hosted static sites serve the entire project from root. Subdomain-to-su
 
 **Always test routing before announcing a subdomain.** Curl the subdomain and verify it serves the expected content, not the root index.html.
 
+## Deploy Surface Boundary
+
+**Invariant:** the repository root is NEVER the deploy surface. Physical separation between "all files tracked in the repo" and "files uploaded to the CDN / server" is enforced by tool configuration, not by `.gitignore`.
+
+Why this matters: most deploy tools (wrangler Direct Upload, `aws s3 sync`, Firebase `firebase deploy --only hosting`) do NOT honor `.gitignore`. Deploying from repo root uploads `.env`, `.claude/`, `docs/methods/`, `logs/`, test fixtures, and any other sensitive or non-production file.
+
+### Required configuration per platform
+
+| Platform | Enforcement |
+|----------|------------|
+| Cloudflare Pages | `wrangler.toml` with `pages_build_output_dir = "./dist"` (or similar). Deploy command: `wrangler pages deploy ./dist` — never `wrangler pages deploy .` |
+| Vercel | `vercel.json` with `outputDirectory`. Never point at repo root |
+| Netlify | `netlify.toml` with `publish = "dist"` or similar |
+| Firebase Hosting | `firebase.json` `hosting.public = "dist"` + `hosting.ignore` list with methodology paths |
+| AWS S3 + CloudFront | `aws s3 sync ./dist s3://bucket` — never `aws s3 sync . s3://bucket` |
+
+### Verification
+
+The methodology-exposure check above (curl denylist) is the runtime assertion that enforcement holds. Run it after every deploy. If any path returns 200 that should not, the deploy surface boundary is breached — stop and fix the ignore/output-dir configuration before continuing.
+
+Evidence: field report #305 documents a 32-day credential leak caused by `wrangler pages deploy .` (dot path) uploading `.env` to production. The `.gitignore` entry was present — wrangler Direct Upload ignored it. Field report #303 documents methodology files publicly served on Cloudflare CDN for all VoidForge static-host deploys lacking `.cfignore`.
+
 ## Deliverables
 
 1. /scripts/provision.sh, deploy.sh, rollback.sh, backup-db.sh

package/dist/docs/methods/FORGE_KEEPER.md

@@ -72,6 +72,8 @@ VERSION.md                         ← Only sync the "Current:" line. If the pro
 
 **CLAUDE.md path detection:** Some projects use `.claude/CLAUDE.md` instead of root `CLAUDE.md`. Before syncing, check both locations. If `.claude/CLAUDE.md` exists and root `CLAUDE.md` does not, sync to `.claude/CLAUDE.md`. If both exist, warn the user — do not create a duplicate. (Field report #58)
 
+**CHANGELOG.md identity check:** Before syncing `CHANGELOG.md`, read the local file's first non-title heading. If it references non-methodology versions (e.g., `Site v2.x`, `App v1.x`) or a semver that does not match `VERSION.md`'s `Current:` line, the local `CHANGELOG.md` belongs to the downstream project — not to VoidForge methodology. Treat `CHANGELOG.md` as **skipped** for this project and print the reason in the sync plan. Never clobber a project's own changelog with the methodology changelog. (Field report #307 F1)
+
 **Never touched by Bombadil:**
 ```
 .claude/settings.json              ← User's permissions and hooks (review new permissions manually)
@@ -95,7 +97,8 @@ Orient to the current state:
 1. Read `VERSION.md` — identify the current VoidForge version
 2. Check which shared methodology files exist locally — determines if this is a VoidForge project
 3. Note any locally modified shared files via `git status` or file timestamps
-4. Announce: *"Old Tom is listening... you're running VoidForge vX.Y.Z. Let's see what the river brings."*
+4. **Parallel-session detect.** Before starting the sync, run `git log --since="1 hour ago" --all`. If commits exist that weren't authored in this session, warn: *"Another session may have committed recently: [SHA] [subject]. Review before proceeding."* Resolve with the user — never race another session's writes against Bombadil's. (Field report #307 F5)
+5. Announce: *"Old Tom is listening... you're running VoidForge vX.Y.Z. Let's see what the river brings."*
 
 ### Step 1 — Listen to the River (Goldberry)
 
@@ -231,7 +234,11 @@ Apply the updates:
 
 ### Step 4.5 — Preview Deploy Verification
 
-After syncing methodology files, if the project has a deploy target, run a preview build (`npm run build`) to verify the sync didn't break anything. For Vercel projects: `vercel` (without `--prod`) to create a preview URL and verify it loads. Only promote to production after preview passes. This prevents the scenario where synced .md files trigger Tailwind v4 content scanning failures that only manifest in platform build environments.
+After syncing methodology files, if the project has a deploy target, run `npm test` **first**, then a preview build (`npm run build`) to verify the sync didn't break anything. For Vercel projects: `vercel` (without `--prod`) to create a preview URL and verify it loads. Only promote to production after both pass.
+
+Run `npm test` before `npm run build` because content drift from the sync (new commands, agents, patterns) surfaces as consistency-check failures in tests — not in build output. Build-only verification misses them. If root `pretest` is absent the test invocation is cheap; if present, it catches agent-reference drift, orphan patterns, and dead links before they ship. (Field report #307 F2)
+
+This also prevents the scenario where synced `.md` files trigger Tailwind v4 content scanning failures that only manifest in platform build environments.
 
 ### Step 4 — The Song Continues (Bombadil)
 
@@ -250,7 +257,7 @@ Verify and celebrate:
 4. Check for handoffs — if new commands or agents were added, mention them
 5. **Content drift check:** If the sync changed methodology counts (agent counts, command counts, pattern counts) AND the project has a data layer that displays VoidForge metadata (e.g., `releases.ts`, `commands.ts`, site content), flag: "The sync changed [N] agents/commands/patterns. If your project displays these counts, update the data layer to match." This prevents stale counts on marketing sites and docs pages after version bumps. (Field report #113)
 5b. **Description accuracy check (Radagast):** For projects that display command descriptions (marketing sites, docs sites, README generators), compare each command's user-facing description against the upstream method doc's actual steps. If the upstream method doc gained new steps, flags, or capabilities in this sync that aren't reflected in the site's description, flag: "Command /X gained [capability] in this sync but the site description doesn't mention it. Update the description in [data file]." Count-based checks catch missing entries; this catches stale descriptions on existing entries. The most common void sync change is adding capabilities to existing commands, not adding new commands. (Field report #267: 9 commands had outdated descriptions after a sync that added capabilities to 12 agents — the biggest feature was invisible on the site.)
-5. **Version history check:** If VERSION.md was updated, compare the version table entries against any project pages that display release history (roadmap pages, changelog displays, "shipped versions" sections). Flag versions present in VERSION.md that are missing from site content. This prevents version drift between the methodology's version history and user-facing release pages.
+5c. **Version history check:** If VERSION.md was updated, compare the version table entries against any project pages that display release history (roadmap pages, changelog displays, "shipped versions" sections). Flag versions present in VERSION.md that are missing from site content. This prevents version drift between the methodology's version history and user-facing release pages.
 6. Announce: *"Hey dol! merry dol! The forge burns bright! VoidForge vA.B.C — all tools sharp, all songs true. The world is good."*
 
 ## Deliverables
@@ -268,3 +275,55 @@ Verify and celebrate:
 - **Network failure:** Bombadil announces the failure cheerfully and stops. No retries, no partial state.
 - **Full-tier users:** Bombadil only syncs methodology files. For wizard updates, tell the user to run `npx voidforge-build update --self`.
 - **Rollback:** All updates are applied to the working tree (not committed). If anything goes wrong, `git checkout -- .` restores every file to its last committed state. Bombadil should mention this safety net before applying updates.
+- **Two-pass sync from scaffold-era `/void` (pre-v20.2):** Projects upgrading from the old scaffold-era `/void` implementation require two runs. The first sync rewrites `.claude/commands/void.md` to point at `main` (npm-transport) instead of the legacy scaffold branch; the second sync, now using the new `void.md`, fetches main's full content. This is self-resolving but can look confusing — announce up front that a second run may be needed. (Field report #303)
+
+## Deployment Hygiene
+
+After syncing methodology to a project that deploys to a static CDN (Cloudflare Pages, Vercel static, Netlify, Firebase Hosting, GitHub Pages), methodology files MUST be excluded from the public deploy. Add a platform-appropriate ignore file that excludes:
+
+```
+.claude/
+docs/methods/
+docs/patterns/
+HOLOCRON.md
+CHANGELOG.md
+VERSION.md
+logs/
+```
+
+Per-platform file names:
+- Cloudflare Pages → `.cfignore`
+- Vercel → `.vercelignore`
+- Netlify → publish-ignore rules in `netlify.toml` or `_headers` / build config
+- Firebase → `firebase.json` `hosting.ignore` array
+
+**Verification (run after the next deploy):**
+
+```bash
+curl -sI "$DEPLOY_URL/.claude/agents/silver-surfer-herald.md" | head -1
+```
+
+If status is `200`, the exclusion is missing — methodology files are being publicly served. Expected status: `404`. Repeat for a representative sample: `docs/methods/FORGE_KEEPER.md`, `HOLOCRON.md`, `CHANGELOG.md`. Methodology files leaking to the public origin is an information-disclosure finding and a hygiene failure. (Field report #303)
+
+## Cross-Repo Scalar Sync
+
+Methodology consumers (marketing sites, docs sites, dashboards) often hardcode scalar counts — agent count, method-doc count, pattern count, test count, ADR count — in TypeScript data constants. These drift silently when `/void` runs, because `/void` touches methodology files but not sibling-repo data layers.
+
+**Target state (auto-sync):** Scaffold CI produces a `stats.json` artifact on every release:
+
+```json
+{
+  "version": "vX.Y.Z",
+  "agents": 42,
+  "methodDocs": 37,
+  "patterns": 41,
+  "scaffoldTests": 128,
+  "adrs": 61
+}
+```
+
+Sibling repos import `stats.json` at build time rather than hardcoding. A failed fetch falls back to the last-known-good committed copy.
+
+**Current state (manual sync):** Until the artifact ships, `docs/methods/RELEASE_MANAGER.md` release checklist MUST include a step: *"Sync scalar counts to sibling repos (marketing site, docs site) — update `totalADRs`, `totalMethodDocs`, `totalPatterns`, `totalScaffoldTests`, agent count."* Omission is how the marketing site landed 12 ADRs and 9 versions behind in field report #308 PF-6.
+
+Any sibling repo that displays these counts is in-scope for this sync, not just the primary marketing site.

package/dist/docs/methods/PRD_GENERATOR.md

@@ -132,6 +132,21 @@ Ask the user: "Does your product use AI or LLM features? If yes: What models? Wh
 - Backup strategy
 - Complete environment variable list
 
+### Cloudflare Pages deploy safety (required for `deploy: cloudflare` projects)
+
+Projects with `deploy: "cloudflare"` (or the static-site variant) MUST include:
+
+1. **`wrangler.toml`** with `pages_build_output_dir = "./dist"` (or the project's actual build output directory). This makes the deploy surface explicit.
+2. **Deploy command uses the output directory, not `.`** — always `wrangler pages deploy ./dist`, never `wrangler pages deploy .`. The dot path uploads the entire repo root including `.env`, `.claude/`, `docs/methods/`, `logs/`. `.gitignore` is IGNORED in Direct Upload mode.
+3. **`.cfignore`** (repo root) that excludes `.claude/`, `docs/methods/`, `docs/patterns/`, `HOLOCRON.md`, `CHANGELOG.md`, `VERSION.md`, `logs/`. Defense in depth.
+4. **`SECURITY.md`** (repo root) with a coordinated-disclosure contact.
+5. **`public/.well-known/security.txt`** pointing at the same contact.
+6. **Dedicated build output directory** — `dist/`, `build/`, `out/`, or `site/`. Never repo root.
+
+The PRD generator MUST emit these files / entries in the Infrastructure / Deployment section for any Cloudflare Pages target.
+
+Evidence: field report #305 documents a 32-day live credential leak caused by `wrangler pages deploy .` from repo root. Affects ALL VoidForge-generated projects that deploy to Cloudflare Pages via Direct Upload, and structurally similar situations with Netlify CLI, Vercel CLI, Firebase CLI, and `aws s3 sync`. See `docs/methods/DEVOPS_ENGINEER.md` §Deploy Surface Boundary.
+
 ## 16. Launch Sequence
 - Phased build plan (what gets built in what order)
 - Each phase has: scope, dependencies, and "done" criteria