ytdb-slate 0.13.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).
 
@@ -51,13 +55,19 @@ Through `context`, later worker threads can receive earlier episodes without ful
 
 Slate independently implements the thread-weaving architecture from the Random Labs technical report for `@randomlabs/slate`.
 
-A track is one coherent, independently mergeable part of a change. Slate supplies a track-based development workflow in orchestrator mode. Project configuration can extend the workflow rules but cannot replace them. Eleven focus areas name specific risks. They cover
+A track is a bounded part of approved work. A code track implements that work. A design track plans a nested change with child tracks. A level contains sibling tracks from one split. The level is the merge unit. Slate supplies this development workflow in orchestrator mode. Project configuration can extend the workflow rules but cannot replace them. Eleven focus areas name specific risks. They cover
 concurrency defects, data loss, security weaknesses, performance degradation,
 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 the whole change. Only you merge them.
+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: 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
 
@@ -68,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. |
@@ -77,6 +87,8 @@ The orchestrator records risks for the change and each track. You approve or rej
 
 Slate reads optional home configuration and trusted project configuration. The [configuration reference](docs/configuration.md) lists merge rules, options, examples, and document path warnings.
 
+Slate attempts notifications after a main-session run settles or an extension dialog stays open for input. Terminal, desktop and bell delivery default to on. Phone push through ntfy, a notification server, needs home setup. Text defaults to the event type. See [notification setup](docs/configuration.md#notifications) for timing and limits.
+
 ## Safety and trust
 
 Slate limits which extensions worker threads can load and which project settings it reads. [Safety and trust](docs/safety-and-trust.md) explains worker extensions, provider registrations, and the project trust boundary.
@@ -86,25 +98,26 @@ Slate limits which extensions worker threads can load and which project settings
 The main goal is that you can guide a change through its design without reading the code. Planned work:
 
 1. Design documents that state exact guarantees and show why the design keeps them. Reviewers check the code against the approved design ([#402](https://github.com/JetBrains/ytdb-slate/issues/402), [#403](https://github.com/JetBrains/ytdb-slate/issues/403), [#404](https://github.com/JetBrains/ytdb-slate/issues/404)).
-2. Recursive decomposition for large, long-running changes ([#361](https://github.com/JetBrains/ytdb-slate/issues/361)).
-3. Better developer experience: asynchronous threads, a detailed cost breakdown, and a read-only view of thread execution.
-4. Remote development through integration with pi-agent-dashboard ([#417](https://github.com/JetBrains/ytdb-slate/issues/417)).
+2. Better developer experience: asynchronous threads, a detailed cost breakdown, and a read-only view of thread execution.
+3. Remote development: planned support will allow you to set up your own infrastructure to steer agents from a laptop, a desktop or a phone through one browser application, with notifications when an agent needs attention.
 
 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
 - [`docs/design-principles.md`](docs/design-principles.md) explains the architecture and its trade-offs.
 - [`docs/model-routing.md`](docs/model-routing.md) defines logical-model routing, recovery, and accepted limits.
 - [`docs/pr-publishing.md`](docs/pr-publishing.md) defines optional draft pull request publishing.
+- [`docs/recursive-workflow.md`](docs/recursive-workflow.md) defines nested planning, repair children, and whole-subtree acceptance.
 - [`docs/review-rules.md`](docs/review-rules.md) defines reviewer roles, evidence, and fix gates.
-- [`docs/roadmap.md`](docs/roadmap.md) describes planned work.
+- [`docs/roadmap.md`](docs/roadmap.md) describes current larger-change guidance and planned work.
 - [`docs/safety-and-trust.md`](docs/safety-and-trust.md) defines worker extension, provider, and trust boundaries.
 - [`docs/track-workflow.md`](docs/track-workflow.md) defines research, design, implementation, review, and delivery.
 - [`docs/user-notes.md`](docs/user-notes.md) defines user note handling.

package/docs/blast-radius.md

@@ -10,28 +10,37 @@ 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.
-
-Each track must be one coherent unit that a human can review in one sitting. The
-orchestrator owns the split and records its rationale. Reject a split that would
-leave an inconsistent intermediate state. When the planned split exceeds twelve
-tracks, stop and present it to the user. The user chooses whether and how the
-change proceeds. Twelve is an escalation threshold, not a hard track cap.
+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.
+A code track implements bounded approved work, including document changes.
+A level contains the sibling tracks created by one split.
+The level is the merge unit.
+All checks pass at each child marker.
+Agreement across documents, prompt guidance, and the extension is required at
+the level boundary.
+Intermediate track packages and review intentions list each remaining difference
+across those surfaces and name the later child that owns it.
+Do not merge an incomplete level into the default branch.
+[track-workflow.md](track-workflow.md) § Recursive planning and loading owns split
+limits, the implementer-requested exception, and the recursive-document loading condition.
 
 ## 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 |
@@ -305,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:
 
@@ -342,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.
 
@@ -366,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
@@ -383,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.
@@ -400,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
 
@@ -430,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.