Skip to content

CODEBASE_AUDIT.md

Latest commit

 

History

History
151 lines (124 loc) · 10.5 KB

CODEBASE_AUDIT.md

File metadata and controls

151 lines (124 loc) · 10.5 KB
Raw

Codebase Audit — pi-codex-goal

Date: 2026-07-01 Scope: Full repository (src/, test/, package metadata, docs, platform-smoke operability) Baseline: 0.1.33 checkout against Pi 0.80.3 Local gate: npm run verify Hosted CI: GitHub Actions runs npm ci and npm run verify on Node 24 for push and pull_request Release platform gate: local Crabbox npm run smoke:platform:all

Executive summary

The package remains in good structural health. The core runtime is split across focused modules for command/tool API, state transitions, runtime events, stale queued-work cleanup, recovery, persistence, and platform-smoke tooling. No critical or high-severity defects were found in this audit.

This pass fixed the low-risk drift and code-judo findings that had clear, behavior-preserving remedies: runtime boundary/resume consolidation, stale queued-work simplification, platform-smoke script consolidation, prompt contract consolidation, duplicate prompt budget rendering, command discoverability gaps, redundant transition validation, one dead export, a double-cloning goal lookup, and the minimal hosted CI workflow.

The ordinary hosted CI workflow is intentionally smaller than the release gate: it runs npm run verify on Node 24 only. The full local Crabbox npm run smoke:platform:all matrix remains the release-sensitive proof and passed in this release pass.

Coverage map

Area Status Evidence
Entry/package metadata Inspected package.json, src/index.ts, README.md, AGENTS.md
Commands/tools Inspected and fixed src/commands.ts, src/tools.ts, src/format.ts, test/commands.test.ts, test/state.test.ts
Prompt contracts Inspected and fixed src/prompts.ts, prompts/create-goal.md, test/prompts.test.ts
Domain/persistence Inspected src/state.ts, src/types.ts, src/goal-persistence.ts, persistence/state tests
Runtime lifecycle Inspected and partially fixed goal-runtime-*, goal-state-controller.ts, runtime/recovery tests
Transitions Inspected and fixed goal-transition.ts, goal-transition-effects.ts, test/goal-transition.test.ts
Continuations Inspected continuation-scheduler.ts, queued-goal-work.ts, queued-goal-messages.ts
Stale queued-work cleanup Inspected and partially fixed stale-queued-work-*, stale queued-work tests
Recovery Inspected recovery*.ts, recovery tests
Platform smoke Inspected and fixed scripts/platform-smoke*, platform-smoke.config.mjs, docs/platform-smoke.md, test/platform-smoke.check.ts
Hosted CI Added .github/workflows/verify.yml runs Node 24 npm ci and npm run verify on push and pull_request
Security/performance Sampled only Secret/artifact hygiene checks inspected; no dedicated threat model or profiling performed

Findings by priority

[🟡 Medium] [Runtime boundary] src/goal-state-controller.ts, src/goal-transition.ts, src/goal-runtime-session-handlers.ts
- Problem: Runtime memory effects and resume continuation paths were split across transition, state-controller, command, auto-resume, and session-resume code.
- Evidence: `reloadGoalRuntimeEffects` is now exported from `src/goal-transition.ts` and covered by transition tests; `resumeGoalWithContinuation` is now the shared resume helper for command, provider-limit auto-resume, and session-resume confirmation.
- Impact: Reload/resume behavior now has one smaller contract to regression-test.
- Blast radius: Runtime recovery, session reload, provider-limit/manual resume.
- Fix: Fixed in this session.

[🟡 Medium] [Stale queued-work maintainability] src/stale-queued-work-reducer.ts, src/stale-queued-work-guard.ts, src/stale-queued-work-obligations.ts
- Problem: The stale queued-work state machine had duplicated lifecycle branches, pass-through wrappers, and parallel anonymous terminal consumers.
- Evidence: Shared reducer defaults/helpers now cover repeated lifecycle handling, anonymous terminal consumption is centralized, and the unused `terminalCleanupFromObserving` export is gone.
- Impact: Stale terminal cleanup and abort release behavior have fewer duplicated branches to keep aligned.
- Blast radius: Replacement goals, stale hidden continuations, abort cleanup after late terminal events.
- Fix: Fixed in this session.

[🟡 Medium] [Platform operability] scripts/platform-smoke/targets.mjs, scripts/platform-smoke/platform-build-windows.ps1, test/platform-smoke.check.ts
- Problem: Platform-build behavior was maintained in separate POSIX shell and PowerShell implementations, while smoke script inventories and marker expectations were repeated in tests/scripts.
- Evidence: `scripts/platform-smoke/platform-build.mjs` now owns the suite body for all targets, the Windows PowerShell file is a thin wrapper, `script-inventory.mjs` feeds the cheap checks, and `package.json` delegates `check:platform-smoke` to `check.mjs`.
- Impact: Platform smoke has one build-suite path and less source-text drift in the cheap check.
- Blast radius: Release validation on macOS, Ubuntu, and native Windows.
- Fix: Fixed in this session.

