@osolmaz/pi-workflows 0.13.0 → 0.13.2

package/docs/plans/2026-08-24-change-scoped-verification-plan.md

@@ -0,0 +1,419 @@
+---
+title: Make Autoimplement verification change-scoped
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-24
+---
+
+# Make Autoimplement verification change-scoped
+
+Autoimplement and Autodoc must judge the current change, not the complete health of the repository. A check failure that already exists on the base branch must stay visible, but it must not stop unrelated work. A new failure caused by the current change must enter a bounded fix-and-check loop.
+
+Known commands and safe mechanical fixes must run as program actions. The model must handle only work that needs judgment, such as proposing a branch name, editing prose, changing code, or classifying evidence that a direct comparison cannot settle.
+
+This plan also fixes the related workflow problems found during the failed Autoimplement run on 2026-08-24:
+
+- documentation verification returns one Boolean result;
+- a documentation failure stops without a repair loop;
+- an included Autodoc blocker bypasses Autoimplement's blocker challenge;
+- documentation can change before Autoimplement selects a safe workspace;
+- the same model can edit documents and run deterministic checks;
+- repository-wide failures are not compared with the base branch;
+- the final blocked result can lose the original reason and evidence;
+- ordinary node failures can stop without safe recovery;
+- a mistaken missing-plan result can stop without challenge; and
+- documentation failure has no clear handoff back to implementation.
+
+The failed SimpleDoc check that exposed these problems was unchanged on the candidate and a clean `origin/main` worktree. It reported the same 30 renames, 32 frontmatter insertions, and 8 reference updates in both places. Formatting, links, privacy, whitespace, and changed-file digests passed. Autoimplement should have reported the SimpleDoc backlog and continued.
+
+## Goal
+
+Add two reusable internal workflow compositions:
+
+1. workspace preparation, which selects and confirms where edits will happen; and
+2. change verification, which runs checks, compares eligible failures with the base branch, repairs current-change failures, and preserves exact evidence.
+
+Use them in Autodoc first. Then apply the same result and routing rules to Autoimplement's local checks, review commands, CI inspection, and delivery. Keep each stage's external actions separate. Do not add a general effect runner or a workflow-engine primitive.
+
+## Principles
+
+- Prepare the workspace before the first edit.
+- Let the model propose names and make semantic decisions.
+- Let program actions run Git commands, checks, comparisons, and safe mechanical fixes.
+- Judge failures against the current change.
+- Keep all base failures visible.
+- Repair new failures within a fixed limit.
+- Challenge every claimed blocker except explicit cancellation and verified human rejection.
+- Observe a possible partial effect before retrying a mutating step.
+- Keep the graph explicit, durable, bounded, and easy to inspect.
+
+## Workspace selection
+
+Autoimplement gains a `workspaceMode` input with these values:
+
+- `auto`: select the safest allowed mode from the current repository state and authority;
+- `branch`: work in the current checkout on a task branch;
+- `worktree`: work in a standard sibling worktree on a task branch; and
+- `defaultBranch`: work directly on the repository's real default branch.
+
+`auto` is the default. It follows these rules:
+
+1. Keep the current branch when it is already the correct non-default task branch.
+2. For a clean default branch, ask the workspace-planning model for a clear task branch name, then create or confirm that branch programmatically.
+3. When unrelated changes must remain in the current checkout, ask for a task branch name and create a standard sibling worktree programmatically.
+4. Use `defaultBranch` only when the task authority or repository policy explicitly permits direct work on the default branch.
+
+For `branch` and `worktree`, the model proposes the branch name. A program action validates and applies the proposal. Validation rejects an empty name, an invalid Git reference, a reserved or conflicting name, the wrong base, a path outside the standard worktree location, and a proposal that would move or overwrite existing work.
+
+For `defaultBranch`, no task branch or worktree is created. A program action confirms all of these facts before mutation:
+
+- the checked-out branch is the repository's actual default branch;
+- direct default-branch work is authorized by the request or repository policy;
+- the expected base revision is current;
+- existing unrelated changes will not be overwritten or included; and
+- later commit and push actions stay within their separate authority.
+
+Working directly on the default branch does not imply commit, push, merge, release, or deployment authority. Delivery must support a direct-default result: commit and push only when authorized, otherwise leave the verified local change and report it. It must not try to open a pull request from the default branch to itself.
+
+The workspace result becomes the source of truth for later paths. It records:
+
+- mode;
+- repository path;
+- worktree path when applicable;
+- base branch and base revision;
+- work branch;
+- whether direct default-branch work is authorized;
+- pre-existing changed paths;
+- creation or adoption evidence; and
+- the scope that later stages may change.
+
+All later prompts and actions use the prepared absolute path. They do not fall back to the Pi process working directory.
+
+## Programmatic checks
+
+Known checks run through action or shell nodes. The model does not run them through tools inside an agent step.
+
+Each check request records:
+
+- a stable ID;
+- executable and argument array;
+- absolute working directory;
+- timeout;
+- output limit;
+- whether the command is read-only;
+- whether it is eligible for base comparison;
+- whether it supports changed-file scope; and
+- the finding format when the tool provides one.
+
+A command request cannot use a shell wrapper, hidden environment changes, standard input, or an unbounded timeout. Verification records the exit code, signal, duration, stdout, stderr, truncation state, timeout state, and spawn failure. A truncated or incomplete result cannot pass.
+
+Repository guidance remains the first source for command selection. If it gives a complete command list, the workflow uses it without a model turn. If it does not, one model step proposes a structured command plan. Program code validates that plan before execution.
+
+## Candidate and base comparison
+
+When a repository-wide read-only check fails and the output does not prove that the current change caused it, change verification runs the same command on a temporary detached worktree at the selected base revision.
+
+The base action must:
+
+1. create a temporary worktree outside the candidate checkout;
+2. run only checks marked read-only and base-eligible;
+3. use the same executable, arguments, timeout, and output limit;
+4. record setup and dependency limitations;
+5. remove the temporary worktree in a bounded cleanup path; and
+6. preserve cleanup evidence if removal fails.
+
+Comparison first uses stable finding IDs when a tool provides them. Otherwise it normalizes only line endings and the temporary worktree path. It does not remove timestamps, counts, file names, or other facts merely to make outputs match.
+
+The result separates:
+
+- `relatedFailures`: new failures caused by the candidate change;
+- `unrelatedFailures`: matching failures already present on the base;
+- `fixedBaselineFailures`: base failures that the candidate removes;
+- `unknownFailures`: differences that available evidence cannot attribute safely;
+- `untestedChecks`: checks that could not produce complete evidence; and
+- the complete candidate and base command results.
+
+Unrelated failures are reported but do not fail the current change. Unknown failures require bounded model judgment or blocker challenge. A `ready` result requires complete candidate checks and no related or unknown failure.
+
+## Repair and recheck
+
+A change-related failure enters a bounded repair loop. Start with two repair attempts. Keep the limit explicit in the workflow graph.
+
+Mechanical repair is allowed only when the command plan declares:
+
+- the direct executable and arguments;
+- the exact changed files it may edit;
+- the check IDs it is expected to fix;
+- its timeout; and
+- the expected type of diff.
+
+The action records the diff before and after the fixer. It rejects an edit outside the declared files. It does not infer or run a broad repository migration such as applying all SimpleDoc recommendations to an old repository.
+
+When no safe mechanical fix exists, a model repair step receives the approved plan plus related and unknown failures. It does not receive unrelated failures as work to fix. It may make semantic documentation or code changes only inside the prepared workspace and declared scope.
+
+After each repair, the same programmatic checks run again. Stop the loop when:
+
+- verification succeeds;
+- the repair makes no diff;
+- the failure fingerprint repeats; or
+- the attempt limit is reached.
+
+An exhausted repair loop creates a complete blocker claim and goes to blocker challenge. It does not stop directly.
+
+## Shared verification result
+
+Replace stage-specific Boolean results with one internal result shape. It uses these routes:
+
+- `ready`: all current-change checks passed;
+- `repairable`: a safe repair path exists;
+- `needsJudgment`: evidence is complete but attribution or repair needs model judgment; and
+- `blocked`: a material outside-scope problem remains after safe recovery.
+
+The result records:
+
+- originating workflow and qualified node;
+- current workspace identity;
+- changed files;
+- candidate commands;
+- base commands;
+- related, unrelated, fixed, unknown, and untested findings;
+- repair attempts and failure fingerprints;
+- output references;
+- reason; and
+- concrete evidence.
+
+Keep large command output in the existing action result and refer to it from findings. Do not copy large output into each failure entry.
+
+## Autodoc changes
+
+Autodoc keeps model steps for these tasks:
+
+- finding or confirming the selected plan;
+- choosing canonical documentation;
+- writing or updating prose; and
+- repairing semantic documentation failures.
+
+Autodoc uses program steps for:
+
+- workspace preparation when an update is required;
+- documentation checks;
+- base comparison;
+- safe mechanical fixes;
+- result classification when exact comparison is sufficient; and
+- graph routing.
+
+Replace `verifyDocumentation` and its `passed` Boolean with the shared change-verification composition. A matching base SimpleDoc failure returns `ready` with visible unrelated failures. A new documentation failure enters repair and recheck.
+
+Autodoc's blocked exit must preserve the originating node, exact command evidence, related and unrelated failures, all repair attempts, and the accepted reason. Its blocked reason must not ignore verification output.
+
+## Autoimplement changes
+
+Run workspace preparation before the first edit-capable node. Read-only plan discovery may run first. Documentation updates and implementation must use the prepared workspace.
+
+Route these blocker sources through one challenge path:
+
+- included Autodoc blocked exits;
+- missing-plan claims;
+- implementation classification;
+- local verification;
+- review command failures;
+- review findings that claim an external block;
+- CI inspection and CI command failures;
+- delivery failures;
+- exhausted repair loops; and
+- ordinary node execution failures that safe recovery cannot resolve.
+
+Explicit cancellation and verified human rejection remain terminal and bypass challenge.
+
+A mistaken missing-plan claim may return to bounded discovery or adopt a plan already proved by the input or canonical documents. The challenge cannot invent an initial plan.
+
+The blocker challenge must return the next practical stage, such as plan discovery, documentation, implementation, repair, review, CI inspection, delivery, redesign, or terminal blocked. A stable counter and failure fingerprint prevent loops.
+
+## Ordinary node failures
+
+Extend the current timeout fallback into one bounded step-failure recovery path. Classify workflow steps as:
+
+- pure;
+- read-only;
+- idempotent mutation; or
+- mutation that needs observation before retry.
+
+Pure and read-only failures can retry within the limit. For a mutating step, inspect durable repository or remote state first. Adopt an effect that already completed. Retry only the missing effect. Send an unsupported or ambiguous effect to blocker challenge with exact evidence.
+
+This policy applies to both timeouts and ordinary failed outcomes. It never recovers explicit cancellation.
+
+Examples:
+
+- inspect the current diff before repeating a model edit;
+- inspect commits before repeating a commit;
+- inspect the remote branch after a lost push response;
+- inspect existing comments before posting again;
+- inspect merge state before repeating merge; and
+- inspect recorded action output before rerunning a command batch.
+
+## Later Autoimplement stages
+
+Apply the same related, unrelated, unknown, repairable, and blocked meanings to:
+
+- local verification;
+- reviewer command execution;
+- CI inspection; and
+- delivery verification.
+
+Keep separate adapters for local commands, reviewer output, CI providers, pull-request comments, commits, pushes, and merges. Do not place all effects behind one universal runner.
+
+CI failures that predate the candidate or belong to an unrelated target remain visible and do not fail the current change. When local reproduction is not possible, use provider evidence and model judgment. Never classify an unavailable or truncated result as unrelated automatically.
+
+## Blocker evidence
+
+Create a durable blocker claim before challenge. It records:
+
+- qualified source node;
+- node attempt ID;
+- current route;
+- exact reason;
+- evidence references;
+- failed commands;
+- related and unrelated failures;
+- recovery attempts;
+- alternatives checked; and
+- the authority or external fact that could prevent progress.
+
+Parent workflows preserve included child evidence. The final blocked result uses the accepted claim directly. It must not replace available evidence with a generic reason or `null`.
+
+## Implementation order
+
+Implement the change in these complete slices:
+
+1. Add the regression for the 2026-08-24 SimpleDoc incident.
+2. Add shared types, validation, finding comparison, and evidence helpers.
+3. Add workspace planning and programmatic workspace preparation with all four modes.
+4. Add candidate checks, base checks, comparison, and temporary worktree cleanup.
+5. Add mechanical and semantic repair with bounded recheck.
+6. Migrate Autodoc and remove the Boolean verification route.
+7. Put workspace preparation before Autoimplement mutation and pass its path to every later stage.
+8. Route all blocker claims through one challenge and preserve qualified child evidence.
+9. Extend timeout fallback to safe ordinary-failure recovery.
+10. Apply the shared verification meanings to local checks, review, CI, and delivery.
+11. Update skills, workflow documentation, examples, and built-in revision data.
+12. Run focused, full, persistence, and real-Pi tests before release.
+
+Each slice must compile and pass its focused tests. Use a hard replacement during alpha. Do not keep the old Boolean route, duplicate verification path, compatibility alias, or feature flag.
+
+## Tests
+
+### Workspace
+
+- A clean default branch in `auto` mode gets an LLM-proposed, programmatically created task branch.
+- An existing correct task branch is adopted without creating another branch.
+- A dirty default checkout gets an LLM-proposed branch in a standard sibling worktree.
+- Explicit `branch` and `worktree` modes use the proposed name only after programmatic validation.
+- `defaultBranch` succeeds only with direct-work authority and the actual default branch checked out.
+- `defaultBranch` does not imply commit or push authority and never opens a pull request to itself.
+- Detached HEAD, wrong base, invalid name, name conflict, hook failure, and worktree cleanup failure preserve evidence and route safely.
+- Existing user changes are never stashed, reset, moved, overwritten, or included.
+- Restart adopts the same prepared workspace instead of creating another one.
+
+### Verification
+
+- All candidate checks pass.
+- Candidate and base fail with the same SimpleDoc backlog; the run reports it as unrelated and continues.
+- A candidate-only documentation failure is related.
+- A base-only failure is recorded as fixed by the candidate.
+- Base setup or command failure stays unknown.
+- Timeout, spawn failure, cancellation, and output truncation cannot pass.
+- Finding order and temporary worktree paths do not cause false differences.
+- Only read-only base-eligible checks run on the base.
+- Temporary base worktrees are cleaned after success, failure, restart, and cancellation.
+
+### Repair
+
+- An allowlisted formatter changes only declared files and verification then passes.
+- A fixer that changes an undeclared file is rejected with the diff preserved as evidence.
+- A broad repository migration is not run automatically.
+- Semantic repair sees related and unknown failures, not unrelated backlog.
+- No diff, repeated fingerprint, and attempt exhaustion stop the loop and enter blocker challenge.
+
+### Routing and evidence
+
+- An included Autodoc blocker reaches the shared challenge.
+- A mistaken missing-plan claim retries discovery or adopts proved input without inventing a plan.
+- Every non-exempt blocker source reaches challenge.
+- Explicit cancellation and verified human rejection stay terminal.
+- Qualified child evidence survives composition, restart, and final presentation.
+- The final blocked result names the source node, commands, reason, evidence, and recovery attempts.
+
+### Failure recovery
+
+- Safe read-only and pure steps retry within the limit.
+- A partial local edit is inspected before continuation.
+- A lost push or comment response is adopted when the remote effect exists.
+- An uncertain consequential effect is not replayed blindly.
+- Repeated failures stop at the bounded challenge path.
+- Existing timeout behavior remains covered by the new general path.
+
+### Complete workflow
+
+- A real-Pi Autoimplement fixture with a matching base SimpleDoc failure reaches implementation.
+- A change-related documentation failure is repaired and rechecked.
+- A true repository-rule or authority blocker ends with complete evidence.
+- Documentation, local checks, review, CI, and delivery use the same failure meanings.
+- Old terminal run data remains readable.
+- Active runs with an incompatible built-in revision refuse unsafe resume.
+
+## Acceptance criteria
+
+- No edit-capable node runs before workspace confirmation.
+- The model proposes every new branch name; program actions validate and create branches and worktrees.
+- `auto`, `branch`, `worktree`, and `defaultBranch` modes work as specified.
+- Known checks and mechanical fixes run programmatically.
+- Candidate and base results are recorded separately.
+- Matching base failures remain visible and do not block the current change.
+- New failures enter a bounded repair and recheck loop.
+- No included blocker bypasses challenge.
+- Missing-plan and ordinary-failure claims have bounded recovery.
+- Final blocked results preserve the original reason and evidence.
+- The same policy applies to documentation, local verification, review, CI, and delivery.
+- The implementation uses existing workflow primitives and adds no Pi core change or engine primitive.
+- Full repository and real-Pi tests pass.
+
+## Rollout
+
+This is a hard built-in replacement under the alpha policy.
+
+Land the pure contracts and tests first. Then land workspace preparation, Autodoc migration, Autoimplement blocker and failure recovery, and later-stage adapters in that order. Keep each commit complete and reversible.
+
+Finish or cancel active runs that use the old built-in definitions before package reload. Old terminal runs remain readable. An active run with an incompatible source revision continues to use the existing revision guard and must restart rather than mixing graphs.
+
+After implementation, update [Workflow authoring reference](../workflows.md), [Workflow composition](../WORKFLOW_COMPOSITION.md), the Autoimplement and Autodoc skills, examples, and built-in revision records. Reload or restart Pi and verify discovery through the installed package path.
+
+Do not release or deploy this change without separate authority.
+
+## Boundaries
+
+- Do not modify Pi core or use a private Pi API.
+- Do not add a workflow-engine primitive, hidden retry, service, database, daemon, or external store.
+- Do not change SimpleDoc, Git, GitHub, CI provider, or target repository behavior.
+- Do not require repositories to add a machine-readable quality manifest.
+- Do not run broad repository migrations automatically.
+- Do not use the model for deterministic command execution, counting, comparison, or routing.
+- Do not hide baseline, nonzero, unknown, or truncated command results.
+- Do not overwrite, stash, reset, or silently move existing user work.
+- Do not merge different remote effects into one universal runner.
+- Do not preserve the superseded alpha behavior through compatibility code.
+
+## Contract impact
+
+- **Session state:** normal workflow prompts, action results, model results, and final presentation only.
+- **Other persistent data:** normal node outputs in the existing SQLite state. No new persistence location.
+- **Pi internals:** none.
+- **Public Pi API:** existing documented extension and tool interfaces only.
+- **Autoimplement input:** add optional `workspaceMode` with `auto`, `branch`, `worktree`, and `defaultBranch`. Omission means `auto`.
+- **Autodoc input:** add optional base, scope, workspace mode, and prepared-workspace fields so standalone and included runs use the same safety rules.
+- **Public pi-workflows API:** existing `agent`, `action`, `shell`, `compute`, `includeWorkflow`, named exits, structured outputs, command batches, and edge routing. Shared verification and workspace result contracts remain internal unless later use proves a public need.
+
+## Related plans
+
+- [Confirm blockers before autoimplement stops](2026-08-20-autoimplement-blocker-challenge-plan.md)
+- [Run independent commands in bounded batches](2026-08-20-bounded-command-batches-plan.md)
+- [Add Autoimplement timeout fallback](2026-08-21-autoimplement-timeout-fallback-plan.md)
+- [Add shared plan-change approval](2026-08-21-plan-change-approval-policy-plan.md)

