carthagent 0.0.0-stage → 1.0.7

package/docs/planning-startup-fix-review.md

@@ -0,0 +1,24 @@
+# Planning startup repair — author review and results
+
+## Implemented
+
+On-demand `delivery_design action=guide` works before a plan without source fingerprint, workspace mutation, or advice call. Compact tested example explains actual component/port/scenario/review fields, requirements and check references; no automatic boilerplate insertion or approval.
+
+Discovery checkpoint at8 built-in discovery results or2 blocked implementation attempts, with stronger wording at16 results. It asks for the first accurate plan or one missing fact. Reads stay available; existing execution gates unchanged. Numeric-only metadata is bounded on restoration and loaded from selected branch. New input resets it, successful plan suppresses it, informational asks are excluded heuristically. Context injection is outbound, not a repeated persistent prompt message.
+
+Unknown IDs/requirement text include invalid values and valid references. Findings remain blocking. Error presentation handles malformed non-array design sections instead of throwing while explaining validation.
+
+Both built-in Jev adapters now transmit check definitions/argv, outputs and assumptions alongside prior semantic input. Test question distinguishes declared commands from execution evidence. Validation precedes optional advice: invalid inspect sends zero calls and reserves zero attempts. Same caps/timeouts, opt-in and no authority; expanded external disclosure documented.
+
+## Tests and challenges
+
+- `npm run quality`: lint/typecheck/build and **360/360 tests pass** (`/tmp/ctg-startup-quality-final.log`).
+- `node --test tools/benchmark/planning-startup.test.mjs`: **1/1 installed-engine offline scripted test passes** (`/tmp/ctg-startup-engine-final.log`),20 tool starts:8 reads -> checkpoint -> guide -> plan/validate/inspect/self-review/approve -> actual file write -> real assertion subprocess -> progress/final diff review -> verified.21 zero-cost mocked provider responses. No actual external provider or credentials used.
+- Extension loop test adds invalid check reference -> rejected inspect/zero advice -> preserving revision -> real loopback mock Jev returning a flagged tests topic -> ordinary review/approval/edit/check/final review. Schema guide itself passes production structural validators.
+- Branch navigation restores only selected checkpoint; compaction notification and session restoration preserve counters. Questions and terminal plans suppress reminders. Existing stale-source, user-validator and persistent-blocker suites pass.
+- Both adapter payload/bounds tests verify extra fields unchanged, no plan mutation, and oversized check argv rejected.
+- `git diff --check`: clean.
+
+This is **author review**, not independent approval. Scripted plumbing proves the workflow is traversable, not that DeepSeek will stop discovery sooner. No new native model-generated compaction test/paid call or benchmark rerun here. Provider180s deadlines and CURL_56 are not fixed by these changes; no timeout increases, automatic paid retries, token-limit changes or new spending authorization introduced. No browser/Python suite or remote CI/merge claimed.
+
+The old `/tmp/ctg-tested-planning` checkout disappeared between turns. Committed history/artifacts survived; reconstructed edits are now under `/home/baissi/ctg-planning-startup`, branch `fix/planning-startup`, based on93c3693. Primary checkout untouched. Historical benchmark source manifests correctly will not validate this changed implementation; their artifacts are not rewritten.

package/docs/planning.md