[🟡 Medium] [Prompt/source-of-truth] src/prompts.ts, prompts/create-goal.md, test/package-manifest.test.ts
- Problem: Completion-audit guidance existed in multiple authored surfaces.
- Evidence: `src/prompts.ts` now exports canonical completion-audit guideline/continuation sections, and prompt tests assert those sections appear in tool guidance and continuation prompts.
- Impact: Model-facing completion rules have a smaller source of truth for runtime prompt surfaces.
- Blast radius: Model behavior around `update_goal` completion.
- Fix: Fixed in this session for runtime prompt surfaces; static markdown prompt alignment remains test-enforced rather than imported at runtime.

[🔵 Low] [Command discoverability] src/commands.ts, src/format.ts
- Problem: `/goal` summary hints and completions lagged the documented command surface.
- Evidence: Hints omitted `/goal copy`; completions omitted `resume cancel` even though commands and README documented it.
- Impact: Users could miss safe command actions.
- Blast radius: `/goal` command UX only.
- Fix: Fixed. Hints now include `/goal copy`; completions include `resume cancel`; tests cover both.

[🔵 Low] [Transition/readability] src/goal-transition.ts, src/goal-state-controller.ts
- Problem: Runtime-accounting validation had a redundant paused/complete branch, and `isCurrentActiveGoalId` called `getGoal()` twice.
- Evidence: The second validation branch already rejected every non-`active`/`budgetLimited` status; `getGoal()` clones snapshots.
- Impact: Small avoidable branch/read cost in hot runtime checks.
- Blast radius: Runtime accounting validation and active-goal ID checks.
- Fix: Fixed. Validation uses the canonical status set once; active-goal checks read one snapshot.

[🔵 Low] [Dead API surface] src/stale-queued-work-terminal-cleanup.ts
- Problem: `terminalCleanupFromObserving` was exported but unused.
- Evidence: Repo-wide reference search found no importers.
- Impact: Misleading stale queued-work helper surface.
- Blast radius: None at runtime.
- Fix: Fixed. Removed the export.

[🔵 Low] [CI] repository root
- Problem: No in-repo automated CI workflow existed.
- Evidence: `.github/workflows/verify.yml` runs Node 24, `npm ci`, and `npm run verify` on `push` and `pull_request`.
- Impact: PR/push checks now have ordinary hosted CI coverage without secrets or platform-matrix claims.
- Blast radius: Contributor/release workflow.
- Fix: Fixed in this session. Crabbox remains a local release gate, not hosted CI.

Systemic patterns

  • Good: Transition planning, persistence, recovery, and stale queued-work logic are heavily tested and mostly split by concern.
  • Good: No source file is near the 1k-line presumptive-blocker threshold.
  • Good: Runtime side effects are mostly explicit through transition effects and recovery machines.
  • Watch: Stale queued-work cleanup remains the densest state-machine area; future edits still need the full stale-work test suite, not piecemeal checks.
  • Watch: Hosted CI is ordinary npm run verify coverage only; do not treat it as proof that the local Crabbox release matrix passed.
  • Watch: Prompt contract text is centralized for runtime prompt surfaces; keep static markdown prompt alignment covered by tests.

Remediation roadmap

Completed in this audit pass

  • Share runtime memory-effect derivation between transitions and session reload.
  • Route command resume, provider-limit auto-resume, and session resume confirmation through the shared resume+continuation helper.
  • Simplify stale queued-work lifecycle and anonymous terminal-consumer duplication.
  • Remove unused terminalCleanupFromObserving export.
  • Consolidate platform-build POSIX/PowerShell behavior into one Node orchestrator with a thin Windows wrapper.
  • Single-source platform-smoke script inventory for cheap checks.
  • Consolidate completion-audit prompt contract text for runtime prompt surfaces.
  • Consolidate repeated prompt Budget lines behind one helper.
  • Remove redundant runtime-accounting validation branch.
  • Avoid double goal snapshot reads in isCurrentActiveGoalId.
  • Add /goal copy to summary hints for all goal states.
  • Add resume cancel command completion coverage.
  • Add minimal GitHub Actions hosted CI for Node 24 npm ci plus npm run verify on push and pull_request.
  • Refresh this audit record to the 0.1.33 baseline.

Release-sensitive verification

  • Run full local Crabbox npm run smoke:platform:all before release-sensitive platform claims.

Validation evidence

  • npm run verify passed under Node/Pi local dev setup: TypeScript typecheck, 6 platform-smoke checks, and 318 regular tests.
  • npm run smoke:platform:all passed under Pi 0.80.3: doctor, macOS, Ubuntu, and native Windows target suites.
  • .github/workflows/verify.yml was added for ordinary hosted CI: Node 24, npm ci, npm run verify, push, and pull_request.

Assumptions, gaps, and blocked checks

  • Security review was limited to structural inspection of artifact/secret hygiene and package contents; no dedicated threat model was performed.
  • Performance was not profiled; no obvious structural performance risk surfaced beyond small snapshot/timer cleanup opportunities.
  • Hosted CI validation does not prove the local Crabbox release matrix; keep that evidence separate.