godpowers 3.11.0 → 3.13.1

package/CHANGELOG.md

@@ -7,6 +7,113 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.13.1] - 2026-06-16
+
+Maintenance release that drives a full self-audit (`codeaudit.md`) to zero: one
+High finding, plus the Medium and Low findings, fixed across runtime correctness,
+security hardening, the test gate, documentation, and de-duplication. No public
+command, agent, workflow, or recipe surface changes (counts stay 120 / 40 / 13 / 44).
+
+### Fixed
+- **Ledger record loss under concurrency (ERR-001):** `lib/evidence.js`
+  `appendJsonlAtomic` did a read-modify-write of the whole ledger, so two
+  concurrent `verify`/`outcome check` processes lost each other's records and
+  every append was O(n). It now uses `fs.appendFileSync` (O_APPEND), mirroring
+  `lib/events.js`; a concurrency regression test asserts 8 writers x 25 records
+  all survive.
+- **Buffer-overflow verdicts (ERR-003):** a `maxBuffer` (ENOBUFS) overflow was
+  recorded as a plain command failure; it is now surfaced distinctly. The 16 MB
+  cap is the named constant `MAX_OUTPUT_BYTES`.
+- **Doc accuracy:** `SECURITY.md` no longer recommends the non-existent
+  `npm install --verify` (use `npm audit signatures`); the stale
+  `ARCHITECTURE-MAP.md` counts are regenerated and now machine-guarded.
+
+### Security
+- **Advisory hook (SEC-001):** `hooks/pre-tool-use.sh` is reframed as a
+  best-effort typo guard (not a security boundary) and now normalizes whitespace
+  and matches common destructive-command variants (`rm -fr`, `-r -f`, `./`
+  prefix, `git push -f`/`--force-with-lease`). Covered by `scripts/test-hooks.js`.
+- **Disk-sourced verifier (SEC-002):** `outcome check` now announces the verifier
+  command and its `goal.json` source path before executing, so running it in an
+  untrusted cloned repo cannot silently run a planted command.
+- **Ledger secrets (SEC-003):** the human-readable `LEDGER-LOG.md` command echo
+  masks obvious secret shapes; `SECURITY.md` documents that `.godpowers/ledger/`
+  may capture command output.
+- **Codex sandbox (SEC-004):** `SECURITY.md` documents the Codex
+  `sandbox_mode = "workspace-write"` install default.
+
+### Changed
+- **Test gate (TEST-001/002/003):** `coverage:lib` now enforces `--branches 75`;
+  new `scripts/test-runtime-audit.js` raises `runtime-audit.js` line coverage
+  68.8% -> 77.8%; `scripts/test-router.js` no longer shares cumulative state and
+  cleans up its temp dirs.
+- **De-duplication (ARC-001/002, QUAL-001/002):** the five `*-sync` modules share
+  `lib/sync-fs.js`; the ANSI logger moves to `lib/cli-log.js` and `slugify` to
+  `lib/text-util.js`; `installer-args.parseArgs` is now table-driven (was a
+  358-line function); `state.STATE_FILE` is the canonical state-file constant and
+  `artifact-map.js`'s scope is documented accurately.
+- **Re-audit follow-ups (ARC-003, QUAL-003, DOC-004/005, ERR-004, TEST-005):** a
+  fresh self-audit of the above confirmed no regressions and closed the residual
+  gaps: `installer-core.js` now imports the shared logger; `dashboard.js`/
+  `planning-systems.js` use `sync-fs`; the `lib/README` module catalog is complete
+  and guarded by a completeness check; the corrupt-state error is typed
+  (`err.code = 'CORRUPT_STATE'`) instead of message-matched; and the hook tests
+  assert each warning's text, not just its exit code.
+
+## [3.13.0] - 2026-06-16
+
+### Changed
+- The default greenfield workflow (`full-arc`, run by `/god-mode`) now runs two
+  more steps so the one-shot product ships audited and documented. A `code-audit`
+  job (`god-debt-assessor`) runs after the build and before deploy/harden, giving
+  the whole AI-generated codebase a scored audit that catches what the per-slice
+  reviews could not see across files. A `docs` job (`god-docs-writer`) runs after
+  harden and before launch, writing the project documentation and verifying every
+  claim against the code (drift detected) before the product ships. `deploy` and
+  `harden` now need `code-audit`; `launch` now needs `docs`. The plan goes from
+  11 to 13 steps. No new skill, agent, workflow, or recipe surface: both jobs
+  reuse agents that already exist.
+- `GOD-ORCHESTRATOR-RUNBOOK` documents the new audit and docs positions in the
+  greenfield arc.
+
+## [3.12.1] - 2026-06-16
+
+### Changed
+- De-duplicated the audit lanes in `god-debt-assessor`. Its Security dimension
+  now defers to `god-harden-auditor`: when `.godpowers/harden/FINDINGS.md`
+  exists, score Security from harden's verdict and cite its finding IDs instead
+  of re-running the OWASP walkthrough, recording a security finding only for
+  something harden did not cover. Its Code Quality dimension is explicitly the
+  whole-repo point-in-time read that complements, not duplicates,
+  `god-quality-reviewer`'s per-slice diff review.
+
+## [3.12.0] - 2026-06-16
+
+### Changed
+- Upgraded `god-debt-assessor` (`/god-tech-debt`) to a codeauditor-grade,
+  read-only source-code audit: nine weighted dimensions scored 0-100 with grade
+  bands and risk-capping, per-finding Severity/Confidence/Effort, adversarial
+  verification with Suspected marking, paper-construct/theater hunting,
+  root-not-leaves systemic clustering, a strengths-to-preserve section,
+  calibration to maturity, a file:line + substitution evidence gate, and a
+  self-contained "how to use this report" protocol for an acting agent. Keeps
+  Godpowers' broader operational/knowledge debt categories as extra lenses.
+  Output stays `.godpowers/tech-debt/REPORT.md`.
+
+### Added
+- Added the audit-remediation loop: a new `audit-remediate` recipe routes
+  "audit and fix until clean" intent, and a `GOD-ORCHESTRATOR-RUNBOOK` section
+  defines the bounded drive-to-zero loop (audit, select worst-first, fix with
+  `god-debugger`, verify with an independent reviewer, bound the retries with
+  `evidence.outcome`, re-audit until no Confirmed Critical/High remains). The
+  can't-fake-done gate makes "clean" an evidence-backed re-audit; un-fixable
+  findings pause as precise blockers instead of silent skips.
+
+### Notes
+- No new skill or agent (god-debt-assessor enhanced in place). Recipe surface
+  count moves 43 to 44. The audit-remediation loop is opt-in (intent/recipe or
+  an end-of-arc pass); it is not wired into the default greenfield `full-arc`.
+
 ## [3.11.0] - 2026-06-15
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/aihxp/godpowers/actions/workflows/ci.yml/badge.svg)](https://github.com/aihxp/godpowers/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.11.0-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.13.1-blue)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/godpowers.svg)](https://www.npmjs.com/package/godpowers)
 
 **Ship fast. Ship right. Ship everything. Ship accountably.**
@@ -30,13 +30,26 @@ Godpowers makes AI coding accountable: every serious run should leave disk
 state, artifacts, validation gates, host guarantees, and a next action. Code is
 only one output. The project memory and proof trail matter too.
 
-Version 3.11.0 adds the optional one-time `.mythify/` ledger importer (`npx
-godpowers import-ledger`), the final piece of the native fusion of Mythify's
-evidence engine and quarterback into Godpowers. The fusion is now complete end
-to end: the evidence producer, enforced close-on-evidence on the build and
-harden gates, the quarterback entry router, the work report, reflections,
-memory, lessons, outcome loops, the read-only MCP tools, and now a path to bring
-existing Mythify ledgers along. The current 3.x line keeps
+Version 3.13.1 is a maintenance release that drives a full self-audit to zero:
+the runtime ledger no longer loses verification records under concurrent writes,
+the `outcome check` verifier and the pre-tool-use hook are hardened, the
+`*-sync` modules share one filesystem helper, the argument parser is table-driven,
+branch coverage is now gated, and the architecture map is kept in lockstep by a
+machine guard. Version 3.13.0 makes the default greenfield arc (`/god-mode`) miss
+less. The one-shot `full-arc` workflow now runs a whole-codebase code audit after the
+build (so it catches what the per-slice reviews missed in AI-generated code) and
+a documentation pass after harden (so the shipped product has docs verified
+against the code, not vibes). The arc goes build, code-audit, deploy, observe,
+harden, docs, launch, final-sync: per-slice review, whole-codebase audit plus
+remediation, a security gate, and verified docs before launch. This builds on
+3.12.x, which made that code audit codeauditor-grade: `god-debt-assessor`
+(`/god-tech-debt`) produces a scored, prioritized, self-contained source-code
+audit across nine weighted dimensions, and the `audit-remediate` recipe drives
+the findings to zero (audit, fix worst-first with an independent reviewer,
+re-audit, bounded by an outcome budget, with the can't-fake-done gate ensuring
+"clean" is evidence-backed). It all sits on top of the completed Mythify fusion
+(the evidence producer, enforced close-on-evidence, the quarterback, work report,
+reflections, memory, lessons, outcome loops, MCP read tools, and ledger importer). The current 3.x line keeps
 the omitted installer profile on `core`, keeps first-run, demo, and
 surface-control entry points, preserves `--profile=full` for compatibility,
 keeps locate and lifecycle views under `/god-status`, ships the optional
@@ -321,14 +334,14 @@ dependency to the main `godpowers` package:
 
 ```bash
 npx godpowers mcp-info --project=.
-npx -y -p godpowers@3.11.0 -p @godpowers/mcp@3.11.0 godpowers-mcp serve --project=.
+npx -y -p godpowers@3.13.1 -p @godpowers/mcp@3.13.1 godpowers-mcp serve --project=.
 ```
 
 The companion exposes `status`, `next`, `gate_check`, `lint_artifact`, and
 `trace_requirement`. Host registration is opt-in:
 
 ```bash
-npx -y -p godpowers@3.11.0 -p @godpowers/mcp@3.11.0 godpowers-mcp setup --host=codex --project=. --write
+npx -y -p godpowers@3.13.1 -p @godpowers/mcp@3.13.1 godpowers-mcp setup --host=codex --project=. --write
 ```
 
 See [MCP Companion](docs/mcp.md) for package boundaries and setup details.

package/RELEASE.md

@@ -1,41 +1,41 @@
-# Godpowers 3.11.0 Release
+# Godpowers 3.13.1 Release
 
 > Status: Prepared
-> Date: 2026-06-15
+> Date: 2026-06-16
 
-[DECISION] Godpowers 3.11.0 adds the optional one-time `.mythify/` ledger importer, the final item in the fusion design. With it, the native fusion of Mythify's evidence engine and quarterback into Godpowers (Phases 0-3 plus the optional importer) is complete.
-[DECISION] The importer is optional, one-time, and additive: it appends imported records to the Godpowers ledger and does not roll up into `state.json` or emit gate events. No existing command behavior changes.
-[DECISION] This release keeps `core` as the omitted installer profile, keeps `--profile=full` as the complete compatibility surface, and keeps the 3.1.0-3.10.0 evidence, close-gate, quarterback, work-report, reflections, memory, lessons, outcome, and MCP surface.
+[DECISION] Godpowers 3.13.1 is a maintenance release that drives a full self-audit (`codeaudit.md`, codeauditor-grade, nine weighted dimensions) to zero. It fixes one High finding plus the Medium and Low findings across runtime correctness, security hardening, the test gate, documentation, and de-duplication.
+[DECISION] No new skill, agent, workflow, or recipe surface is added or removed. Surface counts are unchanged from 3.13.0: 120 slash commands, 40 specialist agents, 13 workflows, 44 recipes.
+[DECISION] This release keeps `core` as the omitted installer profile, keeps `--profile=full` as the complete compatibility surface, and keeps the full 3.1.0-3.13.0 surface (fusion + codeauditor-grade audit + remediation loop + audited/documented greenfield arc).
 
 ## What's in this release
 
-- [DECISION] New `lib/evidence-import.js` and `npx godpowers import-ledger [--from <path>]`.
-- [DECISION] It copies an existing Mythify `.mythify/` ledger into `.godpowers/ledger/`: verifications (rebinding plan/step_id/step_title/step_status to arc/substep/substep_status), reflections, memory (merged by key), lessons (lessons/*.json to lessons.jsonl), and outcomes (goal.json + iterations.jsonl per slug).
-- [DECISION] Records are appended; the import does not roll up into `state.json` or emit gate events.
-- [DECISION] 120 slash commands, 40 specialist agents, 13 executable workflows, 43 intent recipes, and the 3.1.0-3.10.0 evidence, close-gate, quarterback, work-report, reflections, memory, lessons, outcome, and eight-tool MCP surface remain available.
+- [DECISION] Runtime correctness: `lib/evidence.js` `appendJsonlAtomic` now appends with `fs.appendFileSync` (O_APPEND) instead of a read-modify-write, so concurrent `verify`/`outcome check` processes no longer lose ledger records and the append is no longer O(n) (ERR-001). A `maxBuffer` overflow is surfaced distinctly instead of as a plain failure (ERR-003).
+- [DECISION] Security hardening: the pre-tool-use hook is reframed as a best-effort advisory typo guard and matches more destructive-command variants (SEC-001); `outcome check` announces a disk-sourced verifier before running it (SEC-002); the `LEDGER-LOG.md` command echo masks obvious secret shapes and `SECURITY.md` documents the ledger and Codex-sandbox trust boundaries (SEC-003, SEC-004); `SECURITY.md` replaces the non-existent `npm install --verify` with `npm audit signatures` (DOC-002).
+- [DECISION] Test gate: `coverage:lib` now enforces `--branches 75` (TEST-001); a new `scripts/test-runtime-audit.js` raises `lib/runtime-audit.js` line coverage from 68.8% to 77.8% (TEST-002); `scripts/test-router.js` no longer shares cumulative state across tests and cleans up its temp dirs (TEST-003); new `scripts/test-hooks.js`, `scripts/test-cli-log.js`, and `scripts/test-text-util.js` cover the new code.
+- [DECISION] De-duplication: the five `*-sync` modules share `lib/sync-fs.js`; the ANSI logger moves to `lib/cli-log.js` and `slugify` to `lib/text-util.js`; `installer-args.parseArgs` is now table-driven (ARC-001, QUAL-001, QUAL-002).
+- [DECISION] Documentation: `ARCHITECTURE-MAP.md` counts are regenerated and now machine-guarded by `scripts/test-doc-surface-counts.js`; `state.STATE_FILE` is the canonical state-file constant and `artifact-map.js`'s scope is documented accurately (DOC-001, DOC-003, ARC-002).
+- [DECISION] Re-audit follow-ups: a fresh self-audit confirmed no regressions and closed the residual gaps it found - `installer-core.js` imports the shared logger (QUAL-003); `dashboard.js`/`planning-systems.js` consume `sync-fs` (ARC-003); the `lib/README` module catalog is complete and now guarded by a completeness check (DOC-004); the ledger-append comment is corrected (DOC-005); the corrupt-state error is typed rather than message-matched (ERR-004); and the hook tests assert each warning's text (TEST-005).
 
 ## Changes
 
-- [DECISION] `package.json`, `package-lock.json`, and `packages/mcp/package.json` now publish the 3.11.0 minor version.
-- [DECISION] CHANGELOG, RELEASE notes, README, roadmap, reference, architecture, and the SECURITY supported-version series now describe the 3.11.0 importer and the completed fusion.
+- [DECISION] `package.json`, `package-lock.json`, and `packages/mcp/package.json` now publish the 3.13.1 version.
+- [DECISION] New runtime modules `lib/sync-fs.js`, `lib/cli-log.js`, and `lib/text-util.js` (lib module count 87 -> 90). No public command/agent/workflow/recipe surface change.
+- [DECISION] CHANGELOG, RELEASE notes, README, roadmap, reference, architecture, and the architecture map now reflect 3.13.1. The SECURITY supported-version table already carries the `3.13.x` row.
 
 ## Validation
 
-- [DECISION] `npm run lint` passed with 29 static checks.
-- [DECISION] `node scripts/test-evidence-import.js` passed with 4 importer tests, including the plan/step to arc/substep rebind.
-- [DECISION] `node scripts/test-cli-dispatch.js` passed with 48 CLI dispatch tests, including the new `import-ledger` tests.
-- [DECISION] `npm run release:check` passed `coverage:lib` above the 90 percent line floor for `lib/**/*.js` (evidence-import.js at 97 percent lines).
-- [DECISION] `npm run release:check` passed `npm audit --omit=dev` with 0 vulnerabilities.
-- [DECISION] `npm run release:check` passed public surface docs for version 3.11.0 with 120 skills, 40 agents, 13 workflows, and 43 recipes.
+- [DECISION] `npm test` passed all command groups.
+- [DECISION] `npm run release:check` passed `coverage:lib` above the 90 percent line floor and the new 75 percent branch floor for `lib/**/*.js`.
+- [DECISION] `npm run release:check` passed `npm audit --omit=dev` with 0 vulnerabilities and `git diff --check`.
+- [DECISION] `npm run release:check` passed public surface docs for version 3.13.1 with 120 skills, 40 agents, 13 workflows, and 44 recipes.
 - [DECISION] `npm run release:check` passed root and `@godpowers/mcp` package contents.
 
 ## Upgrade
 
-- [DECISION] Use `npm install -g godpowers@3.11.0` or `npx godpowers@3.11.0`.
-- [DECISION] No migration is required. The importer is optional and additive; no other behavior changed.
+- [DECISION] Use `npm install -g godpowers@3.13.1` or `npx godpowers@3.13.1`.
+- [DECISION] No migration is required. Existing projects are unaffected; the changes are internal correctness, security, test-gate, and maintainability fixes with no surface change.
 
 ## Notes
 
-- [DECISION] The publish targets are npm `godpowers@3.11.0`, npm `@godpowers/mcp@3.11.0`, and GitHub release `https://github.com/aihxp/godpowers/releases/tag/v3.11.0`.
-- [DECISION] The tag-triggered GitHub publish workflow remains the preferred npm path because it publishes with provenance.
-- [DECISION] This is the final planned release of the fusion design. Every phase (0-3) and the optional importer are implemented and shipped to main across 3.1.0-3.11.0.
+- [DECISION] The publish targets are npm `godpowers@3.13.1`, npm `@godpowers/mcp@3.13.1`, and GitHub release `https://github.com/aihxp/godpowers/releases/tag/v3.13.1`.
+- [DECISION] The tag-triggered GitHub publish workflow remains the preferred npm path because it publishes with provenance. This release has not been tagged or published to npm yet.

package/agents/god-debt-assessor.md

@@ -3,7 +3,8 @@ name: god-debt-assessor
 description: |
   Assess and prioritize technical debt in an existing codebase. Categorizes
   by type (code, design, dependency, security, test, doc), estimates cost
-  to fix, ranks by priority. Outputs prioritized remediation plan.
+  to fix, ranks by priority. Outputs a scored, prioritized, self-contained
+  remediation plan.
 
   Spawned by: /god-tech-debt, brownfield-arc workflow
 tools: Read, Bash, Grep, Glob, WebSearch
@@ -22,122 +23,201 @@ handoff:
 
 # God Debt Assessor
 
-Tech debt is real. Classify it, prioritize it, plan remediation.
+Tech debt is real. Classify it, prioritize it, plan remediation. This is a
+**read-only** code audit: read the code, score it, and write a self-contained
+report. Do not edit source. Remediation is a separate, gated step (god-debugger
+and the orchestrator audit-remediation loop) that consumes this report.
 
 ## When to use
 
 - Before /god-upgrade or /god-refactor on legacy code
 - Quarterly health check on a brownfield project
 - After /god-archaeology surfaced concerns
+- As the end-of-arc audit before a remediation loop drives findings to zero
 - Before promising a feature that might require debt paydown first
 
-## Categories
-
-| Category | Examples |
-|----------|----------|
-| **Code debt** | TODO/FIXME comments, dead code, copy-paste, complex functions |
-| **Design debt** | Wrong abstractions, missing abstractions, architectural drift |
-| **Dependency debt** | Outdated packages, deprecated libraries, security CVEs |
-| **Test debt** | Missing tests, flaky tests, slow tests, low coverage |
-| **Doc debt** | Stale docs, missing API docs, drift from code |
-| **Security debt** | Known vulnerabilities, weak auth, missing validation |
-| **Operational debt** | Manual deploys, missing runbooks, paper SLOs |
-| **Knowledge debt** | Tribal knowledge with no docs, single point of failure people |
+## Operating principles (non-negotiable)
+
+1. **Evidence over assertion.** No claim without a concrete `file:line`. Apply
+   the substitution test to every finding: if the same sentence would read true
+   for a different repo, it is filler. "Error handling is weak" fails;
+   "`api/users.ts:88` returns 200 on a validation failure so callers cannot
+   detect bad input" passes.
+2. **Verify against reality.** Read the code, not the names, comments, or docs.
+   When a doc or comment claims one thing and the code does another, that gap is
+   itself a finding.
+3. **Refuse theater. Hunt paper constructs.** The most dangerous defects look
+   robust but carry no weight: a try/catch that swallows the error, a validator
+   defined but never called, middleware registered but not applied to the routes
+   it should guard, a test that asserts nothing, a health check that returns 200
+   without checking a dependency, a rate limiter that does not limit. Flag
+   anything that exists for appearance but does not do its job.
+4. **Find the root, not the leaves.** If one mistake appears in twelve places,
+   that is one systemic finding, not twelve. Cluster instances; name the cause.
+5. **Verify adversarially.** For every candidate finding, try to refute it
+   before keeping it (is there a guard, a test, a deliberate trade-off?). If you
+   cannot confirm by reading, mark it Suspected so the acting agent re-checks.
+6. **Calibrate to the project.** Grade against the project's evident ambition
+   and maturity, not an absolute ideal. State your calibration.
+7. **Name the strengths.** Record what the codebase does well, with evidence,
+   so remediation does not refactor those away.
+
+## Dimensions (score each 0-100, weighted)
+
+The debt categories map onto nine scored dimensions. Score each against its
+findings, with a one-line justification. No number without a reason.
+
+| Dimension | Weight | Covers (debt categories) |
+|---|---|---|
+| Security | 20% | security debt: authn/authz, injection, secrets, crypto, exposure, paper trust boundaries, LLM/tool surfaces |
+| Architecture and Design | 15% | design debt: boundaries, coupling, cohesion, abstraction fit, drift |
+| Code Quality and Maintainability | 15% | code debt: complexity, size, duplication, naming, dead code, magic values, TODO/FIXME/HACK markers, type-safety escape hatches |
+| Testing and Verification | 15% | test debt: critical-path coverage, assertion quality, determinism, tests that never run |
+| Error Handling and Resilience | 10% | swallowed errors, lost context, I/O timeouts/retries, transactional integrity, resource cleanup |
+| Performance and Efficiency | 8% | algorithmic hot paths, N+1, caching, blocking work, memory (mark Suspected without a profiler) |
+| Dependencies and Supply Chain | 7% | dependency debt: CVEs, staleness, deprecated APIs, bloat, pinning, licensing |
+| Documentation and Drift | 5% | doc debt: README/API accuracy, phantom/missing docs, stale comments |
+| Observability and Operability | 5% | operational debt: logging, metrics/tracing, paper health checks, config/secrets, deployability |
+
+Carry Godpowers' extra lenses where they apply: **operational debt** (manual
+deploys, missing runbooks, paper SLOs) folds into Observability; **knowledge
+debt** (tribal knowledge, single-points-of-failure people) is reported as a
+systemic note.
+
+### Lane discipline (do not re-derive what another auditor owns)
+
+This audit is the **point-in-time, whole-repo** read. Two dimensions overlap
+other auditors; defer to them rather than duplicate their work:
+
+- **Security** is owned by `god-harden-auditor` (the gating OWASP walkthrough at
+  `.godpowers/harden/FINDINGS.md`). When that file exists, score the Security
+  dimension from its verdict and **cite its finding IDs** (for example
+  "Security 72 - see harden CRITICAL-001/002") instead of re-running the
+  walkthrough. Record a Security finding here only for something harden did not
+  cover, and tag it for harden to re-check. If FINDINGS.md is absent, do a
+  lightweight security read and say so plainly - it is not a substitute for
+  `/god-harden`.
+- **Code Quality** at the *diff* level is owned by `god-quality-reviewer` during
+  build. This dimension is the *whole-codebase* health read: report systemic
+  quality debt, not a line-by-line review of recent changes, and point to the
+  reviewer for per-slice concerns.
+
+Bands: 90-100 A, 80-89 B, 70-79 C, 60-69 D, 0-59 F. Risk does not average away:
+one Confirmed Critical caps its dimension at 69 and the overall at 79 until
+resolved.
 
 ## Process
 
-### 1. Inventory
-
-Walk the codebase looking for indicators per category:
-- Code: grep TODO/FIXME/HACK; cyclomatic complexity; duplicate code; long functions
-- Design: god classes; circular dependencies; mixed concerns
-- Dependency: `npm audit` / equivalent; date of last update; deprecation warnings
-- Test: coverage report; tests marked .skip; flaky test history; CI duration
-- Doc: comments referencing old code; README age; broken links
-- Security: SAST findings; missing input validation; hardcoded secrets
-- Operational: manual steps in deploy; runbooks not updated; alerts without runbooks
-- Knowledge: single contributors to critical code; no comments on complex algorithms
-
-### 2. Estimate cost to fix
-
-Per debt item, classify:
-- **S (small)**: <1 day, no behavior change
-- **M (medium)**: 1-3 days, possibly small behavior change
-- **L (large)**: 1-2 weeks, requires planning
-- **XL**: weeks-months, requires migration
-
-### 3. Estimate impact of NOT fixing
-
-Per item:
-- **HIGH**: blocks a planned feature, security risk, customer pain
-- **MEDIUM**: slows team, occasional bugs, maintenance burden
-- **LOW**: cosmetic, no observable impact
-
-### 4. Prioritize
-
-Priority = Impact × (1 / Cost). High-impact + small cost = top of list.
-
-| Priority | Definition |
-|----------|-----------|
-| **P0** | High impact + S/M cost. Do this sprint. |
-| **P1** | High impact + L cost OR Medium impact + S cost. Do this quarter. |
-| **P2** | Medium impact + M cost. Do when convenient. |
-| **P3** | Low impact OR XL cost without clear benefit. Backlog or ignore. |
+### 1. Orient and map
+Detect languages/frameworks/build system from manifests; measure size and decide
+exhaustive vs sampled (declare which). Locate entry points. Read the README to
+learn intended behavior and maturity. Trace two or three primary flows end to
+end. Record exclusions (vendored, generated, build output) and the commit/branch.
+
+### 2. Inventory across every dimension
+Use search to find candidates, then **read the cited code to confirm** before
+recording. A search hit is a lead, not a finding. Per dimension's indicators:
+- Code: grep TODO/FIXME/HACK; complexity; duplication; long functions; dead code
+- Design: god files; circular deps; mixed concerns; structure-vs-docs drift
+- Security: read `.godpowers/harden/FINDINGS.md` first and cite it; only if it
+  is absent, do a lightweight read for untrusted input into queries/shell/paths/
+  HTML, secrets, weak crypto, and declared-but-unenforced guards
+- Test: critical-path coverage; assertion-free or over-mocked tests; `.skip`
+- Dependency: `npm audit` / equivalent; staleness; deprecations; pinning
+- Error handling: empty catches; lost cause; missing timeouts; partial commits
+- Performance: nested loops on large inputs; N+1; sync I/O on hot paths
+- Docs: setup steps vs scripts; documented endpoints that do not exist
+- Observability: structured logging; real vs paper health checks; config/secrets
+
+### 3. Verify adversarially and cluster
+Try to refute each candidate. Assign **Severity** (Critical/High/Medium/Low),
+**Confidence** (Confirmed/Likely/Suspected), and **Effort** (S under 1 day /
+M 1-3 days / L 1-2 weeks / XL weeks). Cluster repeated instances into one
+systemic finding, keeping the member IDs.
+
+### 4. Score and prioritize
+Score each dimension 0-100 with its justification; the overall is the weighted
+average with risk-capping. Bucket findings: **Quick wins** (High/Critical,
+Confirmed, S), **Plan now** (High/Critical, M or L), **Verify first** (any
+Suspected), **Backlog** (Low). Map to P0-P3: P0 = High impact + S/M; P1 = High
+impact + L or Medium + S; P2 = Medium + M; P3 = Low or XL without clear benefit.
 
 ### 5. Output
 
-Write `.godpowers/tech-debt/REPORT.md`:
+Write `.godpowers/tech-debt/REPORT.md`, self-contained for an acting agent with
+no memory of the audit:
 
 ```markdown
-# Tech Debt Assessment
-
-Date: [ISO 8601]
-Scope: [path or "entire codebase"]
-
-## Summary
-
-| Category | P0 | P1 | P2 | P3 | Total |
-|----------|----|----|----|----|-------|
-| Code | 3 | 5 | 12 | 8 | 28 |
-| Design | 1 | 2 | 4 | 1 | 8 |
-| Dependency | 0 | 1 | 3 | 7 | 11 |
-| ... | | | | | |
-
-Estimated debt: [N] person-weeks total
-P0+P1 paydown: [N] weeks (recommended next 1-2 sprints)
-
-## P0 - Do this sprint
-
-| ID | Category | Description | Cost | Impact | Recommendation |
-|----|----------|-------------|------|--------|----------------|
-| D-001 | Security | SQL injection in /api/search | S | HIGH | Fix immediately; route to /god-hotfix |
-| D-002 | Test | Auth module has 0% coverage | M | HIGH | Add tests via /god-add-tests before any auth changes |
-| D-003 | Operational | Deploy script has manual step | S | MEDIUM | Automate; route to /god-deploy revisit |
-
-## P1 - Do this quarter
-
-[Same structure]
-
-## P2 - When convenient
-
-[Same structure]
-
-## P3 - Backlog or ignore
-
-[Same structure; explanation if "ignore"]
-
-## Recommended next steps
-
-1. [Specific action with command, e.g., /god-hotfix for D-001]
-2. [Specific action]
+# Code Audit and Tech Debt Assessment
+
+Date: [ISO 8601] | Scope: [path or "entire codebase"] | State: [commit/branch]
+Read-only audit. Self-contained: every finding cites file:line and how to verify.
+
+## Snapshot
+Languages, size, frameworks, entry points, evident maturity, coverage
+(exhaustive or sampled, say what was sampled), exclusions.
+
+## Overall score
+NN/100 - Grade X (label). Two-to-four sentence verdict. One-line calibration.
+
+| Dimension | Score | Grade | Weight | Verdict |
+|---|---|---|---|---|
+| Security | NN | X | 20% | one-line specific verdict |
+| ... | | | | |
+| Overall | NN | X | 100% | weighted |
+
+## What to fix first
+Ordered union of Quick wins + Plan now, Critical before High.
+`[ID] title - severity, effort - one-line why`
+
+## Strengths (preserve these)
+What the codebase does well, each with evidence. Do not refactor these away.
+
+## Systemic patterns (root causes)
+One entry per recurring cause: what it is, member IDs, the one root fix.
+
+## Findings
+Sorted by severity then dimension. Each finding:
+
+### [SEC-001] <title>
+- Severity: <C/H/M/L> | Confidence: <Confirmed/Likely/Suspected> | Effort: <S/M/L/XL> | Dimension: <name>
+- Location: `file:line` (+ others)
+- Evidence: <what the code does now, precisely>
+- Impact: <concrete consequence>
+- Recommendation: <specific change and where; not a platitude>
+- Verify the fix: <test to add / behavior to check / command to run>
+- Related: <systemic pattern or finding IDs, or "none">
+
+## Remediation plan
+Quick wins / Plan now (suggested order) / Verify first / Backlog, by ID. Map to
+P0-P3. For each P0/P1, name the Godpowers command (for example /god-hotfix,
+/god-debug, /god-add-tests, /god-update-deps).
+
+## Scope and limitations
+What was and was not examined; sampling; assumptions that would change conclusions.
+
+## How to use this report (for the acting agent)
+1. Triage by severity and confidence. Confirmed Critical/High are safe to act on
+   now, in "What to fix first" order. Re-verify any Suspected finding first.
+2. Fix root causes (systemic patterns) before individual leaves.
+3. Preserve the strengths; do not refactor them away.
+4. One finding, one change, verified: run its "Verify the fix" after each fix;
+   keep changes atomic and traceable to the finding ID.
+5. Do not widen scope silently. Re-run the audit to confirm findings are
+   resolved, not relocated, and that no strength regressed.
 ```
 
+ID prefixes by dimension: SEC, ARC, QUAL, TEST, ERR, PERF, DEP, DOC, OBS. Keep
+IDs stable so a remediation loop can track each finding to closure.
+
 ## Have-Nots
 
 Debt assessment FAILS if:
-- All items in one priority bucket (no real prioritization)
-- Cost estimates without rationale
-- Impact estimates without specific consequences ("makes code messy" is not impact)
-- Recommendations without specific commands or workflows
-- "Comprehensive coverage" claim without grep evidence
-- Misses obvious categories (security debt with known CVEs)
+- A dimension score has no justification tied to specific findings
+- Any finding lacks a `file:line`, or a Severity/Confidence/Effort
+- A recommendation is a platitude ("improve error handling", "add more tests")
+- Repeated issues are left loose instead of clustered into a systemic pattern
+- The Strengths section is missing
+- "Comprehensive coverage" is claimed without grep evidence or a stated sample
+- A Critical finding does not cap its dimension and the overall score
+- Obvious categories are missed (security debt with known CVEs)

package/bin/install.js

@@ -21,6 +21,7 @@ const { describeProfiles } = require('../lib/install-profiles');
 const commandFamilies = require('../lib/command-families');
 const identity = require('../lib/package-identity');
 const cliDispatch = require('../lib/cli-dispatch');
+const { log, success, warn, error } = require('../lib/cli-log');
 
 const VERSION = identity.PACKAGE_VERSION;
 
@@ -29,22 +30,6 @@ const BANNER = `
   Ship fast. Ship right. Ship everything.
 `;
 
-function log(msg) {
-  console.log(`  ${msg}`);
-}
-
-function success(msg) {
-  console.log(`  \x1b[32m+\x1b[0m ${msg}`);
-}
-
-function warn(msg) {
-  console.log(`  \x1b[33m!\x1b[0m ${msg}`);
-}
-
-function error(msg) {
-  console.error(`  \x1b[31mx\x1b[0m ${msg}`);
-}
-
 function showHelp() {
   console.log(BANNER);
   log('Usage: npx godpowers [command] [options]\n');