@@ -0,0 +1,118 @@
+# Adaptive delivery planning
+
+> Read [tested planning before code](tested-planning.md) first. The approval gate is mandatory before code, tests or commands, including legacy-report resumes. This page describes the subsequent adaptive delivery/evidence layer. See the [rollout ledger](tested-planning-roadmap.md) for stage status.
+
+The plan is a revisable acceptance contract, not a one-time list of edits. Its job is to retain requirements, discoveries, progress and verification obligations as understanding changes. It cannot establish that the model understood every requirement or wrote adequate tests.
+
+## Tools and lifecycle
+
+- `delivery_plan` starts a task. For compatibility, replacing an active plan is a revision; it no longer erases verification history. After a terminal `verified`/`blocked` report, it creates a distinct task with fresh evidence.
+- `delivery_revise({reason, patch})` changes the **same task**, including resuming blocked/verified work. Omitted fields are preserved; arrays supplied in the patch replace the entire field. Keep original acceptance text and promised outputs. A reason records what discovery changed the approach; it does not authorize dropping requirements.
+- Revisions keep the run ID, increment revision, clear the old handoff and persist snapshots of prior plans, evidence and progress in `report.json`. Status returns compact revision metadata; compaction context includes assumptions, step progress, revision and the latest reason.
+- Unchanged commands, kinds, IDs and deadlines retain fresh evidence only when the full workspace fingerprint and old evidence identity still match. Rebinding records `originRevision` and `executedRevision` and retains the actual log. New/remapped acceptance criteria retain truthful old command results but appear in `unverifiedRequirements` until their mapped suites execute at or after the requirement's introduction. Repeated revisions cannot launder old executions into new coverage. New assertions are still a model obligation, not mechanically proven by rerunning a command. Changed checks need new executions. Failed/stale evidence stays visible without being promoted to fresh; removed/changed checks remain in revision history.
+- Once verification has started, revisions cannot erase that fact to downgrade a required task. User-owned required validators are rebound automatically.
+- `delivery_check({id:"all"})` runs all declared suites sequentially, collecting ordinary failures before reporting an error. Cancellation and evidence-scope errors still stop execution.
+- For required delivery plans, `delivery_status` and `delivery_finish` share completion checks: required checks must be fresh, artifact roots must exist, declared output paths must be files, structured steps must be done, newly added/remapped requirements need fresh executions, and structured required plans need a snapshot-bound `delivery_review` receipt. Informational/advisory handoffs remain non-blocking, but those classifications cannot authorize new command execution. Explicit unfinished legacy progress also blocks finish. Old untracked string-only plans remain compatible.
+
+### Dependency-aware steps
+
+```json
+{
+  "steps": [
+    {"id":"contract","title":"Capture failing API compatibility behavior","kind":"regression","checks":[]},
+    {"id":"api","title":"Implement server adapter","dependsOn":["contract"]},
+    {"id":"client","title":"Migrate client","dependsOn":["contract"]},
+    {"id":"integration","title":"Verify old and new clients","dependsOn":["api","client"],"checks":["integration"]}
+  ]
+}
+```
+
+Define `unit` and `integration` in the plan's checks and map observable acceptance criteria to them. The intentionally-red `kind:"regression"` milestone must have `checks:[]`: reproduce a behavioral assertion failure via a focused shell command and record the result in progress notes, then mark it done. Import/syntax failures do not establish the requested behavior. Keep passing suites on acceptance and the later integration milestone; this avoids the circular requirement to fix code before finishing regression capture. For ordinary work steps, mark done after their mapped checks pass. Numeric indexes still work. Unknown/duplicate IDs, missing dependencies, cycles and missing check references are rejected.
+
+The API and client branches can proceed independently once the contract step is done. Dependency order is enforced by progress updates, not by restricting arbitrary shell commands. Reopening a prerequisite resets downstream progress. Revisions preserve progress only for unambiguously unchanged steps; changed prerequisites reset dependent progress. Legacy strings are matched by unique title rather than old index.
+
+## Traceable final review and monitoring
+
+For structured required plans, `delivery_review({action:"inspect"})` captures `git diff HEAD` without external diff/textconv helpers, plus the full untracked-file list. It returns a capture ID and saved path; read the full file if truncated and inspect new-file contents separately. Git workspaces need a committed baseline and must be the repository root. Non-Git workspaces receive an explicit manual-source-review limitation instead of a fabricated diff.
+
+After fixing findings and rerunning checks, record:
+
+```js
+delivery_review({
+  action: "record", captureId: "<returned ID>",
+  coverage: [{ requirement: "<exact acceptance text>", assertions: "<test cases/assertions covering this behavior>" }],
+  probes: ["<additional boundary/metamorphic command and observed result>"],
+  findings: [], limitations: ["<honest remaining assurance limits>"]
+})
+```
+
+Include every criterion, including user-owned validators. Unresolved findings prevent recording: repair them or finish blocked. Source changes or any plan revision invalidate the receipt. The harness handoff stores exact check evidence and review evidence; model-authored output reports remain untrusted. Review descriptions and claimed probes are **self-reported**, not proof that files were read or assertions are adequate. This gate does not replace independent review.
+
+Use `ctg --json -p "task"` for engine JSONL events including tool activity, or `ctg status --json` for a versioned report/fingerprint/completion snapshot. Text `-p` alone is not a live tool stream. Engine event shapes follow the bundled engine; report snapshots and saved logs remain the durable evidence. Treat output as potentially sensitive task data.
+
+## Practical workflows
+
+### 1. Cross-package API evolution in a TypeScript monorepo
+
+**Goal:** add pagination without breaking older clients.
+
+1. Inspect server routes, shared types, generated clients, consumers and workspace scripts. Record compatibility invariants and baseline failures.
+2. Capture old response behavior with regression/contract tests. Plan separate server and client branches plus an integration join, as above.
+3. Discover a second consumer using a different serialization convention. Revise assumptions and add an adapter step; do not reset already passing evidence if only the plan changed.
+4. Implement the adapter with targeted tests. Since source changed, rerun affected suites during development and every declared suite against final source before finish. Include the repository's typecheck/build/lint gates, not just a smoke command.
+5. Exercise old and new public clients in fresh subprocesses, then inspect the final diff for unhandled consumers and unrelated changes.
+
+**Automated planning coverage:** dependency gating, stable progress through reordering, shared-config staleness and no fabricated evidence reuse (`tests/planning.test.mjs`).
+
+### 2. Database migration with a discovered backfill risk
+
+**Goal:** introduce a non-null column while preserving data and compatibility during rollout.
+
+1. Record schema version compatibility, backfill size, transaction/locking risks, retry behavior and rollback strategy. Use an isolated test database; a plan does not authorize production migration.
+2. Start with schema, backfill and verification milestones. Run a probe against representative old records.
+3. If the probe reveals duplicate or partially migrated records, revise the backfill milestone into idempotency, failure/restart and integrity checks. Preserve the original data-integrity acceptance criterion.
+4. Reopen affected prerequisites so downstream completion no longer appears valid. Map the final step to migration, rollback/recovery and old-client integration checks.
+5. Declare a migration report under `outputs` and inspect its contents. Merely having a report file is not proof of its correctness.
+
+**Automated planning coverage:** changed prerequisite invalidation, failed-evidence history across revisions, blocked-task resumption, missing-output finish gates. These are planning scenarios, not tests of a real database engine.
+
+### 3. Shared-library regression across many services
+
+**Goal:** fix a retry/cancellation bug without changing public behavior.
+
+1. Reproduce the bug with a failing regression; inspect call sites and existing error-handling conventions.
+2. Keep a small immediate implementation slice and coarse later integration milestones. Do not write a speculative 40-step plan just because the schema allows it.
+3. Run focused unit tests while iterating. Run all declared service suites to collect independent failures in one verification pass instead of discovering one per repair turn.
+4. Revise only after identifying the failure cause. Do not remove assertions or change commands merely to make the gate pass. External validators remain authoritative.
+5. If an external dependency is unavailable, preserve failing evidence and finish blocked with a specific limitation, rather than reclassifying the work as informational.
+
+**Automated planning coverage:** real subprocess checks continue after an ordinary failure; changed commands invalidate evidence; multiple replans cannot wash away verification history (`tests/extension.test.mjs`).
+
+### 4. Long-running refactor interrupted by context compaction
+
+**Goal:** reorganize a subsystem without behavioral drift over several work sessions.
+
+1. Capture invariants, package boundaries, assumptions and regression suites before moving code.
+2. Revise steps as hidden coupling is discovered. Keep stable IDs for unchanged work; avoid relying on numeric position.
+3. Resume from the active report. The injected context retains assumptions, progress and the latest revision reason. Full earlier snapshots remain in the durable report.
+4. Recheck workspace freshness before claiming success. Existing evidence is not portable across tasks or arbitrary changed workspaces.
+5. Use a separate review pass to look for missing requirements and weak tests; a self-authored plan is not an independent review.
+
+**Automated planning coverage:** extension restoration/compaction continuity, cooperative workspace lock and superseded-writer rejection, dashboard revision/finish consistency.
+
+## Limits and deliberate tradeoffs
+
+- Fingerprinting remains whole-workspace and conservative, with existing exclusions and file/byte limits. There is no inferred package dependency graph, scoped test cache, or selective source-change reuse. This costs reruns but avoids hiding changed shared configuration or undeclared callers. Large repositories can adjust `CARTHAGENT_MAX_FILES` / `CARTHAGENT_MAX_BYTES`; scope-limit errors must not become verified evidence.
+- A check's `kind` is self-declared. Exit zero, file existence, step status and a prose review do not prove assertion strength, visual quality, data safety or complete requirement coverage. Existing tests, user-owned validators and independent review are still important.
+- Declared outputs are existence-gated, not independently provenance-checked. Tests should assert their contents; screenshot files still require actual visual inspection where applicable.
+- Original acceptance text and promised outputs cannot be removed by a same-task revision, except when reclassifying a mistaken required plan as informational before verification begins. Legitimate scope cancellation should be explicitly agreed with the user and recorded in a blocked handoff before creating a new task. A terminal new-task reset is an explicit boundary, not protection against a dishonest model.
+- Revision snapshots grow the report and session state. Status/context deliberately omit full history, but there is no archive/retention policy yet.
+- Locks coordinate participating local tools, not arbitrary edits or distributed workers. See [workspace coordination](workspace-coordination.md).
+- Regression scenarios exercise the planning mechanics in temporary multi-package workspaces and real subprocesses. They do **not** establish improved model code quality, lower cost, or success on production-scale repositories; that requires controlled live-task evaluation.
+
+## Verification
+
+```sh
+node --test tests/planning.test.mjs tests/extension.test.mjs tests/server.test.mjs tests/tui.test.mjs
+npm run quality
+```