package/docs/plans/2026-08-25-autoplan-user-intent-capture-plan.md

@@ -0,0 +1,107 @@
+---
+title: Capture the user's complete intent in Autoplan
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-25
+---
+
+# Capture the user's complete intent in Autoplan
+
+Autoplan must begin by asking the model to capture the user's instructions from the conversation. The result is one text value named `originalUserInstructions`. This value is the authoritative task text for every later planning step.
+
+The capture instruction must tell the model to include everything that the user has instructed for the intended purpose in the given context. This includes relevant earlier messages and queued messages that are present in the model context. When several messages contribute, the model must preserve their wording and order in one text value. It must not summarize, rewrite, explain, label, omit, or add instructions.
+
+The model is the authority for the captured text. Validation checks only that the result is a non-empty string. It does not compare the text with Pi session entries. After acceptance, the workflow must preserve the exact string, including its internal whitespace.
+
+## Selected design
+
+Add one mandatory `agent` node before Autoplan's existing `frame` node. The node returns this shape:
+
+```json
+{
+  "originalUserInstructions": "one text value"
+}
+```
+
+The field is a string. It is not an array of messages or message objects.
+
+Every later Autoplan agent prompt must include the accepted string explicitly. The framing, practical candidates, ideal end state, selection, and implementation plan must use it as the authoritative user instructions. The existing structured input remains supplemental:
+
+- `problem` can provide a caller-supplied description and can still support the run title;
+- `scope` states the authorized scope;
+- `constraints` carries explicit limits;
+- `previousPlan` carries a plan that may need review; and
+- `newEvidence` carries evidence that can affect the plan.
+
+The final ready and blocked outputs must include `originalUserInstructions` for audit and downstream use. The node output and final output remain durable through the existing workflow run store.
+
+## Implementation plan
+
+### 1. Add the intent result contract
+
+Add a result type with one `originalUserInstructions` string. Add a validator that rejects a missing, non-string, or whitespace-only value and returns the original string without trimming or normalization.
+
+**Where:** `src/builtins/autoplan.workflow.ts` and focused Autoplan tests.
+
+**Verify:** Tests accept internal whitespace unchanged and reject empty or whitespace-only text. Type and runtime checks reject arrays and message objects.
+
+### 2. Add the first Autoplan node
+
+Add a mandatory intent-capture agent before `frame` and make it the workflow entry node. Its prompt must tell the model to:
+
+- inspect the conversation context;
+- include everything the user has instructed for the intended purpose in that context;
+- include relevant earlier or queued user messages that are present in context;
+- preserve the wording and order when several messages contribute;
+- return one `originalUserInstructions` text string; and
+- not summarize, rewrite, explain, label, omit, or add instructions.
+
+Route this node directly to `frame` after successful validation.
+
+**Where:** `src/builtins/autoplan.workflow.ts`.
+
+**Verify:** Graph tests prove that the new node is first and mandatory. Prompt tests check the complete single-string instruction and the direct route to `frame`.
+
+### 3. Use the captured text throughout planning
+
+Include `originalUserInstructions` explicitly in every later Autoplan agent prompt: `frame`, `propose`, `ideal`, `choose`, and `plan`. Keep scope, constraints, previous plans, new evidence, and earlier step outputs as supplemental context. Do not let `input.problem` replace the captured instructions.
+
+**Where:** `src/builtins/autoplan.workflow.ts` and focused prompt tests.
+
+**Verify:** Use a distinct captured string and caller problem in tests. Confirm that every later agent prompt contains the captured string and does not present the caller problem as the authoritative instructions.
+
+### 4. Preserve the text in final results
+
+Add `originalUserInstructions` to both ready and blocked result types and final values. Read it from the accepted capture output without changing it.
+
+**Where:** `src/builtins/autoplan.workflow.ts` and built-in workflow tests.
+
+**Verify:** Ready and blocked runs return the exact captured string. Resume and normal run persistence continue through the existing node-output and final-output records.
+
+### 5. Update the public workflow reference
+
+Document the mandatory capture step, the one-string contract, model authority, later prompt use, and final-output field in the built-in Autoplan section.
+
+**Where:** `docs/workflows.md`.
+
+**Verify:** Documentation checks pass, and the reference agrees with the implementation and tests.
+
+## Boundaries
+
+- Use existing `agent`, `compute`, edge, validation, output, and persistence behavior.
+- Do not change Pi core or private Pi APIs.
+- Do not add session-message inference, conversation bindings, an amendment journal, or a workflow-engine primitive.
+- Do not compare the model's text with session history.
+- Do not add aliases, fallback behavior, dual paths, feature flags, a parallel schema version, or compatibility shims.
+- Do not publish a package or update downstream package pins as part of this change.
+
+## Verification
+
+Run:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+git diff --check
+```

package/docs/session-event-journal.md

@@ -45,14 +45,13 @@ The current event types are:
 - `assistant_event`
 - `message_finished`
 - `tool_execution_started`
-- `tool_execution_updated`
 - `tool_execution_finished`
 
 Unknown future event types remain visible to generic readers.
 
 ## Write rules
 
-The recorder queues hot-path Pi events in memory and writes bounded batches. One transaction writes the complete batch, updates the segment count, increments the segment resource revision, and appends its audit event.
+The recorder stores lifecycle boundaries and settled content. It does not store token deltas or incremental tool progress. It queues these bounded records in memory. One transaction writes each complete batch and updates the segment count. The session-event rows are the audit journal; the store does not add one generic event for each flush.
 
 The writer checks:
 
@@ -68,7 +67,7 @@ Workflow execution does not fail because temporal capture failed. The run and th
 
 ## Settled entries
 
-A `message_finished` event can refer to the Pi entry ID that settled the message. Replay first shows temporal deltas, then switches to the verbatim entry when that settled link is available.
+A `message_finished` event can refer to the Pi entry ID that settled the message. Replay uses settled assistant content and switches to the verbatim entry when that link is available.
 
 Agent workflow steps also store their first and last Pi entry IDs. This makes the conversation slice for each step explicit without changing Pi session data.
 

package/docs/workflows.md

@@ -437,11 +437,11 @@ runs.
 ### Built-in plain summary
 
 The built-in `plain-summary` workflow turns supplied structured data into one
-short normal assistant message. Its input has `source`, `purpose`, optional
+normal assistant message. Its input has `source`, `purpose`, optional
 `mustInclude`, optional `maxChars`, optional `maxSentences`, and `format` set to
-`paragraphs`, `bullets`, or `mixed`. The workflow defaults to 2,000 characters,
-five sentences, and mixed format. These are workflow-specific limits;
-`assistantMessage()` itself has no default limit.
+`paragraphs`, `bullets`, or `mixed`. The workflow applies no character or
+sentence limit by default. A caller can request either limit with a positive
+integer. `assistantMessage()` itself also has no default limit.
 
 The summarizer uses only the supplied source, treats instructions inside that
 source as data, keeps required points, and returns the same text as its
@@ -452,11 +452,38 @@ before the parent continues.
 
 ### Built-in planning and implementation
 
-The built-in `autoplan` workflow records two through four practical candidates,
-describes the ideal separately, chooses one option, records a rejection reason
-for every other explicit option, and writes a detailed plan. It then includes
-`plain-summary` to show the chosen plan, its main steps, and the rejected options
-in one short assistant message. The detailed records remain in the run bundle. The standalone `autodoc` workflow finds an already selected plan, records it in canonical documentation, verifies those documents, and never devises or implements. The built-in `autoimplement` workflow finds a clear existing plan from explicit input, conversation context, or referenced canonical documents. It blocks when no clear plan exists. An explicit plan bypasses autodoc only when a current-document receipt carries its matching plan digest; otherwise autodoc inspects and adopts or updates the canonical documents. Later invalidating evidence returns to `autoplan` followed by `autodoc`.
+The built-in `autoplan` workflow first asks the model to capture everything the
+user has instructed for the intended purpose in the available conversation
+context. Relevant earlier and queued user messages must keep their wording and
+order. The model returns one `originalUserInstructions` string and must not
+summarize, rewrite, explain, label, omit, or add instructions. Validation checks
+only that the string is not empty and preserves the accepted text without
+normalization. Every later Autoplan agent prompt includes this string as the
+authoritative user instructions. Structured run input such as scope,
+constraints, a previous plan, and new evidence remains supplemental. Ready and
+blocked final outputs include the same string for audit and downstream use.
+
+Autoplan then records two through four practical candidates, describes the ideal
+separately, chooses one option, records a rejection reason for every other
+explicit option, and writes a detailed plan. It includes `plain-summary` to show
+the chosen plan, its main steps, and the rejected options in one assistant
+message without a character or sentence limit. The detailed records remain in
+the run bundle. See
+[Capture the user's complete intent in Autoplan](plans/2026-08-25-autoplan-user-intent-capture-plan.md)
+for the selected design and implementation plan.
+
+The standalone `autodoc` workflow finds an already selected plan, records it in
+canonical documentation, and never devises or implements. It prepares a safe
+workspace only when documentation must change. Program actions run candidate
+checks, compare eligible failures with the base revision in a temporary
+detached worktree, and keep matching baseline failures visible without blocking
+the current change. The built-in `autoimplement` workflow finds a clear existing
+plan from explicit input, conversation context, or referenced canonical
+documents. A missing-plan claim and every other non-exempt blocker enter one
+bounded challenge path. An explicit plan bypasses autodoc only when a
+current-document receipt carries its matching plan digest; otherwise autodoc
+inspects and adopts or updates the canonical documents. Later invalidating
+evidence returns to `autoplan` followed by `autodoc`.
 
 The built-in `plan-approval` workflow offers `continue`, `stop`, and exact-text `replan` exits. Its shared policy uses `auto`, `required`, or `skip` mode. Omitted policy defaults to `auto`: ask audience `operator`, then continue with the exact plan after 10 minutes without an answer. Required mode waits for a human. Skip mode creates no decision. Stop and replan always require a human answer.
 
@@ -464,18 +491,13 @@ The internal plan-change workflow composes Autoplan, Autodoc, plan approval, and
 
 Autoimplement runs independent commands through bounded command batches. A batch is an ordinary function action that calls the public `runCommandBatch` helper. Each command has a stable ID, executable, arguments, absolute working directory, timeout, and output limit. Results stay separate and return in input order. One command uses the same path with concurrency one.
 
-Autoimplement gives `implement` an eight-hour deadline. When a supported
-long-running agent node times out, one shared read-only fallback inspects the
-current repository, accepted workflow outputs, and relevant pull-request state.
-It then retries the timed-out stage or routes to verification, review, CI,
-delivery, the existing redesign workflow, or blocked. The fallback can run at
-most three times in one Autoimplement run. Its own failure or timeout is
-terminal. Cancellation remains immediate and never enters fallback. A repeated
-effect step first checks what already exists and performs only missing work.
-This graph fallback starts after the timed-out turn ends and is separate from
-successor-turn delivery.
+Autoimplement prepares the workspace before its first edit-capable node. `workspaceMode` accepts `auto`, `branch`, `worktree`, or `defaultBranch`. Auto mode adopts a current task branch, creates a model-named branch from a clean default branch, or creates a model-named standard sibling worktree when the default checkout has existing work. Program actions validate and apply names. Direct default-branch work requires explicit authority and does not imply commit, push, merge, or release authority. Every later stage uses the prepared absolute path.
 
-Autoimplement uses batches for pi-reviewer, pending CI watches, and local verification commands from independent repositories. It keeps model turns, fixes, pushes, comment changes, merges, and releases in their existing order. Reviewer commands are tied to the repository, base branch, pushed head, and relevant dependency fingerprint. A later review round includes only repositories whose head or dependency fingerprint changed. P0 or P1 work still requires another review. P2-only work can be addressed and verified without another reviewer run only because of that P2 work.
+Autoimplement gives `implement` an eight-hour deadline. When a supported step fails or times out, one shared bounded recovery step inspects accepted outputs and durable repository or pull-request state. It adopts a completed effect or retries only a missing effect. Cancellation remains immediate and never enters recovery. Unsupported or uncertain effects create a qualified blocker claim before challenge.
+
+Local verification uses the shared change-verification composition. Direct program actions run candidate checks and read-only base-eligible checks with the same command, arguments, timeout, and output limit. Results separate related, unrelated, fixed-baseline, unknown, and untested findings. Matching base failures do not block the candidate. Related failures enter a two-attempt mechanical or semantic repair loop. Unknown or incomplete evidence needs bounded judgment, and truncated, timed-out, cancelled, or spawn-failed output cannot pass.
+
+Autoimplement uses batches for pi-reviewer and pending CI watches. It keeps model turns, fixes, pushes, comment changes, merges, and releases in their existing order. Reviewer commands are tied to the repository, base branch, pushed head, and relevant dependency fingerprint. A later review round includes only repositories whose head or dependency fingerprint changed. P0 or P1 work still requires another review. P2-only work can be addressed and verified without another reviewer run only because of that P2 work.
 
 Autoimplement inspects every pull request before it waits for CI. It accepts only supported pending `gh pr checks --watch` or `gh run watch` descriptors and binds each one to the validated pull request as `gh pr checks <PR URL> --watch`. Repository and pull-request overrides are rejected. One watch lasts at most five minutes. A failed or timed-out watch affects only its pull request. When checks remain pending, the model runs more useful local tests before checking CI again. Autoimplement does not invent an ETA.
 
@@ -684,7 +706,7 @@ possible. Defaults worth knowing:
   is explicit user control. When no run is live but the widget still shows a parked or finished run,
   the command clears the widget.
 - One workflow runs per session at a time.
-- After the workflow tool accepts an agent-step submission, the extension removes any assistant tail text from the rest of that agent run. The next workflow message is the visible continuation. A deferred intent makes a workflow prompt, presentation, and factual fallback compete to provide one successor turn, so an abort cannot produce two continuation turns.
+- After the workflow tool accepts an agent-step submission, any assistant text that follows remains visible. The next workflow message continues the graph. A deferred intent makes a workflow prompt, presentation, and factual fallback compete to provide one successor turn, so an abort cannot produce two continuation turns.
 - Agent nudges: if the model ends its turn without submitting the pending
   step, it gets a reminder, twice by default, then the step fails.