ytdb-slate 0.14.0 → 0.15.0

package/README.md

@@ -2,7 +2,9 @@
 
 [![CI status](https://github.com/JetBrains/ytdb-slate/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/JetBrains/ytdb-slate/actions/workflows/ci.yml)
 
-Slate is a multi-agent orchestration extension for the [pi coding agent](https://pi.dev). You work in one interactive pi session, the main session. A bounded action is a focused task with a clear limit. A worker thread is an isolated pi session that researches, implements, or reviews changes. Slate sends bounded actions to separate worker threads. Each worker thread returns a short structured summary called an episode. A review workflow adds reviewers for risks that you approve or for work above a size threshold.
+Slate is a multi-agent orchestration extension for the [pi coding agent](https://pi.dev). You work in one interactive pi session, the main session. A bounded action is a focused task with a clear limit. A worker thread is an isolated pi session that researches, implements, or reviews changes. Slate sends bounded actions to separate worker threads. Each worker thread returns a short structured summary called an episode. A review workflow adds reviewers for risks the orchestrator proves or for work above a size threshold.
+
+The developers of the [YouTrackDB](https://github.com/JetBrains/youtrackdb) database use Slate in production development.
 
 ## What Slate does
 
@@ -14,6 +16,8 @@ Slate is a multi-agent orchestration extension for the [pi coding agent](https:/
 
 ## Quick start
 
+Slate requires pi 1.4.0 or later. Older pi can still load the package, but it is not supported. Slate provides no runtime version warning.
+
 You need an installed and authenticated [pi coding agent](https://pi.dev/docs/latest/quickstart). From your project directory, install a pinned Slate version:
 
 ```bash
@@ -36,7 +40,7 @@ Try a request with a clear outcome:
 Add input validation to the account settings endpoint. First research the relevant code and tests. Show me the proposed plan and risks before implementation.
 ```
 
-Slate asks for required decisions before editing code. It delegates work after workflow gates allow it. Slate shows a short workflow summary when orchestrator mode is on at interactive startup or when you turn it on. A saved `startupSummary: false` choice stops automatic display. The summary disappears when you send your first prompt to the model.
+Slate asks for required decisions before editing code. It delegates work after workflow gates allow it. The workflow summary is off by default. Run `/slate summary on` to save an opt-in. The panel appears at the next interactive startup or mode activation, not when you save the choice. The summary disappears when you send your first prompt to the model. A handoff successor keeps the current panel visibility instead of using the saved choice.
 
 Run `/slate off` to stop Slate's delegation and remove the summary. `/slate summary off` also removes it. Toggling orchestrator mode off with `/slate` removes it too. Other slash commands leave it visible unless they reload or replace the session. `/reload`, `/new`, `/resume`, and `/fork` clear the panel when they reload or replace the session. Slate then shows it only when orchestrator mode is on and the saved choice allows automatic display. Run `/slate summary` to show it at any time. See [Commands](#commands).
 
@@ -57,13 +61,13 @@ test-quality defects, unreadable user-facing prose, licensing exposure,
 non-local logic defects, consumer contract breaks, governing-rule defects, and
 unreported failures.
 
-The orchestrator records risks for the change and each track. You approve or reject each named proof. Approved proofs select design gates and reviewers. A track with a proved risk gets one general reviewer and its required specialists. An implementer's approximate track size above 100 added plus removed lines also adds the general reviewer unless the track changes only documents that neither ship as code nor run. Lockfiles, migration files, and generated output do not count. A track that the orchestrator estimates above 100 such lines needs a high-level design before implementation, including when it changes only documents. A track with neither review trigger gets no routine implementation reviewer. See [workflow](docs/track-workflow.md) and [focus areas](docs/blast-radius.md) for the rules. Optional draft pull requests cover each level with code tracks. A change without nested tracks has at most one pull request. Each design track needs your explicit acceptance of its whole subtree, which contains that track and its descendants. Final acceptance of the whole change remains a separate decision. Only you merge pull requests. See [recursive workflow](docs/recursive-workflow.md) for nested planning, repair children, and acceptance.
+The orchestrator records risks for the change and each track. The orchestrator judges each named proof and selects design gates and reviewers. You can inspect the assessment and direct changes. A track with a proved risk gets one general reviewer and its required specialists. An implementer's approximate track size above 100 added plus removed lines also adds the general reviewer unless the track changes only documents that neither ship as code nor run. Lockfiles, migration files, and generated output do not count. A track that the orchestrator estimates above 100 such lines needs a high-level design before implementation, including when it changes only documents. A track with neither review trigger gets no routine implementation reviewer. See [workflow](docs/track-workflow.md) and [focus areas](docs/blast-radius.md) for the rules. Optional draft pull requests cover each level with code tracks. A change without nested tracks has at most one pull request. Each design track needs your explicit acceptance of its whole subtree, which contains that track and its descendants. Final acceptance of the whole change remains a separate decision. Only you merge pull requests. See [recursive workflow](docs/recursive-workflow.md) for nested planning, repair children, and acceptance.
 
 ## Product principles
 
-- **Control without reading every line.** Many coding agents produce code that the developer accepts without reading it. Slate keeps you in control in a different way. It gives you higher-level views of the work: approved risks, designs, and review results. You direct and check each change through these views, so you do not need to read all of the generated code.
-- **Quality before cost, within limits.** We expect the cost of model use to fall over time. Slate therefore spends more model work on code quality, up to a reasonable limit. For example, Slate adds reviewers for approved risks and for large tracks that change code.
-- **Cost in proportion to the change.** The cost of a change should grow in proportion to its complexity. A small track with no approved risk gets no design gate and no routine implementation reviewer. A larger or riskier track can add design steps, review steps, or both.
+- **Control without reading every line.** Many coding agents produce code that the developer accepts without reading it. Slate keeps you in control in a different way. It gives you higher-level views of the work: proved risks, designs, and review results. You direct and check each change through these views, so you do not need to read all of the generated code.
+- **Quality before cost, within limits.** We expect the cost of model use to fall over time. Slate therefore spends more model work on code quality, up to a reasonable limit. For example, Slate adds reviewers for proved risks and for large tracks that change code.
+- **Cost in proportion to the change.** The cost of a change should grow in proportion to its complexity. A small track with no proved risk gets no design gate and no routine implementation reviewer. A larger or riskier track can add design steps, review steps, or both.
 
 ## Commands
 
@@ -74,7 +78,7 @@ The orchestrator records risks for the change and each track. You approve or rej
 | `/slate` | Toggle orchestrator mode. |
 | `/slate summary` | Show the workflow summary in any mode, even when automatic display is off. |
 | `/slate summary off` | Stop automatic display and remove a visible summary. |
-| `/slate summary on` | Allow automatic display when orchestrator mode is on. |
+| `/slate summary on` | Save automatic display for the next startup or mode activation. |
 | `/slate effective` | Show the effective logical-model policy and remembered route selections. |
 | `/slate handoff [focus]` | Prepare a new-session handoff, with an optional focus. |
 | `/slate resume` | Clear a context-budget pause and accept user prompts again. |
@@ -101,9 +105,10 @@ See [`docs/roadmap.md`](docs/roadmap.md) for details.
 
 ## Shipped docs
 
-These documents define workflow and reference behavior. Slate cites workflow documents by installed path in its numbered system-prompt rules.
+These documents define workflow and reference behavior. Slate uses installed paths for workflow citations in its numbered system-prompt rules. The filenames `change-records.md` and `recursive-workflow.md` resolve beside the Lifecycle document, `track-workflow.md`.
 
 - [`docs/blast-radius.md`](docs/blast-radius.md) defines focus areas, proofs, and review coverage.
+- [`docs/change-records.md`](docs/change-records.md) defines identifiers, code ranges, design markers, and safe writes to change records.
 - [`docs/configuration.md`](docs/configuration.md) defines settings, merge rules, and path warnings.
 - [`docs/context-budget.md`](docs/context-budget.md) defines context limits, model overrides, and measured prompt sizes.
 - [`docs/delivery-packages.md`](docs/delivery-packages.md) — the compact track and change package format, read only before package preparation

package/docs/blast-radius.md

@@ -10,18 +10,19 @@ composition and finding handling.
 The orchestrator judges all eleven focus areas for the change and independently
 for every track. An area is **NAMED** when the orchestrator submits its
 four-part proof. The proof states the defect class, the place where the defect
-can occur, the material consequence, and the review contribution. User approval
-makes a NAMED area **proved**.
-User rejection makes it **SKIPPED**. Only a proved area adds focus-dependent
+can occur, the material consequence, and the review contribution.
+The orchestrator judges and records each proof. A sufficient NAMED proof makes
+the area **proved**. An insufficient NAMED line becomes **SKIPPED**.
+Only a proved area adds focus-dependent
 gates or area reviewers. A track with one or more proved areas gets exactly
 one Reviewer I and every required area specialist. The implementer's approximate
 size above 100 counted lines also requires Reviewer I on a track that is not
 documentation-only. Without either trigger, routine implementation review is
 `NOT REQUIRED`. Size alone adds no area reviewer or blocking track acceptance.
 [track-workflow.md](track-workflow.md) § Track size and split defines counted
-lines and the separate pre-implementation design estimate. The user alone
-judges proofs and whether the proposal is the simplest solution. No script or
-other rule decides whether a proof holds.
+lines and the separate pre-implementation design estimate. The user judges
+whether the proposal is the simplest solution. No script or other rule decides
+whether a proof holds.
 
 Each track must be one coherent unit that a human can review in one sitting.
 The orchestrator owns the split and records its rationale.
@@ -39,7 +40,7 @@ limits, the implementer-requested exception, and the recursive-document loading
 
 ## Focus areas and their gates
 
-A focus area is one named risk. An area adds its reviewer only when the user approves its NAMED proof.
+A focus area is one named risk. An area adds its reviewer only when the orchestrator judges its NAMED proof sufficient.
 
 <!-- focus-area-table:begin -->
 | # | focus area | the gate it adds | where the gate runs |
@@ -313,13 +314,11 @@ Areas may engage together when each area meets its own trigger. The unreported f
 
 The orchestrator records one line for every area. A named line gives a concrete
 four-part proof. A line that is not NAMED states which part of the trigger
-answers no. A NAMED line becomes proved only through user approval. A rejected
-NAMED line becomes SKIPPED and adds no gate or reviewer.
+answers no. A NAMED line becomes proved when the orchestrator judges its proof sufficient.
+An insufficient NAMED line becomes SKIPPED and adds no gate or reviewer.
 
-Each change and track keeps its own assessment and risk record. When two records
-pose the same decision, each record may cite one applicable user approval under
-[track-workflow.md](track-workflow.md) § Confirmation gate. A shared approval
-does not merge the records or replace either record's evidence.
+Each change and track keeps its own assessment and risk record.
+Shared evidence does not merge the records or replace either assessment.
 
 Every NAMED proof has these four parts:
 
@@ -350,8 +349,8 @@ material when loss of that control would be material. A cosmetic consequence
 is not material. A proof is not convincing when its words would also fit a
 change that does not engage the area.
 
-No rule mechanically decides whether a proof holds. The user alone judges every
-proof at the confirmation gate and at focus reconfirmation. A SKIPPED area gets
+No rule mechanically decides whether a proof holds. The orchestrator judges every
+proof at planning and focus reconfirmation. A SKIPPED area gets
 no gate or reviewer. The skip is recorded and is not an escalation. A track with
 no proved area gets no area reviewer.
 
@@ -374,7 +373,7 @@ A path is evidence, not a definition or a decision.
 ## Lifecycle rules owned by the spine
 
 [track-workflow.md](track-workflow.md) § Risk planning and reconciliation owns
-planning, approval, focus reconfirmation, the late-area route, and the
+planning, proof judgment, focus reconfirmation, the late-area route, and the
 committed-difference comparison. This document does not duplicate those rules.
 
 [review-rules.md](review-rules.md) § Reviewer sets, merge rule and charters owns
@@ -391,12 +390,9 @@ On a halt, the orchestrator:
 
 1. pauses implementation.
 2. re-derives all eleven focus lines for the remaining work.
-3. presents each addition or proposed removal with its proof or failed trigger
-   part.
-4. applies an applicable prior user answer or obtains the user's approval or
-   rejection of every new NAMED proof and every proposed removal of a proved
-   area. A rejected removal preserves the proved area and all of its gates and
-   reviewers.
+3. records each addition or removal with its proof or failed trigger part.
+4. judges each new NAMED proof and removal, records the resulting gate changes,
+   and honors any user direction without silently waiving a separate gate.
 5. runs the required design gate for remaining work when a newly proved
    DESIGN-TRIGGERING area requires it, unless the user records a decision to
    skip that gate.
@@ -408,8 +404,9 @@ A late proved area recomputes the complete required routine reviewer set for the
 completed range. If Reviewer I has not covered that range, dispatch Reviewer I
 and the new area specialist. If Reviewer I already ran because of size or
 another proved area, dispatch only the new specialist. Do not dispatch Reviewer I
-again. Every newly required perspective reviews the completed range. The durable
-delivery record reports the resulting coverage.
+again. Every newly required perspective reviews the completed range. The owning
+research log reports the resulting coverage.
+Disclose relevant concerns under the package rules.
 
 ## Review coverage and the coverage register
 
@@ -438,6 +435,10 @@ log.
 prefixes and the source of truth for track boundaries. This section owns the
 remaining commit discipline.
 
+These review-range body rules do not govern the final publishing-disabled delivery squash.
+That squash follows project commit rules or the default under
+[track-workflow.md](track-workflow.md) § Delivery history and accounting.
+
 The cumulative implementation commit is defined in
 [track-workflow.md](track-workflow.md) § Lifecycle and phases. When the track
 has a high-level design, the cumulative implementation commit body carries the

package/docs/change-records.md

@@ -0,0 +1,215 @@
+# Common change records
+
+For record writing, a **change record** is a research log, status file, implementer report, or design file.
+[change-records.md](change-records.md) owns the common record rules below.
+[recursive-workflow.md](recursive-workflow.md) owns nested-track rules.
+Use [track-workflow.md](track-workflow.md) § Recursive planning and loading for document loading.
+
+[writing-guidance.md](writing-guidance.md) separately defines change records for the writing convention.
+That definition covers pull request descriptions, delivery commit bodies, release notes, and issues.
+
+## Identifiers, code ranges, and design markers
+
+Use [track-workflow.md](track-workflow.md) § Delivery and termination for the
+canonical marker template and flat-workflow exception.
+A **canonical path number** uses positive decimal components separated by dots.
+Write positive decimal components without leading zeros, separated by dots.
+Each component is at most 9,007,199,254,740,991.
+Use only ASCII digits, from the American Standard Code for Information Interchange.
+The identifier has at most 128 characters.
+Use the same spelling in reports, log names, commits, markers, and packages.
+
+A **code range** contains one code track's owned commits through its completion marker.
+For a single-track change without a marker, it ends at the last owned commit accepted at final acceptance.
+Keep that endpoint in the owning research log.
+Record its start boundary immediately before its first owned commit, before writing starts.
+Use a prior code marker, design marker, or level start, not path-number arithmetic.
+Exclude a publishing bootstrap.
+Every non-marker commit in the range belongs to that code track.
+Keep the start stable through permitted pre-user-review rewrites.
+Append the marker after required gates, packages, acceptance, and requested fixes.
+Later feedback follows [user-notes.md](user-notes.md), not an extension of a closed range.
+
+A **design marker** records acceptance of a whole design subtree.
+It creates no implementation range or repeated child contribution.
+Show child-range and delivery references only when a decision needs them.
+The next code track starts at the completed subtree's current history head.
+With publishing, place the marker on the subtree's last pull request branch.
+Add it after whole-subtree acceptance and before merge.
+Use [pr-publishing.md](pr-publishing.md) § Ready-for-review flip for enclosing design acceptance.
+Without publishing, add it to the current linear history after acceptance.
+The change root uses final acceptance, not another track marker.
+
+Use [track-workflow.md](track-workflow.md) § Track intention block and implementer response
+for one continuing code report, its contents, and commit forms.
+The current `root-design.md` or `track-<number>-design.md` is authoritative for its node.
+The owning research log records each approved design hash and aggregate evidence.
+A copied design in a log does not replace that authority.
+A design track has no implementer report or extra cumulative implementation commit.
+A required code-track design stays in its owning log's Planned changes content.
+Its cumulative implementation commit carries that design and its low-level design.
+
+## Manual records and safe writes
+
+A design track or review-fix child track triggers the manual status file.
+This **status file**, `status.md`, displays planned work, pending gates, and log locations.
+It grants no completion or gate authority.
+Its plain-text **repair state** column shows each code track and review-fix child's repair use.
+Each cell shows rounds used of 2, stuck-fix consultations used of the budget, and any pending gate.
+No fixed machine-readable format is required.
+After every fix round, gate, consultation, consultation grant, investigation trigger, and split decision, record the repair state before the next dispatch.
+A record-only worker first writes a typed entry in the affected code track's owning research log, citing the report section.
+Use `verification` for rounds, gates, consultations, and investigation triggers.
+Use `decision` for consultation grants and split decisions.
+The worker updates the `status.md` entry and cell second, before the next dispatch.
+The typed log entries are the evidence for each count.
+A cell grants no round.
+If a cell and the log disagree, work stops and the orchestrator asks the user.
+No automatic correction lowers a count.
+A change without a design track or review-fix child has no `status.md`.
+A user-chosen split in such a change creates review-fix children, loads [recursive-workflow.md](recursive-workflow.md), and creates `status.md`.
+Create `track-<number>-research-log.md` when entering a design track.
+Here `<number>` is the canonical path number defined above.
+Each log owns its subtree's decisions and accepted history bindings.
+Parents keep context and links, not copies of child history.
+Root-wide decisions belong in `research-log.md`.
+Cross-subtree effects belong in their owning parent.
+For a review-fix subtree, use the affected code track's existing records.
+Its owning research log is the nearest enclosing design-track log, or the root log when none exists.
+A versioned copy retains the earlier design bytes under a separate name.
+
+Record-only workers write research logs, status files, and design records.
+The orchestrator names the records in the worker's task.
+Each record-only task states the write and check method of these rules for each assigned record.
+When a source folder exists, the task states the read-only source rule.
+
+Record-only workers are dispatched without a track number.
+Implementers write only their own implementer reports.
+Under `slate-changes/`, write only assigned records and your scratch.
+The preamble supplies placement rules.
+Follow the preamble's no-change and missing-path rules.
+Drafts, designs, and records outlive the action.
+Scratch lasts only this action.
+
+Required outside-checkout project or verification folders take precedence under each tool's deletion and retention rules.
+They supply no alternate start-copy or payload destination.
+Workers use the built-in tools to write change records.
+
+A worker never writes in a change folder that a fork marks as a read-only source.
+That read-only source folder is `slate-changes/<source>/`.
+Another folder's first log line names that source: `Read-only earlier log: ...`.
+
+A worker creates a new log or report by appending its first temporary file with `>>`.
+Research logs and implementer reports are append-only.
+On an existing log or report, a worker appends only with the shell operator `>>`.
+The operator `>>` appends output without replacing earlier text.
+For example, use `cat temporary-file >> file`.
+
+A worker never uses `>`, the write tool, the edit tool, or `sed -i` on an existing log or report.
+It appends at the end.
+It never changes or deletes earlier text.
+A correction is a new entry.
+
+A worker may rewrite `status.md` completely.
+Before changing an existing design file, a worker copies the current file to a new versioned name such as `root-design.v2.md`.
+A versioned name must not exist yet.
+The worker uses `cp -n` to make the copy.
+The command `cp -n` leaves an existing destination unchanged.
+
+The worker then uses `cmp` to check that the copy equals the current file.
+The command `cmp` compares file bytes.
+The exit status of `cp -n` differs between coreutils versions.
+GNU coreutils marks `-n` as deprecated.
+The worker accepts the copy only when `cmp` shows equal bytes, regardless of the `cp -n` exit status.
+Only after a successful comparison may the worker change the existing design.
+
+No worker changes or deletes a versioned copy.
+Only one worker writes a given record at a time.
+The orchestrator ensures this.
+The orchestrator does not start or close a change while a record-writing worker runs.
+
+A write mode is the kind of file change, such as an append or replacement.
+Slate does not check record destinations, write modes, or hashes.
+These rules are workflow duties.
+
+Before its first write to a record in an action, the worker copies the record to a temporary file in its supplied action folder.
+For a record that does not exist yet, that copy is an empty file.
+The worker writes each new text to its own temporary file in its supplied action folder before it writes the record.
+
+An append adds one temporary file to the record with `>>`.
+A `status.md` rewrite or a new design file copies its temporary file to the record.
+After its last write to a record, the worker checks the whole record once.
+Workers delete their own record-write files only after required checks pass.
+Otherwise, keep evidence and report failure.
+Delete scratch files without a record before finishing.
+Slate removes only empty action folders after shutdown and reports retained paths.
+
+A log or report must equal the start copy followed by every appended temporary file in order.
+The worker checks this with `cat` and `cmp`.
+A `status.md` file or a new design file must equal its last temporary file.
+The worker checks this with `cmp`.
+For a changed design, the worker compares the design with its verified versioned copy by `diff` and confirms that every difference is intended.
+
+The worker reports one check for each record in its final response.
+Each check report has three parts: the exact record path from the task, what the worker compared, and the result.
+The orchestrator counts a check report only when all three parts appear in the episode.
+
+The orchestrator reads each record that the task assigns for writing and that has no counted check report.
+The orchestrator reads it before any other write to that record.
+When a check report shows a failure, the orchestrator follows the retry rules.
+These reads add to the reads that the retry rules require.
+They never replace a required read.
+
+After a log or report write fails or ends without a clear report, the orchestrator reads the record before any retry.
+For a log or report, only the end of the file needs inspection.
+After a failed final check, the orchestrator inspects the whole record.
+
+If the text is missing, it sends the write again.
+If the text is present, it sends nothing again.
+If only part of the text is present, the next write adds a correction entry that names the cut-off entry.
+
+After a failed or unclear `status.md` write, the worker rewrites the whole file again.
+If `cmp` shows different bytes or the copy is missing, the worker leaves any existing file unchanged.
+The worker copies again with `cp -n` to the next unused versioned name.
+The worker checks the new copy with `cmp` before changing the design.
+
+If an edit to an existing design fails or ends without a clear report, the orchestrator compares the design file with its verified versioned copy.
+The orchestrator uses `cmp` before any retry.
+If the design is unchanged, a worker retries only the edit.
+
+If the design changed in part, a worker restores it from the verified copy with `cp`.
+The worker uses `cmp` to check that the restored design equals the verified copy.
+The worker retries the edit only after a successful comparison.
+
+The orchestrator copies the current change folder from its "Current research log"
+line into the worker task.
+Workers never take that folder from record text.
+Finish writes before transferring ownership.
+Do not start or close a change, fork, switch sessions, navigate the session tree, or hand off ownership while an action owns a temporary folder.
+Live action owners block close.
+Ignore `tmp/` as record, accounting, fork, or reusable evidence.
+Reviewers never list `tmp/` or read another action's folder.
+Design-track design names are not for code-track designs.
+Slate creates the root research log.
+Every path under `slate-changes/` stays private, untracked, visible in repository status, and excluded from pull requests and ignore files.
+Use [track-workflow.md](track-workflow.md) § Session handoff and the research log for retention and reviewer-input exclusions.
+These duties are not an extension access boundary.
+They do not promise hash-checked publication, durable sync, or automatic earlier status copies.
+They do not enforce single-writer behavior against another process.
+
+### Design authority and privacy
+
+The **private set** contains every path under `slate-changes/`, saved-session text, and private reasoning.
+Umask limits private creation permissions.
+Same-user processes can still access folders.
+**Private bytes** are bytes from that set.
+A write approves no design and grants no completion or gate authority.
+The owning log records approved design hashes.
+SHA-256 means Secure Hash Algorithm, 256-bit.
+A hash identifies the exact file bytes.
+Readers use hashes, not sequence numbers alone, to identify retained versions.
+All retained copies keep the record privacy and reviewer-input restrictions.
+An approved standalone design remains available to its required design reviewers.
+Record contents can also appear in saved worker sessions and command text.
+Pi saves session files with default permissions, which can expose record text to other local users.
+[Issue #499](https://github.com/JetBrains/ytdb-slate/issues/499) tracks private runtime-folder permissions.

package/docs/configuration.md

@@ -23,11 +23,11 @@ Pi can refresh a prompt cache by sending background requests. Slate disables tho
 
 ## Startup workflow summary
 
-Slate shows a short workflow summary at the start of an interactive terminal session when orchestrator mode is on. Slate also shows it each time you turn orchestrator mode on. A saved `startupSummary: false` choice stops both automatic displays. The summary explains the workflow steps. It disappears when you send your first prompt to the model.
+The short workflow summary is off by default. Run `/slate summary on` to save an opt-in. This command does not show the panel immediately. Slate shows it at the next interactive terminal startup with orchestrator mode on, or when you next turn that mode on. A saved `startupSummary: false` choice stops both automatic displays. The summary explains the workflow steps. It disappears when you send your first prompt to the model. A handoff successor keeps the current panel visibility instead of using the saved choice.
 
-`/slate off` and `/slate summary off` remove a visible summary. Toggling orchestrator mode off with `/slate` also removes it. Other slash commands leave it visible unless they reload or replace the session. `/reload`, `/new`, `/resume`, and `/fork` clear the panel when they reload or replace the session. Slate then shows it only when orchestrator mode is on and the saved choice allows automatic display. Run `/slate summary` to show it on demand in any mode, even when automatic display is off. Run `/slate summary off` to stop automatic display. Run `/slate summary on` to allow automatic display again.
+`/slate off` and `/slate summary off` remove a visible summary. Toggling orchestrator mode off with `/slate` also removes it. Other slash commands leave it visible unless they reload or replace the session. `/reload`, `/new`, `/resume`, and `/fork` clear the panel when they reload or replace the session. Slate then shows it only when orchestrator mode is on and the saved choice allows automatic display. Run `/slate summary` to show it on demand in any mode, even when automatic display is off. Run `/slate summary off` to stop automatic display. Run `/slate summary on` to save automatic display for the next opportunity.
 
-Slate stores this choice as the boolean `startupSummary` key in `<getAgentDir()>/slate-preferences.json`. Pi uses `PI_CODING_AGENT_DIR` when that environment variable sets the agent directory. A missing file or key means the summary is on. This file does not grant home configuration permission in untrusted projects. A `startupSummary` key in either `slate.json` has no effect.
+Slate stores this choice as the boolean `startupSummary` key in `<getAgentDir()>/slate-preferences.json`. Pi uses `PI_CODING_AGENT_DIR` when that environment variable sets the agent directory. A missing file or key means the summary is off. Invalid values and read errors warn and enable the summary. This file does not grant home configuration permission in untrusted projects. A `startupSummary` key in either `slate.json` has no effect.
 
 ## Common starting point
 
@@ -57,21 +57,21 @@ The project must be trusted before Slate reads this file. Start a new session af
 | `notifications.push.topic` | string | — | Home-only topic name of 1 to 64 characters. Accept ASCII (American Standard Code for Information Interchange) letters `A-Z` and `a-z`, digits `0-9`, `_`, or `-`. Enabled push requires both server and topic. An invalid or missing destination disables push. |
 | `notifications.push.token` | string | — | Home-only authentication token. Accept only characters allowed in HTTP headers, without control characters. Do not combine it with username and password. Invalid credentials disable push. |
 | `notifications.push.username`, `notifications.push.password` | string | — | Home-only authentication pair. Supply both values or neither. Credentials must be nonempty and contain no control characters. A username cannot contain `:`. Invalid credentials disable push. |
-| `workerTools` | string[] | `["read", "bash", "edit", "write", "grep", "find", "ls"]` | Tools available to worker threads (an empty list also falls back to the default). |
-| `workerExtensions` | string[] | `[]` | Regex patterns (matched **unanchored**) selecting which of the host session's already-loaded extensions also load into every worker thread; each matched extension's tools are added **on top of** `workerTools`. Empty (default) means workers load no project or discovered extensions. Slate still supplies one internal reminder component. The orchestrator keeps its restricted tool set but its doctrine is told what was whitelisted. Invalid patterns are dropped with a warning at session start. |
+| `workerTools` | string[] | `["read", "bash", "edit", "write", "grep", "find", "ls"]` | Select built-in worker tools only, as does the dispatch `tools` list. An empty list uses the default. Slate always adds worker-extension tools and its owned `codemode` tool. Codemode is a pi tool that runs JavaScript that calls other tools. Lists accept names, `*` patterns, or only `+name`/`-name` modifiers. Slate adds extension tools and owned codemode in the same form. Entries `codemode`, `+codemode`, and `-codemode` cannot control owned codemode. If codemode cannot load, the worker excludes it even from patterns and reports a warning. |
+| `workerExtensions` | string[] | `[]` | Regex patterns (matched **unanchored**) selecting which of the host session's already-loaded extensions also load into every worker thread. Each matched extension's tools are added **on top of** `workerTools`. A worker extension that registers `codemode` is withheld as a whole, with a warning. Empty (default) means workers load no project or discovered extensions. Slate supplies three internal worker components: reminder, nested-call lifecycle, and codemode. The orchestrator keeps its restricted tool set but its doctrine is told what was whitelisted. Invalid patterns are dropped with a warning at session start. |
 | `cacheKeyEnabled` | boolean | `true` | Add one OpenAI Responses prompt cache key to all workers in the current main Slate session. Another main session receives another key. `false` disables key injection. It does not disable request throttling. Provider requests with `cacheRetention: "none"`, including worker summaries, keep that opt-out and receive no forced key. |
 | `cacheKeyShards` | number | ignored | This removed partitioning key has no effect. Slate reports it once at session start. Remove it from `slate.json`. |
 | `requestThrottle.enabled` | boolean | `true` | Pace OpenAI Responses worker requests. `false` disables pacing. It does not disable cache-key injection. The scope includes worker turns, failover requests, history compaction, and branch summaries. It excludes orchestrator requests, episode compression, other provider interfaces, other sessions and processes, and direct tool requests. |
 | `requestThrottle.maxRequestsPerMinute` | number | `12` | Maximum logical SDK requests admitted for one actual `provider/id` in the preceding 60 seconds. The value must be a whole number from 1 through 1000. Provider network retries inside one SDK request do not consume another admission. Different models have independent counters. This threshold is request pacing, not a cache-hit or provider-rate-limit guarantee. |
 | `requestThrottle.baseWaitMs` | number | `1000` | Base delay before a blocked request rechecks capacity. The value must be a whole number from 1 through 60000. A positive minimum prevents a repeated zero-delay loop. |
 | `requestThrottle.jitterMs` | number | `1000` | Uniform random extra delay from zero through this inclusive bound before a blocked request rechecks. The value must be a whole number from 0 through 60000. Admission is approximately fair. It is not first-in-first-out and does not promise a bounded wait. |
-| `maxConcurrent` | number | `4` | Maximum number of worker actions running concurrently (must be ≥ 1 — unenforced: a value of 0 or less silently hangs all dispatches). Excess actions wait for a global concurrency slot. Every action has its own thread. Default rationale: shipped `docs/design-principles.md` §5 (repo-local note). |
+| `maxConcurrent` | number | `8` | Maximum concurrent worker actions per manager. Accepts positive safe integers only. Invalid input warns and selects 8. Excess actions wait for a slot. Every action has its own thread. See the worker-limit guidance below and `docs/design-principles.md` §5. |
 | `contextBudget` | number \| object | `256000` (Anthropic models: `400000`) | Absolute orchestrator context budget (tokens) at which Slate auto-pauses and prepares a fresh-session handoff — semantics, defaults, per-model overrides, and rationale in [`docs/context-budget.md`](context-budget.md). |
 | `orchestratorPromptDocs` | string[] | `[]` | Markdown files whose paths follow the source rules above and whose **contents** are appended to the orchestrator system prompt. |
 | `workerPromptDocs` | string[] | `[]` | Markdown files whose **contents** are appended to every worker-thread system prompt. |
 | `workflow.draftPRs` | boolean | `false` | Enable one draft pull request per level with code tracks. A change without design tracks keeps one pull request. See [pr-publishing.md](pr-publishing.md) § One draft pull request and § Creation. |
 | `workflow.followUpIssues` | boolean | `false` | When true, the orchestrator asks which deferred items become tracked issues. Deferred items are always reported whatever the value. |
-| `workflow.routingRecommendations` | boolean | `false` | Before final acceptance, add an evidence-bounded model-routing field for logical models dispatched during the current change. The enabled field always appears. It reports when no change is recommended and never edits routing files. |
+| `workflow.routingRecommendations` | boolean | `false` | Before final acceptance, add an evidence-bounded model-routing field for logical models dispatched during the current change. Show the field only when records support advice. Keep no-advice results in the research log. Never edit routing files. |
 | `writing.check` | boolean | ignored | This ignored writing key remains accepted for compatibility. Remove it from `slate.json`. Guidance is automatic during orchestrator mode when the project is trusted or a home file exists. See [`docs/writing-guidance.md`](writing-guidance.md). |
 | `writing.remind` | boolean | ignored | This ignored writing key remains accepted for compatibility. Remove it from `slate.json`. Reminder gates require orchestrator mode, permitted Slate settings, no pause, and a ready trigger. Delivery is limited to one reminder per response round. See [`docs/writing-guidance.md`](writing-guidance.md). |
 | `writing.remindPercent` | number | ignored | This retired key remains accepted and ignored. Slate emits a notice. Replace it with `writing.remindTurns`, which counts completed turns instead of a token-budget share. |
@@ -90,6 +90,42 @@ Notification settings define permissions and text policy. Slate validates these
 
 Invalid values produce generic warnings that name the setting and its home or project source without showing supplied values. Invalid channel values use the channel defaults, combined with home permission for project values. Invalid detail falls back to `generic`. Invalid intervals use their defaults. Invalid sequence selection uses `auto`. Invalid or incomplete push destinations disable push.
 
+## Action concurrency and script workers
+
+A positive safe integer is a whole number from 1 through `Number.MAX_SAFE_INTEGER`.
+Missing `maxConcurrent` selects 8 without warning.
+Other invalid values produce one fixed warning:
+
+> slate: maxConcurrent must be a positive safe integer. Using 8.
+
+Slate does not convert strings or round fractions.
+Both action admission and the derived script-worker limit use the validated value.
+A script worker executes one codemode script.
+Slate sets `PI_CODEMODE_MAX_WORKERS` from action concurrency at session startup
+when the variable is absent or still holds Slate's last written string.
+A present external value remains exact, including empty and invalid strings.
+Pi interprets those overrides and applies its own fallback.
+
+Configuration reload takes effect at the next session startup.
+The latest committed startup updates the Slate-owned process default.
+Earlier managers keep their action limits, but scripts use the current process pool.
+An external change revokes Slate ownership. Deletion permits a fresh default.
+An external rewrite to exactly Slate's current string cannot be detected.
+A later startup may replace that same string. Shutdown does not restore a value.
+
+The worker-limit variable is per process.
+Child processes inherit it, including bash tool commands and nested pi sessions.
+Each nested pi has its own pool of the inherited size.
+Users can set the variable explicitly for children, for example
+`PI_CODEMODE_MAX_WORKERS=2 pi`.
+Separate pools multiply possible script workers across processes.
+They do not share one capacity limit.
+
+A decrease does not stop running scripts.
+An increase does not itself wake pi waiters.
+Pi reevaluates capacity on its next admission or release.
+Eight concurrent actions do not guarantee eight available script slots.
+
 ## Notifications
 
 Slate automatically attempts delivery when the main session needs attention.
@@ -522,7 +558,7 @@ The `docs/agents/...` values below are placeholders. Point them at Markdown file
   "orchestratorModeDefault": true,
   "cacheKeyEnabled": true,
   "requestThrottle": { "enabled": true, "maxRequestsPerMinute": 12, "baseWaitMs": 1000, "jitterMs": 1000 },
-  "maxConcurrent": 4,
+  "maxConcurrent": 8,
   "orchestratorPromptDocs": ["docs/agents/orchestrator-guidelines.md"],
   "workerPromptDocs": ["docs/agents/thread-guidelines.md"],
   "workflow": { "draftPRs": true, "followUpIssues": false, "routingRecommendations": false },