package/docs/production-merge-review.md

@@ -0,0 +1,23 @@
+# Existing implementation production-branch merge
+
+## Scope and plan
+
+User authorized merging existing work. Merge the current context-efficiency, opt-in Jev, startup guidance and benchmark/report history into current origin/main via PR. Preserve main's thinking-model catalog changes. No deployment, new paid benchmark, automatic Jev enablement or timeout-repair implementation is authorized by this merge.
+
+1. Reconcile current main into this branch without overwriting either worktree's unrelated work.
+2. Review production diff for SRP/DI, authority changes, default paid dispatch and durable evidence preservation; keep known benchmark failures and proposed-only timeout plan explicit.
+3. Run local quality plus available offline benchmark/integration tests. Use remote CI for OS/Node matrix, Python and browser checks. Do not equate green tests with semantic completeness.
+4. Publish PR with author review (not independent approval), known limitations and test receipts; merge only after green CI and no unresolved merge blockers. Verify resulting main commit remotely and fast-forward local main only if still clean.
+
+## Author challenge before integration
+
+- New runtime modules separate pure context projection/discovery/guide, archival filesystem effects, advisor orchestration and injected provider transport. Existing serialized workspace operation remains the caller; advice does not write approval or resolve blockers.
+- Jev defaults disabled; explicit opt-in plus provider credentials required. Exact requested OpenRouter model typesafe/jev-1.13, Decisions API, bounded inputs/response/time and durable three-attempt maximum. This is not a global dollar limit or zero-retention feature.
+- Archives can retain sensitive original content; content-addressed local writes precede outbound substitution. Full report/session history retained. Pointer is not proof of reading. Context reduction and guide do not claim reliable autonomous completion.
+- Benchmark-only gateway still has buffered stream diagnostics, question-contract drift and imperfect terminal error classification; hardcoded local fixture paths make these tools operator-specific, not production runtime dependencies. They are preserved as historical experimental infrastructure; no paid invocation in normal quality/CI.
+- Current pilot results show uncompleted deliveries and no scored Jev dispatch. Merge ships an optional critic and deterministic ergonomics, not demonstrated Jev effectiveness or fixed provider timeouts.
+- Proposed design-section patching, streaming timing instrumentation, command deadline changes and new pilot repetitions remain unimplemented in delivery-timeout-repair-plan.md.
+
+## Verification
+
+Integrated origin/main at72f819a cleanly; thinking-model catalog/TUI changes preserved. Fresh npm run quality: lint/typecheck/build and362/362 tests pass. Separate node --test tools/benchmark/*.test.mjs:18/20 pass, including actual installed-engine offline full delivery, mocked advice, TLS transport and billing/profile tests. Two historical browser evaluator tests fail because local Snap geckodriver cannot preserve its mount namespace (driver log: Invalid argument, unexpected eof); shop6/6 non-browser categories and voxel7/7 non-browser categories pass. These failures remain disclosed, not converted to skips. Logs /tmp/ctg-production-quality.log and /tmp/ctg-production-benchmark-tests.log; historical evaluator diagnostic artifacts retained under /home/baissi/benchmarks/infrastructure-tests/. No live paid calls. Remote OS/Node/Python/browser CI pending at PR publication. Review is author-performed; independent human approval is not claimed.

package/docs/quality.md

@@ -0,0 +1,35 @@
+# Repository quality and evaluation evidence
+
+Run `npm ci` followed by `npm run quality`. Native Windows, macOS and Linux CI
+runs lint/typecheck, build and JS/Python regressions. A separate Linux Firefox
+job runs `npm run test:browser` and retains screenshots as diagnostic artifacts,
+not evidence of manual visual approval.
+
+ESLint recommended rules cover first-party `.mjs` source, tests and tooling.
+TypeScript extension checking remains a separate compiler check. Vendored code,
+scenario fixtures, generated artifacts and public assets are excluded from this
+initial lint scope; this is not a claim that all repository languages are linted.
+Unused parameters/caught errors and deliberately underscore-prefixed bindings
+are permitted. Empty catch blocks remain permitted for established best-effort
+cleanup patterns. No formatting rewrite is required.
+
+## Every implementation and evaluation
+
+1. Discover repository instructions and configured lint, format, type, test and
+   production-build commands. Use the target repository's conventions, not carthagent's
+   style by default. Do not weaken existing validators.
+2. Run those gates and focused behavior/failure-path regressions. Report missing
+   gates and pre-existing debt explicitly; do not silently call them passing.
+3. Review the actual diff: architecture, canonical implementations versus
+   duplication, validation boundaries, error handling, async cleanup, unused
+   code, dependencies, type weakening and public-behavior tests.
+4. Record findings with severity, path/line, rationale and resolution. Bind the
+   review to the commit/source fingerprint; edits invalidate the review.
+5. Report functional evidence, repository conformance, review findings and
+   unreviewed areas separately. A model review is not executable evidence.
+
+Maintainer checklist: no unrelated churn; no blanket lint suppression; clean
+failure/cleanup paths; bounded diagnostics; honest platform and visual claims.
+Paid model comparisons additionally require an explicit spending cap and
+independent task acceptance checks. Passing lint does not prove maintainability,
+security, completeness or a favorable cost per accepted change.

package/docs/repository-benchmark-design.md

@@ -0,0 +1,111 @@
+# Repository-scale daily development benchmark — design proposal
+
+## Aim and honest hypothesis
+
+Test whether Carthagent improves **correct feature delivery and regression avoidance** in existing repositories under matched resources, including permissioned online documentation. Do not construct a leaderboard of tasks selected because pi already failed. Harder tasks should challenge baseline and treatment alike; unknown outcome is the point.
+
+This is a design/selection proposal, **not a runnable or frozen benchmark yet**. No task has an implemented withheld evaluator, proven environment or reference patch in this suite. Repository SHAs below are discovery anchors, not execution bases. Budget estimates are proposals, not spending authorization.
+
+## Candidate repositories: verified discovery, not inferred from search snippets
+
+Primary GitHub API metadata and raw README contents were retrieved into `/home/baissi/benchmarks/repo-suite-design/`. Search-engine results were irrelevant and were not used as evidence.
+
+- **Saleor core:** discovery SHA `9ea6bdeae2e704cc01f6659e9c4f87a83d0ce245`. Its README describes GraphQL-only headless commerce, channels, payments/webhooks and a separate dashboard; warns that main is unstable and recommends compatible release versions. Choose a stable release base plus compatible dashboard/storefront pins, not blindly this main SHA. API metadata identifies BSD-3-Clause; inspect licenses in all selected components before packaging fixtures. Sources: https://github.com/saleor/saleor/blob/9ea6bdeae2e704cc01f6659e9c4f87a83d0ce245/README.md and https://api.github.com/repos/saleor/saleor .
+- **Medusa core:** discovery SHA `037232847319a12b83f597cce06e24371f96e81f` on develop. README describes a modular commerce framework and **open-core** licensing: core MIT, separately identified enterprise/RBAC materials require a commercial agreement. Restrict tasks to verified core paths or exclude the repository; do not assume the entire tree is MIT. Sources: https://github.com/medusajs/medusa/blob/037232847319a12b83f597cce06e24371f96e81f/README.md and https://docs.medusajs.com/learn/advanced-development/architecture/overview (linked by README; architecture page not independently fetched in this design).
+- **Scheduling candidate, identity unresolved:** requested `calcom/cal.com`, discovery SHA `54343aa685ae8f33159d2f485ec4a57bad5c574a`; fetched README identifies **Cal.diy**, a community fork with enterprise features removed, Next.js/tRPC/React/Prisma, PostgreSQL, local yarn/Docker development. Resolve canonical repository/redirects and validate license/path scope before adoption; do not describe it as a verified commercial Cal.com checkout. Source: https://github.com/calcom/cal.com/blob/54343aa685ae8f33159d2f485ec4a57bad5c574a/README.md .
+- Directus discovery request returned 404; not selected without resolving its current repository availability.
+
+README architecture claims are verified page contents, not evidence that a local installation runs. The suite needs measured tracked file/LOC counts, package graph, baseline suite duration and feature ownership paths after checkout. 'Large codebase' is not established merely by stars/reputation.
+
+## Six proposed tickets
+
+Final tickets must be checked against the pinned code: exclude functionality already present and avoid copying an existing upstream fix. Freeze exact public contracts before measured runs. Difficulty comes from existing invariants and cross-layer behavior, not obscure guessing.
+
+### R1 — Channel-scoped order CSV export (Saleor + compatible dashboard)
+
+**User story:** An authorized staff member exports filtered orders for one channel from the existing list view, without exposing another channel's/customer's restricted data.
+
+**Acceptance contract:** typed API entry point, existing permission checks, streaming/paginated processing, stable documented column/order/filter semantics, formula-injection-safe cells, UTC timestamps with explicit display timezone policy, audit event, bounded memory, accessible download/error state; existing exports/list filters unchanged. Declare whether the pinned project supports async export before choosing an API shape.
+
+**Withheld evaluation:** cross-channel authorization matrix; user/app role variants; 20k seeded records with bounded memory threshold defined from reference; commas/newlines/Unicode/formulas; cancel/retry behavior; real browser list filter→export; existing relevant GraphQL tests. Mutants remove permission check, skip pagination, or mishandle quoted cells.
+
+### R2 — Optimistic bulk tagging with conflict recovery (Medusa core admin + API)
+
+**User story:** Apply/remove an allowed product label on a filtered selection using existing admin UI, reflecting updates immediately while correctly handling partial failure and another editor.
+
+**Acceptance:** existing typed routes and validation, permission-compatible core paths only, per-record version/concurrency rules, atomicity semantics explicitly chosen, idempotent retry, rollback of failed optimistic rows, stale-response protection after filter changes, keyboard operation and screen-reader status. No enterprise RBAC modification.
+
+**Evaluation:** deterministic delayed/out-of-order HTTP responses, two clients editing same record, validation failure subset, duplicate requests, browser navigation/reload, persistence/restart, existing product tests. Reference patch and mutants establish that tests detect stale UI and lost updates.
+
+### R3 — Configurable reschedule cutoff with DST safety (resolved scheduling community repo)
+
+**User story:** Event owner configures a reschedule cutoff; invitees see localized availability and receive consistent API/UI behavior near cutoff and daylight-saving changes.
+
+**Acceptance:** schema/default migration that preserves old events, owner authorization, explicit instant-based cutoff semantics, existing cancellation rules unchanged, localized message, disabled controls plus server enforcement, idempotent competing reschedules. Define injected clock and fixed timezone database version.
+
+**Evaluation:** before/at/after cutoff, DST gaps/folds, non-hour offsets, invalid timezone, old database migration, simultaneous requests, browser locale switching, unaffected cancellation routes. No real calendar account; local calendar adapter with real HTTP interaction.
+
+### R4 — Webhook consumer API-version upgrade (Saleor/Medusa integration)
+
+**User story:** Update an existing integration to a pinned new upstream event version while accepting the documented old version during transition.
+
+**Acceptance:** authenticate exact raw bytes; reject bad/stale signatures; durable deduplication; tolerate documented nullable fields; explicit version mapping; transactional state changes; backoff/Retry-After; redact credentials in logs; no real payments or outbound customer actions.
+
+**Online track:** agents may fetch pinned vendor API docs/changelog, not hidden solutions or upstream implementing PRs. Evaluator serves both event versions from a local HTTP service with injected clock/failures. The third-party version/schema must be selected and verified during setup; no invented vendor version in the ticket.
+
+**Evaluation:** replay/different payload same event ID, Unicode raw-body signatures, crash between receive/commit, duplicate concurrent delivery, 429 and permanent 4xx, restart; reference/mutants must distinguish retries from double side effects.
+
+### R5 — Persisted advanced search with backward-compatible URLs (admin web app)
+
+**User story:** Users save named filter views, share valid URLs, and restore state across navigation without leaking another user's saved view.
+
+**Acceptance:** schema migration, ownership enforcement, typed query parser, canonical URL encoding, old URLs still accepted, invalid/deleted filter values handled, back/forward works, no stale network response overwrites new state, accessible reset/error UX.
+
+**Evaluation:** two users, migration from old DB, encoded operators/Unicode, malformed query fuzz cases, conflicting request order, browser back/forward/reload, screenshots for review plus objective layout/interaction checks. Existing search routes and API clients remain compatible.
+
+### R6 — Durable background import with cancel/resume (commerce core)
+
+**User story:** Upload a product-import CSV, preview validation failures, start a bounded background job and resume safely after worker restart.
+
+**Acceptance:** existing storage/queue seams, explicit row-level transaction/idempotency semantics, progress and cancellation state machine, maximum upload limits, formula/text handling, no partial undocumented silent success, old synchronous API compatibility if present, no customer-data outbound traffic.
+
+**Evaluation:** malformed row midway, worker termination after database commit before acknowledgement, repeated upload/key, cancel racing commit, retry permanent errors, scoped status polling, real queue/DB/browser. Small and large files; resource bounds calibrated against reference, not arbitrary impossible latency requirements.
+
+## Tracks and network policy
+
+1. **Hermetic development:** prebuilt containers/dependency cache, local DB/Redis/mail/webhook stubs; no outbound network during candidates. Frozen documentation snapshot provided equally.
+2. **Online documentation:** same containers and tasks/budgets; read-only HTTPS allowlist for official docs, registry metadata and specified upstream source reference pages. Supervisor fetch proxy records URL/time/status/response hash and serves cached identical content for matched runs. Separate cold-live exploration pilot from reproducible cached evaluation.
+
+The public web can contain misleading instructions. Treat fetched content as data, not benchmark authority. No production credentials, real payments/calendar events, deployments, public issue/PR submissions, repository pushes or access to supervisor evaluations. External tools need read-only treatment consistently in both arms; granting arbitrary shell before plan approval is not an acceptable workaround. Network/tool isolation must be an actual container/network policy, not merely a prompt. Dependency installs should finish in setup; unavailable upstream docs/services are infrastructure outcomes, not model zeros.
+
+## Fair experimental design
+
+- Primary comparison: **plain pi vs context-efficient Carthagent**, same installed engine/model/provider routing, tools, documentation access, native compaction, temperature/reasoning, container hardware, wall/tool/dollar budgets.
+- Secondary ablations: previous Carthagent vs new context projection (separate development tasks); Jev off/on only after primary completion improves. Do not conflate context management, advisor, engine version and larger budgets.
+- Split tasks before execution: development tickets for tuning/fixture fixes, held-out feature tickets for reporting. No discard because baseline won or treatment failed. Pilot both arms to calibrate difficulty; publish all pilot outcomes separately.
+- Proposed first scored tranche: 4 held-out tickets × 2 arms × **3 paired repetitions** = 24 runs. Balanced/reversed arm order and task order. Add online subset as a separately labeled stratum, not unbalanced extra access for treatment.
+- Proposed upper bound per cell: 45 min, 250 tool attempts, $5 including compaction/advisor; **$120 max** for 24 cells, plus explicitly capped setup/diagnostic allowance. Requires user approval and capacity/budget confirmation; do not charge the old $27 campaign. Limits may change during unscored setup only, then freeze.
+- Report paired task-level differences, full run distributions and uncertainty; do not treat assertions or three repeats as independent task samples. A few repository tickets cannot establish universal superiority.
+
+## Success and evidence
+
+Primary: strict delivery success = held-out acceptance + protected regression checks + runnable migration/launch + honest final handoff. Separate functional partial-credit, candidate tests, false completion, harness gate completion, time/cost, context growth/compaction calls and infrastructure/resource failures. A runtime pass with missing tests or unfinished handoff is not full success.
+
+Maintain immutable original requirements and validators. Baseline and treatment may not edit protected evaluators or weaken existing tests unnoticed. Save source diff, task-specific file scope, executed commands, DB snapshots, request logs, final answer, screenshots and network receipts. Blind reviewer assesses maintainability/security against a predefined rubric; disclose if the supervisor is the only reviewer. No arbitrary 'one file/function' SRP score. Hidden evaluator location must be inaccessible from candidate containers, not a sibling directory under the same user.
+
+## Readiness gates before any measured run
+
+- Resolve repository identity/license, pin commit + submodules/lockfiles/container digests and compatible companion repositories.
+- Create isolated container with non-root user, no host auth mounts, limited egress, resource/process limits, separate evaluator service and fresh DB/queues per cell.
+- Install dependencies once; pass existing relevant baseline tests; record unrelated failures without deleting them. Verify browser + migrations and project runtime versions (do not force Node 26 on an unsupported app).
+- Implement reference patch for each ticket, withheld tests and semantic mutants; green reference, intentionally red base and mutant failures must prove test sensitivity. Reference/hidden tests never enter candidate checkout or online allowed pages.
+- Freeze task text, base SHA, public contracts, test/container hashes, docs corpus, budgets and analysis plan; verify before every launch. Add realistic >400KB history/compaction transport preflight and byte/terminal classification regression tests before paying for candidates.
+- Do not start until both arms work in the identical environment and compaction retains obligations. Pause on shared infrastructure failures; retain every cell and any protocol deviation.
+
+## Local capacity check
+
+The current host reports approximately 7.6GiB RAM, 2GiB swap and ample disk; neither `docker` nor `podman` was found on PATH. The scheduling README suggests a development Node heap as high as 16GiB. A large multi-service browser fixture is therefore **not ready on this host**. Start with a smaller single-service API ticket or provision a suitable isolated worker; do not silently install privileged container infrastructure or run commercial services to make the benchmark proceed.
+
+## Implementation status
+
+Only design and repository discovery are complete here. Checkout/license review, containers, pinned runnable bases, six exact tickets/reference implementations, protected evaluators and repeated paid comparisons are **not implemented/run**. This distinction prevents promising a difficult but nonexistent 'pi cannot handle it' benchmark.

package/docs/review-assurance.md

@@ -0,0 +1,9 @@
+# Review assurance
+
+`ctg review <pr>` launches one fresh reviewer, with a default 300-second subprocess timeout. `--timeout` accepts integers from 1 through 300. PR metadata lookups each have their own 30-second deadline; this is not a whole-command 300-second deadline.
+
+Approval requires successful execution, a valid final verdict line and preceding single-line `REVIEW_JSON` object (version 1, matching snapshot/head, findings with file, positive line, blocking/nonblocking severity, issue and fix), unchanged local source fingerprint, and the same remote PR head before and after review. Missing head identity fails closed. The source fingerprint has the same exclusions as delivery evidence; it is not a filesystem sandbox. Changes made and reverted during review cannot be detected by endpoint comparison.
+
+Read-only behavior is currently an instruction, not enforced isolation. A reviewer may execute tools; use a disposable checkout with restricted credentials for untrusted repositories. Snapshot checks detect some mutations after the fact, not prevent them. The CLI now persists a three-attempt admission limit per canonical PR URL in this workspace under `.harness/reviews/`. Failed and inconclusive attempts count; changed heads do not reset the allowance. Concurrent attempts are excluded by an exclusive lock. Approved identical snapshots are not rerun. The third non-approved result escalates; further attempts require user intervention. This is not a cross-workspace quota or protection against state-file edits. Interrupted locks are never automatically stolen: confirm the writer is gone and inspect the saved history before manually recovering state.
+
+Review findings are model judgments, separate from test/lint/build evidence. They should identify severity, file and line, rationale, proposed resolution, and uncertainty. A valid verdict does not prove completeness, correctness, or that the reviewer inspected the intended diff. Local context can differ from the PR; the reviewer must use the PR diff as the authoritative change.

package/docs/review-experiment-results.md

@@ -0,0 +1,59 @@
+# Review workflow experiment: not a proven quality improvement
+
+Two matched reruns used the original 52-file voxel-project baseline, identical
+prompt, DeepSeek v4.1 Flash, high thinking, and a 30-minute budget. No generated
+source was repaired by the evaluator before scoring. These are single attempts,
+not controlled evidence of causal performance changes.
+
+| Run | Seconds | Verified usage USD | Playable acceptance |
+| --- | ---: | ---: | --- |
+| Original CTG | 538.50 | 0.318282600 | Failed |
+| Persistent review findings | 420.51 | 0.326691900 | Failed |
+| Mandatory outcome-contract experiment | 407.71 | 0.518784300 | Failed |
+
+The first patched run exercised gameplay handlers in smoke, but ordinary startup
+crashed and coordinate conventions disagreed. The next run tested a real native
+window launch successfully, but rendered geometry, camera-relative strafe and
+player-safe placement still failed independent probes. Both reported verified.
+
+Outcome linkage improved traceability; it did not establish assertion adequacy.
+The original paired experiment ran concurrently with another agent, whereas the
+reruns ran alone; sampling and warm caches also varied. No general speed or cost
+advantage is established. Tests and screenshots are not proof of playability.
+
+The final experiment also exposed unnecessary review retries: invented finding
+IDs, omitted findings arrays, and resubmitting a resolved finding. Resolution
+retries now accept identical evidence idempotently and do not reopen a finding
+being explicitly resolved in the same record. Different evidence cannot overwrite
+an existing resolution; genuinely recurring findings can still be reported.
+
+Outcome contracts are now **opt-in**, rather than inferred from component count.
+Test across CLI, API, persistence, migration and packaging tasks, including simple
+changes, before considering a mandatory policy. Measure false verified finishes,
+successful deliveries, appropriate blocked results, cost and unnecessary friction.
+
+## Follow-up: fresh-context acceptance review and model repairs
+
+A further fresh implementation with generic representation/integration guidance
+still failed single-shot acceptance. A separate fresh CTG reviewer reproduced the
+render/control defects and the implementation model repaired them. Subsequent
+evaluation found intermittent native graphics output; model repair added a
+documented native software-renderer path. A second fresh reviewer found an AABB
+overlap error and a raycast boundary error, which the model repaired with tests.
+Final fresh review approved the core acceptance, with 75 Python tests passing,
+actual native launch, image/state correspondence, camera-relative movement over
+60 angle combinations, safe placement and chunk-isolation probes.
+
+This success required multiple review/repair rounds and extra time beyond the
+original 30-minute single-run comparison. Some interrupted continuations needed
+a fresh repair context. It is not evidence of autonomous single-shot reliability,
+lower cost, or a complete manual play test. Physical pointer input was unavailable.
+The successful general mechanism was fresh-context executable falsification,
+not game-specific rules in CTG. The generated game—not the harness—contains the
+domain-specific fixes.
+
+The experimental `ctg review workspace --request-file original-task.txt` command
+exposes this review mechanism without requiring a pull request. It runs a separate
+context with no delivery extension and does not automatically repair source,
+grant verified status, or make its verdict independent proof. Review subprocess
+tools are not OS-sandboxed; no source modifications are requested by its prompt.

package/docs/tested-planning-roadmap.md

@@ -0,0 +1,58 @@
+# Tested planning and agent-authored workflows
+
+Status: **all six implementation stages tested and merged**. Owner: Carthagent. This is the implementation contract for the six sequential PRs below. Historical live-trial notes are evidence, not current operating instructions, and must remain intact.
+
+## Non-negotiable behavior
+
+For new delivery tasks, no product code, test code, prototypes, arbitrary shell commands or mutation-capable custom tools before a tested plan is approved. Planning is structured data written through harness tools. Read-only discovery remains possible. Approval means readiness to implement, not correctness of future code. Informational tasks never grant mutation permission. Legacy reports remain readable but must pass the new gate before new mutations.
+
+The workflow is discovery → requirements/examples → architecture/workflow → deterministic validation → adversarial review/scenario walkthroughs → revise/retest until blocking findings are resolved → approval → regression tests → implementation → integration/final review. Approval is bound to plan identity, revision and the inspected source snapshot. The first authorized mutation starts implementation; subsequent planned source edits do not invalidate the design approval on every keystroke. A plan revision always relocks implementation. Source changes before implementation begins stale the approval. During implementation, unexpected external edits cannot be distinguished from all legitimate edits without stronger isolation; disclose that limitation.
+
+## Architecture responsibilities and DI
+
+- `planning`: pure contract validation, review receipts, approval lifecycle. No I/O, network or rendering. Inject snapshot hashes/time where needed.
+- `workflow`: pure graph semantics and projections; immutable mandatory gate overlay. No execution or model authority.
+- `planning-access`: fail-closed tool policy, read-only discovery boundary. Inject tool metadata/runner where appropriate. No heuristic shell allowlist.
+- extension/server/CLI: composition roots for persistence, workspace locks and execution. All execution entry points enforce the same approval policy.
+- UI: renders observed state and evidence; never infers success from prose or animation. Workflow, architecture and evidence are distinct views.
+- `plan-advisor`: optional injected classifier port and Jev HTTP adapter. Advisory only; cannot mint approval, modify requirements or bypass checks. No keys/provider calls required for normal operation or tests.
+
+SRP is cohesion and one reason to change, not one function per file. DI exposes time/network/process/storage boundaries; deterministic contract tests verify boundaries, while integration tests cover real entry points.
+
+## Planned contract
+
+A design contains components (responsibility, non-responsibilities, owned requirements, layer, dependencies), ports (owner, input/output/error contracts, adapter, injection mechanism, composition root and test double), scenarios (requirement, component path, input, expected behavior, failure case, concrete assertion, check IDs), risks (blocking/open or resolved with evidence), and workflow (stable nodes, dependency edges and bounded recovery transitions). Exact existing acceptance text stays authoritative. Every criterion requires positive and failure/boundary scenarios. Every declared external dependency must have an injection contract. A structural validator cannot prove the architecture is good or that a scenario is adequate.
+
+Reviews record challenges, walkthroughs and findings against an exact revision, design digest and source fingerprint. Review is explicitly model-authored; reviewers cannot assert independent provenance without an actual separate invocation. No confidence threshold unlocks implementation. Blocking findings must be resolved through a new design revision and fresh validation/review. Optional findings need a recorded disposition.
+
+## Six sequential PRs
+
+| Stage | Deliverable | Acceptance and tests | Status / PR |
+|---|---|---|---|
+| 1 | Planning contract, validator and lifecycle | Missing requirements/scenarios/ports; invalid references; blockers; stale review/approval; revision history; no I/O in policy | Merged [#93](https://github.com/B-icy/Carthagent/pull/93); 335 local tests and all CI green |
+| 2 | Approval gate and mutation restrictions | Default pre-plan protection; shell/custom-tool bypass; informational downgrade; CLI/HTTP check bypass; restore/revision; truthful enforcement scope | Merged [#94](https://github.com/B-icy/Carthagent/pull/94); 337 local tests and all CI green |
+| 3 | Agent-authored workflow and architecture | Stable IDs; DAG prerequisites; explicit bounded recovery; mandatory gate overlay; D2 escaping; old plan rendering | Merged [#95](https://github.com/B-icy/Carthagent/pull/95); 340 local tests and all CI green |
+| 4 | Event-driven workflow/architecture/evidence UI | Current phase, reason locked, findings, evidence, stale states; safe rendering; terminal projection; browser integration | Merged [#96](https://github.com/B-icy/Carthagent/pull/96); 341 local tests and all CI green; local Firefox blocked by snap /tmp restriction |
+| 5 | Adversarial review and scenario loop | Inspection receipt; complete challenges/walkthroughs; finding history; unresolved blocker; repair/revalidate; honest self-review provenance | Merged [#97](https://github.com/B-icy/Carthagent/pull/97); 343 local tests and all CI green |
+| 6 | Optional Jev advisory evaluation | Injected fake/HTTP adapter; no-key baseline; failure/timeout/malformed response; shadow findings, false negatives, latency/cost metrics; no approval authority | Merged [#98](https://github.com/B-icy/Carthagent/pull/98); 348 local tests, real loopback HTTP transport, no-key corpus and all CI pass; no live Jev benchmark |
+
+Each stage: focused tests → quality → PR inspection and cross-platform CI → merge → update this ledger for the next stage. GitHub does not permit self-approval; author review and authorized merge are not independent approval. No silent weakening of requirements to obtain green CI.
+
+## Plan testing performed before implementation
+
+1. Requirement walkthrough: source/test generation is prohibited before approval; planning JSON is allowed through dedicated APIs. No executable planning probes are smuggled through shell.
+2. Boundary walkthrough: requirements map to component owners, contracts and scenario assertions. Fake-only testing is insufficient; tests must include adapter and public entry-point behavior.
+3. Failure walkthrough: malformed design → findings → revise → fresh validation/review; unresolved assumption blocks approval. Provider failures cannot change gate state.
+4. Lifecycle walkthrough: compaction restores receipts; changed revision invalidates approval; changed snapshot before first mutation invalidates it; implementing source changes require final check reruns, not endless approval deadlock.
+5. Enforcement challenge: tool interception is not an OS sandbox. Fail closed for all non-read tools before approval, including unknown tools. Disable raw shell during planning. Do not claim protection from external processes or a malicious host. Baseline execution before approval is unavailable unless a real isolated runner is supplied; report this rather than pretending shell regexes provide isolation.
+6. UI challenge: arbitrary D2 is not executable truth. Agent authors graph semantics; harness owns mandatory gates and observed statuses. Render a shared validated model into D2 and terminal/dashboard projections.
+7. Review challenge: a separate prompt is not independent assurance. Record reviewer provenance honestly, retain findings, bind receipts. Jev cannot certify completeness or authorize mutations.
+8. Scope challenge: preserve legacy report visibility and original failures, but do not grandfather old reports into unapproved mutation. Update stale operating guidance rather than delete historical evidence.
+
+Preimplementation outcome: ready to implement this roadmap sequentially. Completion outcome: the six scoped stages are merged, preserving the limitations below. Known limitation: semantic adequacy and independently verified review quality cannot be proven by schema validation. A paid live Jev benchmark is not authorized by enabling an adapter; use deterministic injected evaluation and clearly distinguish it from provider effectiveness.
+
+## Progress journal
+
+- Stage 6 results and limits: [optional advisor evaluation](plan-advisor-evaluation.md). No service credentials were accessed and no paid/provider request was made. Jev remains optional and outside normal approval flow.
+- Stages 4–6 use `/tmp/ctg-tested-planning`, an isolated Git worktree, to preserve concurrent unrelated provider/TUI changes in the original checkout. Local Firefox was blocked by snap's `/tmp` namespace; CI Firefox passed for stages 4–6. Final JavaScript quality passed 348 tests; Linux/macOS/Windows × Node 22/24 and browser CI were green before each merge. Python validation ran in CI, not locally.
+- Initial repository inspection confirms current plan-existence gate and fixed D2 suffix do not meet this contract. No implementation changes were made before documenting and challenging this plan.

package/docs/tested-planning.md

@@ -0,0 +1,58 @@
+# Tested planning
+
+## Quick start without exhaustive discovery
+
+Use `delivery_design {"action":"guide"}` **before creating a plan** for the compact exact field contract and illustrative example. It does not need approval, execute commands, mutate the workspace, or call Jev. Substitute actual task requirements and real checks; the example is not a ready-made design for your project.
+
+Inspect relevant entry points, callers/types and nearby tests, then submit the first concrete contract. After eight discovery results or two blocked execution attempts, the extension recommends a plan or one targeted unresolved question; after sixteen results it emphasizes excessive discovery. These are advisory checkpoints, not a hard cutoff. Necessary reads remain available. Numeric checkpoint state follows the selected session branch and survives compaction; a new user input resets it and a successful plan suppresses it. Informational requests do not receive these reminders (classification is heuristic, not an authorization decision).
+
+Validation reports offending references and allowed IDs. Repair via `delivery_revise`, preserving every acceptance requirement and output; then validate → inspect → review → approve. Keep unknowns explicit rather than inventing baseline results. Jev, if enabled, runs only at valid inspection and challenges semantic adequacy—not schema syntax. See [Jev configuration and disclosure](jev.md).
+
+
+Context handling: [compact projections and recovery](context-efficiency.md). `delivery_status` returns active obligations rather than the full report history. A large `delivery_design inspect` returns `captureArchive.path`; read the entire immutable capture in pages before authoring review. Its capture ID/digest/source binding and all validation/approval requirements are unchanged. A pointer is not evidence that the plan was read. Full history remains in the report/session; older successful planning exchanges may be referenced by verified archives in outbound model context. before code
+
+New and resumed delivery tasks must test and approve their design before generating product code, tests or executable prototypes. A plan's existence is no longer permission to implement. `--delivery-strict=false` does not bypass this policy.
+
+## Sequence
+
+1. Discover with built-in `read`, `ls`, `find`, `grep`. Shell and unknown/custom tools are blocked before approval, including apparently read-only shell commands. No isolated baseline runner is supplied; do not claim preapproval commands ran.
+2. Call `delivery_plan` with the existing acceptance/check contract and `design` below. Planning data is persisted by the harness, not arbitrary file writes.
+3. Call `delivery_design {action:"validate"}`. Resolve blocking diagnostics using `delivery_revise`.
+4. Call `delivery_design {action:"inspect"}` to capture the exact validated plan, previous findings and unresolved blocker IDs. Read that capture. Record `delivery_design {action:"review",review:{captureId,challenges,walkthroughs,findings,limitations,resolutions:[]}}`. Walk through **every** scenario with `{scenario,trace,assertion}`. Findings have `severity:"blocking"|"advisory"`, `description`, and an explicit `disposition` for advisory findings. Review is model-authored, not independent proof.
+Blocking findings receive harness IDs and cannot disappear through an empty second review. Revise the design, validate and inspect again, then supply `resolutions:[{id,change,evidence}]` for each repaired blocker. Same-revision resolutions are rejected. Findings, validation receipts and revisions remain in history. Capture binds the actual plan snapshot, but does not prove it was read or that a claimed resolution is semantically sufficient.
+
+5. Call `delivery_design {action:"approve"}` only after challenges and iterations. The approval is bound to run, revision, full plan digest and source fingerprint.
+6. Generate regression tests, implement, run checks, and complete final diff-linked review. Existing evidence rules and user-owned validators remain authoritative.
+
+Revisions always relock implementation. Source edits before the first authorized implementation action stale approval. Once implementation starts, planned source edits do not require approval after each keystroke; they still invalidate final verification evidence. Resume restores receipts. Legacy reports remain readable but cannot authorize new commands or writes without a tested design.
+
+Informational plans still finish without a repair loop, but cannot authorize arbitrary process execution. Consequently `advisory` checks cannot be newly executed through the delivery runner without a required, approved design. Existing advisory evidence remains readable. Use `none` for read-only answers.
+
+## Design fields
+
+`design` is planning data, not executable code:
+
+- `components`: `{id,responsibility,excludes:[],layer,dependencies:[],externalDependencies:[],requirements:[]}`. Layers: `core`, `adapter`, `composition`, `presentation`. Requirements use exact acceptance text. Declare explicit non-responsibilities. Core components cannot depend on concrete adapters; `externalDependencies` name owned ports.
+- `ports`: `{id,owner,adapter,compositionRoot,input,output,errors,injection,testDouble,integrationAssertion}`. Owner/adapter/compositionRoot reference component IDs. Declare contracts and where dependencies are injected. Real adapter assertions complement test doubles.
+- `scenarios`: `{id,requirement,kind,path:[],input,expected,assertion,checks:[]}`. Kinds: `positive`, `failure`, `boundary`. Every requirement needs a positive and failure/boundary scenario. Paths name components; checks name existing executable suites. Specify observable assertions, not implementation descriptions.
+- `risks`: `{id,description,status:"open"|"resolved",blocking:boolean,evidence?}`. Blocking open risks prohibit approval; resolved risks need evidence.
+
+SRP means cohesive ownership/reasons to change, not mechanically one function per file. Contract validation detects missing declarations and contradictions, not undeclared hidden dependencies or semantic inadequacy.
+
+## Agent-authored workflow
+
+Optional `workflow:{nodes:[],recovery:[]}` is the canonical graph, not free-form executable D2. Each node declares `{id,title,type,dependsOn:[],requirements:[],components:[],checks:[],inputs:[],artifacts:[],effects:[]}`. Types: `work`, `decision`, `check`, `artifact`. Work nodes reference a `step` (structured ID or `legacy_1` etc.); every step must appear. Decisions declare `condition`; check nodes need check IDs. Effects are `read`, `write`, `execute` declarations, not permissions. IDs beginning `gate_` are reserved.
+
+Prerequisites form a DAG. Recovery transitions declare `{from,to,when,maxAttempts,stop}` with 1–10 attempts. These are proposed bounded recovery routes, **not an executable scheduler**; the agent still performs actions through gated tools and session budgets. D2 is generated from this validated graph. The harness overlays design approval, fresh verification, final review and handoff gates; the model cannot remove those. Legacy plans retain their old D2 and have a canonical fallback projection. Architecture is a separate component/dependency/port projection.
+
+## Workflow, architecture and evidence views
+
+The dashboard Plan panel has three selectable views and a pinned revision/lock explanation. Workflow shows observed current work, node states and recovery routes; architecture shows responsibilities, non-responsibilities, dependency direction and injection contracts; evidence shows execution revisions, logs and stale/failed status. Check buttons are disabled while approval is locked. Proposed decisions/artifacts are never inferred successful.
+
+The terminal supports `/workflow`, `/architecture` and `/evidence` in the side pane. Report-file/tool-result updates refresh the shared projection; dashboard status polling consumes that same projection. This is observed-state refresh, not a claimed ordered event stream. `ctg status --json` includes `planningView` for other consumers. A passing command or an approved plan remains distinct from semantic correctness.
+
+## API and enforcement scope
+
+`POST /api/design` accepts the same action/review fields under the dashboard's authentication and workspace lock. `/api/checks/run`, `ctg check`, and `delivery_check` enforce the same approval policy. Participating tool calls are fail-closed before approval; this is **not an OS sandbox**. External processes, trusted host/extensions, tool-name replacement, raw API state-file tampering and postapproval unexpected edits are outside the guarantee. A tool hook does not hold a cross-process lease for an arbitrary tool's entire execution; avoid concurrent sessions editing one workspace.
+
+Implementation status, blockers and receipts are available through `delivery_status`, report JSON and `/api/status`. See the [six-stage roadmap](tested-planning-roadmap.md) for rollout and outstanding stages. Historical trial notes retain the behavior and failures observed at their original revisions.

package/docs/tui-pickers.md

@@ -0,0 +1,9 @@
+# Command and settings pickers
+
+- In the `/` command palette, **Enter activates the highlighted command once**, even when the typed name is partial. **Tab completes** the command without running it. Escape dismisses the palette without changing the text.
+- `/model` opens model search directly across providers. Type a provider or model name, browse with arrows, and press Enter to switch. The current model is marked independently of the highlighted candidate. Successful selection returns to the prompt.
+- Settings uses the same interaction: Enter opens a row's choices, arrows browse, Enter applies, Escape cancels. Choosing from settings returns to settings. Provider selection is only a model-list filter; it never switches the model by itself. Theme changes are applied only on confirmation, not previewed.
+- Switching models during an active response is rejected with an explanation. While a switch is pending, repeated confirmation is ignored; errors leave the picker open for retry. Escape cancels browsing, not a request already submitted. Ctrl-C remains available.
+- Opening settings does not consume the prompt draft. Activating a slash command consumes that command text, as before.
+
+Validation: `npm run quality` covers keyboard parsing, picker transitions and pending/error behavior. On POSIX, `python3 tools/test-picker-pty.py` starts the offline demo in a real pseudo-terminal and exercises single-Enter opening, model selection, Tab completion and Escape. It uses temporary configuration and makes no provider calls. This is not a substitute for native terminal visual review.