cloving 0.3.20 → 1.1.0

package/README.md

@@ -1,264 +1,688 @@
 # Cloving
 
-An AI pair-programmer for the command line.
+The world's easiest software factory.
 
-LLM-powered shell commands, code generation, commit messages, code reviews, unit test generation, and more. Works with most popular LLMs including OpenAI, Claude, Gemini, Ollama, and more.
+Build a software factory with simple TypeScript for your project, and your project can build itself.
 
-[![asciicast](https://asciinema.org/a/SCcxw4B2XFQaTD0GeDTk0xbuq.svg)](https://asciinema.org/a/SCcxw4B2XFQaTD0GeDTk0xbuq)
+The end of vibe coding. This is agentic engineering.
 
-Cloving CLI is a command line utility which integrates AI into your development workflow.
+A workflow file in TypeScript is the factory. It sets the steps: a worker turn in a work tree, a pull request, a review and a merge. Cloving keeps the state of each run and a record of each step. A GitHub step continues after a restart of the service. A worker turn in work stops at a restart. Cloving builds itself through `develop-issue` in this repository.
 
-What makes the Cloving CLI different from other AI tools is that it builds sophisticated context-aware prompts to generate code, commit messages, and more.
+## Cloving
 
-Cloving gets to know your specific projects, the frameworks you use, the coding style you prefer, and the patterns you follow, and does its best to generate code that fits your existing project so that it actually works.
+Cloving is a local durable development workflow service in TypeScript. You give it a ticket or the text of a task. A Claude Code worker does the work on a new git branch in its own work tree. Then you, or a review on GitHub, decide about the work. The service records each run, each event and each decision on your computer.
 
-It delivers usable code that you can save directly into your project instead of copying and pasting code snippets from chat interactions.
+This pre-release has one supervised slice: a service for one git repository, a workflow host, a Claude Code worker, a GitHub worker and review rounds. `cloving --help` lists the commands.
 
-**Read the [introduction announcement](https://cloving.ai/tutorials/introducing-the-cloving-cli).**
+What works now:
 
-> [!WARNING]
->
-> This project is still in the early stages of development and is not yet stable.
-> Please use it with caution and [report any issues](https://github.com/cloving-ai/cloving-cli/issues) you encounter
+- `cloving start` starts the service for one git repository, with the workflow host, the Claude worker and a watch page.
+- Three workflows from one workflow file: `develop-prompt`, `develop-ticket` and `develop-issue`.
+- In a run of `develop-ticket` or `develop-prompt`, the operator approves or denies the work of each round. A run has a maximum of three rounds.
+- In a run of `develop-issue`, Greptile reviews the pull request. The GitHub worker merges the pull request at the confidence score 5/5, with no human approval.
+- Cloving develops itself through `develop-issue`, with a Greptile review and an automatic merge.
+- The watch page shows the runs, the events and the work of the Claude worker as it occurs.
+- `cloving chats import -- FILE_A FILE_B` imports selected Claude Code transcripts into private runtime files without a service.
+- `cloving chats redact IMPORT_ID` creates a redacted corpus and a separate counts manifest without a service.
 
-## Features
+What does not work yet:
 
-- **Context-aware AI code generation**
-- **AI-powered Git commit message generation**
-- **Automated code reviews with AI insights**
-- **AI-assisted unit test generation**
-- **Support for multiple AI models including OpenAI, Claude, and Ollama**
+- The Claude worker is not confined. It runs as the current user.
+- An approval does not merge the branch. You merge the branch yourself.
+- `cloving start` loads only the workflow file `workflows/develop-ticket.ts`. A new workflow file also needs changes of the code (see "Develop a workflow").
+- Cloving cannot make a workflow from your earlier chats yet. The issues [#42](https://github.com/cloving-ai/cloving-ai/issues/42), [#43](https://github.com/cloving-ai/cloving-ai/issues/43) and [#44](https://github.com/cloving-ai/cloving-ai/issues/44) are open for this work. Until then, the prompt "Find workflows in your chats" is a guide for a coding agent.
+- This pre-release package is not published to npm.
 
-## Important
+### Import selected chats
 
-The cloving will ask you before submitting any prompt to the AI model. You can use the `-s` or `--silent` flag to run the command without asking for confirmation, but by default you will have the chance to review all prompts with all the context before submitting them. This is to ensure that you are aware of what is being sent to the AI model and can make any necessary changes before submitting the prompt.
+Chat import, redaction and analysis file operations currently require macOS. On Linux, the chat commands return `platform-unsupported` with exit status `1` before file access. The analysis file adapter also refuses with `platform-unsupported` before reading payloads.
 
-## Prerequisites
+```sh
+cloving chats import -- TRANSCRIPT_A.jsonl TRANSCRIPT_B.jsonl
+cloving chats import --previous-import IMPORT_ID -- TRANSCRIPT_A.jsonl TRANSCRIPT_B.jsonl
+cloving chats import --root PROJECTS_A --root PROJECTS_B --exclude-project project-skip -- TRANSCRIPT_A.jsonl
+```
 
-- Node.js (version 20 or higher)
-- Git
-- API access to AI chat models (e.g., OpenAI GPT-4, Claude, Ollama, etc.)
+Select files positionally, projects folders with repeatable `--root`, or both. Relative paths use the current directory. At least one file or root is required. After `--`, every argument is a literal file path, including names that look like options. The command does not expand globs; your shell can expand an unquoted glob. A source must be a regular file of at most 10 MiB (10,485,760 bytes). Symbolic links are refused. Sources keep their original bytes.
 
-## Installation
+Each root explicitly selects a projects folder. Claude Code normally stores projects below its configuration folder, whose default name is `.claude` below the home folder; `CLAUDE_CONFIG_DIR` can change that location. Cloving never discovers a root from configuration or reads settings to expand your selection. This layout does not guarantee supported transcript formats or complete history. [Claude Code session storage](https://code.claude.com/docs/en/sessions#where-transcripts-are-stored) and [subagent storage](https://code.claude.com/docs/en/sub-agents) describe the source layout.
 
-You have three options to install and use Cloving:
+`--exclude-project NAME` matches a direct project folder name exactly, preserving case. Repeat it for several names. Exclusions require roots and never affect positional files. Names cannot contain separators, parent-directory markers or glob patterns. An excluded subtree produces one `project-excluded` entry; its children are never listed or opened.
 
-### 1. Global Installation via npm
+Positional files retain their order and repetitions and come before scanned files. Roots sort by canonical path, retaining repeated selections with stable ties. Entries sort by relative path using JavaScript string order. Scans select regular files ending in lowercase `.jsonl`; other filenames produce `unsupported-extension` without a content read. Root children have depth one. Session files at depth two and subagent files at depth four fit the limit. Folders at depth four are pending with `depth-limit` and disclose no descendant inventory.
 
-Install Cloving globally using npm:
+Across all roots, at most 100 eligible scanned candidates receive a source-read attempt. A failed open, oversized file, invalid encoding or unsupported transcript still consumes a slot. Repeated roots and overlapping selections consume separate slots; positional files are outside this budget. All metadata candidates are ordered before slots are allocated. Later candidates are pending with `file-limit` and are never opened. Select a pending file explicitly in a later import. The supported macOS scanner refuses links in roots, ancestors and entries, canonical containment escapes, Git repository roots (including worktrees and bare repositories), and source or ancestor identity changes before reading bytes. Inaccessible directories produce unreadable subtree entries. Directory enumeration also refuses raced links; an unavailable kernel protection fails closed.
 
-```bash
-npm install cloving -g
-```
+Each import accepts at most 50 MiB (52,428,800 bytes) of normalized corpus JSONL, measured as UTF-8 including newline separators. Repeated selections count toward this total. This bounds the message content retained for structure analysis. Exceeding the limit returns `output-failed` with exit code `1`, leaves no completed coverage manifest and may leave partial data files. Select fewer sources for each import; copy and conflict comparisons apply within each import.
 
-This allows you to run `cloving` commands from anywhere in your terminal.
+The supported Claude Code JSONL subset has `user` and `assistant` envelopes with a matching `message.role`. Content can be a string or an ordered array of `text`, `tool_use` and `tool_result` blocks. Records preserve the role, timestamp, session ID, tool fields and original block positions. Missing timestamps and session IDs become `null`. Thinking blocks and non-message metadata are omitted and counted. Unknown message shapes or blocks refuse the entire source. Claude Code's internal transcript format can change between versions.
 
-### 2. Run with npx
+Each import creates `chats/IMPORT_ID/corpus.jsonl`, `structure.json` and `coverage.json` below the resolved Cloving runtime directory. Selection uses a nonempty `CLOVING_RUNTIME_DIR`, then `XDG_RUNTIME_DIR/cloving`, then `XDG_STATE_HOME/cloving/run`, then `HOME/.local/state/cloving/run`. Relative settings resolve against the current directory. Destinations inside a Git repository are refused, including through symbolic links. New directories have mode `0700`; files have mode `0600`. These permissions add no encryption or redaction.
 
-You can use npx to run Cloving without installing it globally:
+New corpus records have `schemaVersion: 2` and a `sourceId` of `sha256:HEX:OFFSET`. The digest covers the exact source bytes. The offset is the zero-based byte position of the source line. `text` joins the message's text blocks with a newline; `blocks` retains each supported block's `position`. Tool result content is copied as JSON data. Positional-only imports retain coverage version 1 with its ordered `files` array. Imports containing roots write coverage version 2 with ordered `roots`, `exclusions`, fixed `limits` and ordered `entries`. Each entry identifies its zero-based positional or sorted-root selection, file or subtree kind, resolved path, status, fixed reason code, digest when available, record count and omission counts (`metadataRecords` and `thinkingBlocks`). Excluded and pending subtree entries count only themselves. Scanned oversized files are `unsupported` with `file-too-large`; positional oversized files retain `too-large`, including mixed imports. Refused sources contribute no records. Included sources also record `byteSize`, measured from the exact hashed bytes. Both coverage versions accept legacy entries without sizes. The final coverage manifest appears only after the corpus, structure and optional revision files close successfully. Output failure leaves no completed coverage manifest; partial data files may remain.
 
-```bash
-npx cloving [command]
-```
+Use `--previous-import IMPORT_ID` before `--` to compare with one earlier import in the resolved runtime chats folder. It accepts one UUID v4 ID, using the same syntax as redaction. Missing, repeated and malformed values are usage errors (`missing-value`, `repeated-previous-import` and `invalid-import-id`). At least one current file or root is still required. The earlier coverage manifest must be valid and carry the same ID; completed partial imports are allowed. Existing revisions must also be valid with a positive safe revision number that can be incremented. Missing coverage, invalid metadata or linked inputs return `previous-import-refused`, exit `1`, a null import ID and zero counts before selection, source reads or new output.
 
-This method downloads and executes Cloving on-the-fly, ensuring you always use the latest version.
+Comparison writes private `revision.json` with `schemaVersion: 1`, `importId`, `previousImportId`, `evidenceRevision`, `counts` and ordered `entries`. An earlier import without a revision starts revision `1`; otherwise its revision increases by one. Each entry stores `path`, `root` (null for positional selections), `before` and `after` evidence, one `status` and one fixed `reason`. Absent evidence is null; present evidence contains a nullable digest and optional byte size. No message text is stored. Counts always include `new`, `missing`, `unchanged`, `changed`, `truncated` and `extended`, including zeros.
 
-### 3. Clone and Install from Source
+Selections match only by stored source path and selected root path, resolving each manifest's root indexes independently. Repeated keys pair in order. Current entries come first, followed by unmatched earlier entries in their earlier order. New selections are `new`; absent or currently refused selections are `missing`. Equal non-null digests are `unchanged`. An unavailable earlier digest or size makes differing evidence `changed`. Fewer bytes are `truncated`; more bytes are `extended` only when SHA-256 of exactly the earlier byte count equals the earlier digest. Other differences are `changed`. Prefixes use the same bounded source read; no source is reopened. Earlier entries never select sources or invent subtree descendants. Missing or truncated evidence forces `import-partial` and exit `1`. Revisions do not merge corpora, establish complete history or invoke later analysis. Without the option, no revision file is created and the summary retains its existing shape.
 
-For development or to use the latest unreleased features:
+Version 2 preserves nonempty envelope `uuid` strings exactly, with `null` for unknown identity. It preserves boolean `isSidechain` flags, otherwise `null`. A nonempty `parentUuid` string is an observed link and explicit `null` is an observed root. Absent, empty or invalid parents are omitted and remain unknown. Import retains all supported branches and side chains and never uses API message IDs, paths, content or neighbors to infer identity.
 
-1. Clone this repository:
-   ```bash
-   git clone https://github.com/cloving-ai/cloving-cli.git
-   ```
+The version 1 structure sidecar references each occurrence by zero-based `recordIndex` and `sourceId`, including repeated selections with the same source ID. It contains no message content or source paths. Known identity matches across the import mark copies of the earliest occurrence with equal role, text and blocks, ignoring object member order while preserving array order and exact JSON number tokens. All records stay in the corpus. Different content for one identity produces a conflict group containing every variant and its copies; no variant wins.
 
-2. Navigate to the project directory:
-   ```bash
-   cd cloving-cli
-   ```
+Structure groups nodes and observed links within known sessions. Null and empty session IDs remain separate, unlinked occurrences. Links with conflicting observed parents or unknown child identity are marked ambiguous. Forks require multiple distinct known child IDs through unambiguous links. Missing parent targets are counted once per session and target ID, separately from unknown parent fields. Cyclic groups include all observed links, including ambiguous links; their IDs form strongly connected groups in occurrence order. Counts include records, known sessions, forks, copies, conflict groups, unknown identities and missing parent targets, including zeros. `historyCompleteness` is always `"unknown"`: selected history and even an explicit root cannot establish complete history. Omitted metadata parents remain unresolved.
 
-3. Install dependencies and link the package:
-   ```bash
-   yarn install
-   yarn link
-   ```
+Console output contains counts, fixed codes and an opaque import ID. Source paths, exclusion names, event and session IDs, and transcript text stay in the private files. Root imports add `excluded` and `pending` entry totals. `refused` counts unreadable, unsupported and positional oversized entries. Exit code `0` and `import-complete` mean no refused or pending entries and, when comparing revisions, no missing or truncated evidence; exclusions alone permit success without comparison. Code `1` and `import-partial` mean refused, pending, missing or truncated entries when output completes. Output failures return code `1`, a null import ID and zeroed counts. Code `2` means invalid usage, before source or destination access. Importing performs only structural comparison; it makes no model or network call and does not execute transcript instructions. Full quality admission and release qualification remain pending.
 
-After installation, configure Cloving with your API key and preferred model:
+### Protected chat analysis files
 
-```bash
-cloving config
-```
+The daemon provides `chats` capability methods `read-analysis` and `save-analysis` only to the registered `analyze-chats` workflow. A declaration must explicitly name `chats`; existing workflows retain their capabilities. Start one analysis with `cloving run analyze-chats --input input.json`, where the file contains exactly `{ "importId": "11111111-1111-4111-8111-111111111111" }` using your redacted import ID. The declared workflow charges three effect units for sequential read, one model turn and save. No evidence path is accepted.
+
+`read-analysis` takes `{ importId }`, with the same lowercase UUID v4 syntax as redaction and the import ID as its protected target. It reads only `redaction.json`, `redacted.jsonl` and `structure.json` from the resolved runtime import directory. Its completed result contains `{ snapshot }`, whose `importId`, `redaction`, `corpus` and `structure` fields are strings. Keep these strings in private durable state; parsing and serializing corpus numbers can lose their exact tokens. Original corpus, coverage, revision and transcript content are never analysis inputs.
+
+Each evidence file is bounded before retention. The redacted corpus, serialized snapshot, complete escaped model document (`{ prompt: analysisModelInput(snapshot) }`) and final serialized save payload must each fit 65,536 UTF-8 bytes. The model-input formatter includes instructions and the full sidecar. Overflow returns `analysis-too-large`; transport limits are unchanged. Missing redaction manifest or corpus returns `redaction-required`, malformed nonempty import IDs return `invalid-import-id`, and invalid or unsafe evidence returns `analysis-input-refused`. Manifest counts and identity fields must match the corpus. Sidecar validation retains original copy/conflict classes, using class markers rather than redacted content to check structure consistency.
 
-Choose the installation method that best suits your needs and workflow. The global npm installation is recommended for most users, while npx is great for one-off usage or trying out Cloving. Cloning from source is ideal for contributors or those who want the absolute latest features.
+`save-analysis` takes `{ importId, cycleId, snapshot, reply }`. The reply is JSON text and validation uses the captured snapshot even if the files later change. Invalid JSON returns `analysis-invalid-json`; candidate refusal retains the validator's unique codes in declaration order. Accepted output writes and closes private `proposal-CYCLE_ID.txt` before creating `analysis-CYCLE_ID.json` as the completion marker. The JSON is the complete validator result, including every citation, counterevidence item and limitation. The deterministic plain-text proposal is at most 4,000 characters. Matching duplicate saves retain bytes and receipt identity; a matching proposal without a marker may finish. Conflicting or incomplete existing outputs remain unchanged and return `analysis-output-failed`. A proposal alone is not completed analysis. New files have mode `0600`; destinations and linked files use the import protections.
 
-## Usage
+The pure batch preparer validates a captured snapshot, selects the longest consecutive whole-record prefix within 65,536-byte encoded launch and adapter documents, and refuses a fifth batch. It preserves record bytes, global occurrence indexes and captured copy/conflict classes, includes the earlier result as data, and measures the fixed instruction and prompt encoding shared with the restricted launcher. Raw metadata remains bounded at 65,536 bytes and the input corpus at 52,428,800 bytes. Workflow integration, streaming capture, cumulative merge, immutable coverage checkpoints, batch save bounds and restart across batches remain pending; the running workflow retains its single-snapshot limits above.
 
-Cloving provides several commands to help integrate AI into your development workflow:
+Analysis reuse after an evidence revision is unavailable. `earlierAnalysisId` is not a supported analysis input, and `analysis:IMPORT_ID:CYCLE_ID` identifies a saved result without establishing checkpoint coverage. Import revisions classify source changes but do not map analysis citations or transfer analyzed record ranges. Reuse requires an implemented and verified batch pipeline with result merging, committed complete or partial coverage checkpoints, replay binding and durable question/answer follow-up. The pure batch preparer and saved validator results do not satisfy that prerequisite.
 
-### Configuration
+A candidate with `openQuestion` currently returns `analysis-input-refused` from `save-analysis`, reconciliation and stop without creating output. The pure question validator is implemented; private drafts, durable analysis questions, expiry and answer follow-up are pending. The workflow still uses one turn and three effect units.
 
-Configure Cloving with your API key and model:
-```bash
-cloving config
+Success returns `{ kind: "handoff_requested", cycleId, promotionId }`, where `promotionId` is an opaque analysis reference. It grants no execution or publication authority. The file adapter performs no git work, network request or model call. Redaction can leave private values, and validator acceptance checks shape and cited occurrences rather than factual accuracy. History completeness remains unknown and independent observations remain unestablished.
+
+The analysis turn always uses the `claude` executable on the search path, including with `CLOVING_WORKER=codex`. Development workflows keep their configured worker. Analysis requires Claude Code major version 2, at least 2.1.302, with every required launch flag in its help text; an unavailable or unsupported CLI returns `analysis-worker-unavailable`. It accepts no `analyze-chats` profile or development-command override.
+
+To configure subscription login:
+
+1. Run `claude setup-token` once and store the token in your secret manager.
+2. Set `CLOVING_ANALYSIS_TOKEN_COMMAND` before starting the daemon. Its value is a JSON array of one or more nonempty strings naming a program and its arguments, for example `CLOVING_ANALYSIS_TOKEN_COMMAND='["op","read","op://Development/Claude Analysis/token"]' cloving start`. The command must print only the stored token on stdout.
+3. Start an `analyze-chats` run. Immediately before each new turn, Cloving runs the command without a shell, with a 10-second deadline and a 4,096-byte limit shared by stdout and stderr. After removing one final line break, stdout must contain 1–512 printable ASCII characters without spaces or control characters. An unset or malformed setting, command failure, timeout, excessive output or invalid token blocks with `analysis-worker-unavailable` and a fixed cause category.
+
+The fetched token goes only to the analysis process as `CLAUDE_CODE_OAUTH_TOKEN`. Cloving does not put it in its environment, development workers, logs or stored results, and does not fetch it for CLI probes or completed-turn replay. Analysis excludes `ANTHROPIC_API_KEY`, including a key present in the daemon environment. Cloving does not read the macOS keychain.
+
+The fixed launch removes built-in tools with `--tools ""` and denies MCP tools separately, with an empty strict MCP configuration. Safe and restricted modes disable discovery; skills, hooks, project instructions, plugins, session persistence and Chrome integration are disabled. The command runs once with a five-dollar budget in an empty private directory and uses a separate fixed system instruction and encoded evidence input. Only this turn contacts the model. See the [Claude CLI controls](https://code.claude.com/docs/en/cli-reference) and [subscription authentication](https://code.claude.com/docs/en/authentication).
+
+Replies of at most 16,000 UTF-8 bytes are retained completely for validation. Larger replies return `analysis-reply-too-large`; unsuccessful turns return `analysis-turn-failed`. Both retain available usage. A completed private worker result is written before its report, so durable replay can reuse it. An interrupted or unknown completion never starts a replacement turn. Analysis creates no raw stdout/stderr turn logs or generic text summary. Worker records and accepted outputs remain private; operational views expose codes, counts, usage and opaque identities. Temporary CLI data is removed when the turn completes. Acceptance grants no execution, publication or workflow-generation authority.
+
+### Redact an imported corpus
+
+```sh
+cloving chats redact IMPORT_ID
 ```
 
-### Initialization
+Use the UUID v4 import ID printed by `chats import`. This command uses the same runtime directory selection and needs no service. It accepts version 1 and version 2 corpus records and coverage manifests. It validates coverage without reopening transcript paths. Original corpus, coverage and structure files remain unchanged.
+
+The command writes `redacted.jsonl` and `redaction.json` beside the originals. New files have mode `0600`. Existing outputs are refused. The manifest records rule version `1`, record count, category counts (including zeros), and total replacements. It contains no matched values or replacement map. The manifest is written only after the redacted corpus closes successfully. A failure can leave an incomplete redacted corpus; there is no restart recovery.
 
-Set up Cloving in the current project:
-```bash
-cloving init
+`HOME` supplies the home folder. The rules replace home paths (including tilde forms), e-mail addresses, supported GitHub, Anthropic and OpenAI tokens, complete private-key blocks, and URLs with user information. `CLOVING_PRIVATE_TEXTS` adds literal texts with case ignored. For this command, an unset setting or `[]` adds no texts. Malformed lists, non-string entries and blank entries are refused. The issue-posting workflows still require a nonempty private-text list.
+
+Redaction inspects message text, text blocks and nested tool input and result strings, including member names. Overlapping matches count once, with priority given to private keys, credential URLs, home paths, tokens, e-mail addresses, then private texts. Both stored copies of message text count. Source references, schema versions, identity fields, parent-field presence, record order and exact number tokens remain intact. The structure sidecar is private metadata outside redaction scope and is not a redacted export. Member-name collisions are refused.
+
+Console output contains only fixed codes, counts and the import ID. Exit code `0` means success, `1` means processing failure, and `2` means invalid usage. Originals and metadata remain outside redaction scope. Both originals and outputs remain private runtime data. Redaction makes no model or network call and does not execute transcript instructions. It neither guarantees removal of every private value nor authorizes later model use.
+
+### Validate process analysis data
+
+The pure `validateAnalysis(candidate, { records, structure })` function in `src/chats/analysis.ts` validates one version 1 process candidate against an ordered redacted corpus and its matching pre-redaction, in-memory `ImportStructure`. The evidence object keeps the API within the repository's two-parameter quality limit. Stored sidecar envelopes are not this input type. This pure validator makes no model call.
+
+Candidates declare IDs and descriptions for inputs, ordered stages, branches, bounded loops, artifacts, stopping conditions, gates and non-gates. Branch links use `sourceStageId` and `targetStageId`; loops use ordered `stageIds` and `exhaustedStoppingConditionId`. Stages, gates and loops declare a claim `kind`, `sourceRefs` and `counterevidenceRefs`. References identify exact occurrences by `recordIndex` and `sourceId`. Copies add no support; observed repetition needs two directly cited original source IDs. Routine repair, accidental interruption and tool-imposed confirmation require matching non-gate classifications.
+
+Version 1 also accepts an optional `openQuestion` object containing only `claimId`, `description`, `sourceRefs` and `choices`. It names a stage, gate or loop claim and cites distinct known occurrences from that claim's support and counterevidence, with no unrelated references. Two to four choices each contain only a unique nonempty `id` and an inert `description`. Malformed or multiple questions return `invalid-question`; absent claims or missing declared conflict return `question-without-conflict`. Missing and unknown sources retain their existing codes, as do recursive authority fields. Validation checks the declared relations and makes no claim that the prose describes a real conflict. A validated question remains unresolved analysis data.
+
+Acceptance returns the candidate plus limitations preserving conflict groups, unknown history and unestablished independence. Refusal returns only fixed, unique codes in declaration order. Candidate fields are closed; authority and executable fields are refused, and descriptions remain inert. Validation does not certify redaction, evidence authenticity, inference quality, publication safety or permission for any action. Evidence content and exact numeric tokens remain unchanged. Full product admission remains pending CLV-002 through CLV-004.
+
+## Install
+
+Cloving supports macOS and Linux on arm64 and x64, with the Node and npm ranges in `package.json`. Workflow admission still requires exactly Node 26.9.0. CI runs the developer gate and packed-install checks on macOS 15 arm64 and Ubuntu 24.04 x64 with Node 26.9.0 and npm 11.19.1. Chat import and redaction currently require macOS; other platforms return `platform-unsupported` before file access. Windows is unsupported.
+
+A run needs these tools:
+
+- `git`.
+- The `claude` command of Claude Code on the search path. The Claude worker runs it as the current user.
+- For `develop-issue` only: the `gh` command with a login, and a GitHub repository that Greptile reviews. The worker uses the `gh` login and the git credentials of the current user.
+
+Once the operator publishes this package, install the executable with:
+
+```sh
+npm install --global cloving --ignore-scripts
+cloving --version
 ```
-Options:
-- `-s, --silent`: Run without asking for confirmation of submitting prompts
-- `-m, --model <model>`: Select the model to use
 
-### Generating Commit Messages
+This package replaces the older Cloving CLI under the same npm name. The registry currently serves that older CLI; the command above is for after this release is published. The installed package includes startup, the watch command, bundled workflows and the SDK compiler integration. It starts without a source checkout or development dependencies, using the installed runtime dependencies. Installation runs no scripts and starts no service.
 
-Generate an AI-powered commit message:
-```bash
-cloving commit
+For checkout development, get the code and install the dependencies:
+
+```sh
+git clone https://github.com/cloving-ai/cloving-ai.git ~/cloving
+cd ~/cloving
+npm ci --ignore-scripts
 ```
-or
-```bash
-cloving generate commit
+
+The runtime dependencies include the Workflow SDK (`workflow`), its directive compiler (`@workflow/builders`), Solid Objects (`solid-objects`), Entities (`entities`) and Preact (`preact`), which the watch page loads. Startup runs the SDK compiler to transform workflow and step directives. Development dependencies are needed to build the package, but an installed tarball runs without them.
+
+### The `cloving` command
+
+For checkout development, put a launcher for `src/cli.ts` in a directory of the search path. The launcher must use exactly Node 26.9.0. This example is for a checkout in `~/cloving` and a launcher in `~/.local/bin`:
+
+```sh
+mkdir -p ~/.local/bin
+cat > ~/.local/bin/cloving <<'EOF'
+#!/bin/sh
+exec node "$HOME/cloving/src/cli.ts" "$@"
+EOF
+chmod +x ~/.local/bin/cloving
+cloving --version
 ```
-Options:
-- `-s, --silent`: Run without asking for confirmation
-- `-m, --model <model>`: Select the model to use
 
-### Code Reviews
+If the `node` program of the search path has a different version, write the full path of the correct `node` program in the launcher.
+
+To install a built tarball, build and pack it in the checkout:
 
-Get an AI-powered code review:
-```bash
-cloving generate review
+```sh
+npm run build
+npm pack --ignore-scripts
 ```
-Options:
-- `-s, --silent`: Run without asking for confirmation
-- `-m, --model <model>`: Select the model to use
 
-### Generating Code
+Then install the resulting tarball in your project using its absolute location:
 
-Generate code based on a prompt:
-```bash
-cloving generate code
+```sh
+npm install --ignore-scripts --omit=dev /path/to/TARBALL
+./node_modules/.bin/cloving --help
+./node_modules/.bin/cloving start
 ```
-Options:
-- `--save`: Automatically save all files after generating the code
-- `-i, --interactive`: Auto-save generated code and then show a new prompt with existing context to revise the code further
-- `-s, --silent`: Run the command without asking for confirmation of submitting prompts
-- `-m, --model <model>`: Select the model to use
-- `-p, --prompt <prompt>`: Specify the prompt to use
-- `-f, --files <filenames...>`: Specify filenames of files with context to use for generating code
-
-### Generating Shell Commands
-
-Generate a shell command based on a prompt:
-```bash
-cloving generate shell
+
+The installed executable includes JavaScript for startup, the watch command and bundled workflows. It uses the installed runtime dependencies, including the SDK compiler, without a source checkout. Runtime state and generated workflow artifacts use the configured runtime location outside the installation. Installation scripts are unnecessary. The checkout launcher above remains supported, including its existing checkout self-update behavior; installing a tarball does not add package self-updates.
+
+For a project-local tarball installation, use `./node_modules/.bin/cloving` wherever the examples below say `cloving`, or add your project's `node_modules/.bin` to the search path. After a build, `npm link` also supplies the executable.
+
+## First run
+
+This first run uses `develop-prompt` on a test repository. It needs no ticket command and no GitHub repository.
+
+1. Make a test repository with one commit:
+
+   ```sh
+   mkdir ~/cloving-trial
+   cd ~/cloving-trial
+   git init
+   echo "A test project." > README.md
+   git add README.md
+   git commit -m "Start the test project"
+   ```
+
+2. In terminal 1, in the test repository, start the service. Keep this terminal open:
+
+   ```sh
+   cloving start
+   ```
+
+   `cloving start` copies the workflow file into a host project, compiles it there, and starts the service. Then it prints the commands for a second terminal.
+
+3. Open the watch page on `http://127.0.0.1:3663/`.
+
+4. In terminal 2, submit a run:
+
+   ```sh
+   cloving run develop-prompt --prompt "Add a file HELLO.md with one line of text."
+   ```
+
+   The command prints a committed receipt with the run ID. A receipt does not mean completed work.
+
+5. The Claude worker does one Claude Code turn. Then the run opens one approval. Show the pending decisions:
+
+   ```sh
+   cloving questions
+   ```
+
+   The output has the approval text and the values that a decision command needs. The approval text has the round, the ticket ID, the branch, the commits, the changed files and the report of the worker.
+
+6. Read the diff before you decide. In the test repository, `git diff HEAD...BRANCH` shows the work of the branch.
+
+7. Approve or deny the work:
+
+   ```sh
+   cloving approve DECISION_REF --expected-revision N --generation N --subject-digest DIGEST
+   cloving deny DECISION_REF --text "FEEDBACK" --expected-revision N --generation N --subject-digest DIGEST
+   ```
+
+   An approval completes the run. It does not merge the branch, so merge the branch yourself, for example with `git merge BRANCH`. A denial with a feedback text starts one more round.
+
+8. `cloving status` lists the runs. `cloving status RUN_ID` shows one run with its reason, evidence and next action.
+
+### The service and its settings
+
+`cloving start` starts one Cloving service for the git repository of the current directory, with the workflow host, the Claude worker and the watch page. `--repository` selects a different repository. Stop the service with Control-C. A stop of the service stops a turn in work; submit that ticket again.
+
+The client commands find the service with no setting, because the two sides use the same default runtime directory (`~/.local/state/cloving/run`). `CLOVING_RUNTIME_DIR` selects a different place for the two sides. The directory above the runtime directory holds the authority state, the Local World data, the turn records and the git work trees.
+
+`cloving watch` serves a local page on `http://127.0.0.1:3663/` (`--port` selects a different port). The page shows the runs, the events, the work of the Claude worker as it occurs, and each pending decision with its approve and deny commands. `cloving start` starts the page too; `CLOVING_WATCH_PORT` selects its port, and the value `off` starts none.
+
+Each workflow board with supported inputs has **+ Add a card** at the bottom of its first column, including an empty board. It opens an inline form: **Issue number** for `develop-issue`, **Ticket ID** for `develop-ticket`, **Idea** for `develop-prd` and **Task** for `develop-prompt`. Declared workflows such as `analyze-chats` use the string fields in their bundled declaration. Unsupported inputs have no control. Select **Add card**, press Enter in a one-line field, or Command/Control+Enter in a text area to send. **Cancel** and Esc close the form. The service reply shows the admitted run ID or a refusal code; admitted cards arrive through the existing live stream. For `workflow-active`, add `cloving: ready` to the issue to queue it.
+
+The form sends the same run request as the CLI and retains its random command ID for retries, including a lost reply. Retry the same form to avoid duplicate runs. The write endpoint accepts at most 16 KiB of JSON, requires the page's random token, matching Origin and a loopback/localhost Host with the bound port, and allows no cross-origin preflight. `CLOVING_WATCH_ACTIONS=off` removes both the form control and the endpoint; actions are enabled by default. The **Start a run** section remains available with prompts to copy into agents. Decisions and other run actions still use their displayed CLI commands.
+
+`cloving start` reads its settings from the environment. `cloving start --help` gives the form and the default of each setting:
+
+- `CLOVING_RUNTIME_DIR`: the runtime directory.
+- `CLOVING_TICKET_COMMAND`: the ticket command (see "Daily development").
+- `CLOVING_NOTIFY_COMMAND`: a JSON list naming a command to notify the operator about pending decisions, blocked runs and failed runs. It has no default.
+- `CLOVING_NEXT_COMMAND`: a JSON list of a command and its arguments that prints the next ready ticket ID for `--next`. It has no default.
+- `CLOVING_ANALYSIS_TOKEN_COMMAND`: a JSON command array that prints the subscription token just before an analysis turn (see "Protected chat analysis files"). It has no default.
+- `CLOVING_CLAUDE_COMMAND`: a replacement of the `claude` command of the worker.
+- `CLOVING_PROFILES`: a JSON file of named Claude turn profiles, read once when the service starts.
+- `CLOVING_WATCH_ACTIONS`: `off` disables starting runs from the board; default `on`.
+- `CLOVING_WATCH_PORT`: the port of the watch page, or `off`.
+- `CLOVING_WATCH_REPOSITORY`: repository context for a separate watch process. `start` sets this from its service repository. The watch process uses its local origin and has no current-directory default.
+- `CLOVING_OWNERSHIP_LEASE_SECONDS` and `CLOVING_HOST_BOUND`: limits of the workflow host.
+- `CLOVING_GH_COMMAND`, `CLOVING_CHECK_COMMAND` and `CLOVING_PRIVATE_TEXTS`: settings of `develop-issue`; the GitHub command and private-text list also apply to `develop-prd`.
+
+A command setting is a JSON list of texts, for example `CLOVING_CHECK_COMMAND='["npm", "test"]'`.
+
+The notify command receives no added argument. Its standard input receives one JSON object with `event`, `runId`, `workflowId`, `subject` and `body`. The body contains the decision or outcome text already shown by `cloving questions` or `cloving status`, with complete response commands, up to 4000 characters. The daemon checks every 15 seconds and records each event before calling the command. The first check with no notification record only records existing events. Records survive restarts; a failed command is logged once and never retried. Commands have 30 seconds to finish. A stop after recording an event but before sending it can lose that notification, and decisions opened and closed between checks can be missed.
+
+## Daily development
+
+`cloving start` copies the TypeScript files in `workflows/` into a host project and compiles them there. The bundled workflows are:
+
+- `develop-prompt` takes the text of a task. Use it for a small task with no ticket, or for a first try in a new repository.
+- `develop-ticket` takes a ticket ID and reads the ticket itself. Use it for the normal work on a ticket, when you want to read each diff and merge the branch yourself.
+- `develop-issue` takes a ticket ID too, and sends the work through a GitHub pull request. Use it for a small ticket with clear criteria, in a GitHub repository that Greptile reviews and that has a check command. It is the workflow of the continuous process.
+- `develop-prd` takes an idea, researches the code and web, reviews a draft PRD, and posts it as a GitHub issue. Set `CLOVING_PRIVATE_TEXTS` to a nonempty JSON list before starting the daemon. A refused post preserves the worktree and draft. A successful post removes the worktree and adds no label; read the issue and add `cloving: ready` when it is ready for implementation.
+
+```sh
+cloving start                                  # terminal 1, in the repository
+cloving run develop-ticket --ticket TICKET_ID  # terminal 2
+cloving run develop-issue --ticket TICKET_ID   # the work goes through a pull request
+cloving run develop-issue --next               # select the next ready ticket
+cloving run develop-prompt --prompt "the text of the task"
+cloving run develop-prd --prompt "Show the cost of each run on the watch page"
+cloving watch                                  # the live page, also started by cloving start
+cloving questions
+cloving approve DECISION_REF --expected-revision N --generation N --subject-digest DIGEST
+cloving deny DECISION_REF --text "FEEDBACK" --expected-revision N --generation N --subject-digest DIGEST
 ```
-or
-```bash
-cloving generate sh
+
+The rule: read the diff before you approve.
+
+Claude turns have web research tools by default, an empty GitHub CLI configuration folder, and no GitHub token environment variables. This is not a sandbox: a turn can still find other credentials. The PRD refusal rules catch the listed private text and common sensitive forms; unlisted private names can pass. A `post-uncertain` result requires checking GitHub before trying another run.
+
+### The ticket command
+
+`CLOVING_TICKET_COMMAND` (a JSON list of texts) names the ticket command. The contract of a ticket command:
+
+- It gets a ticket ID as its last argument and prints the text of the ticket.
+- For `develop-issue`, a first line that starts with `# ` gives the title of the pull request. With no such line, the title is `Cloving task <cycle ID>`.
+- For `develop-issue`, a line `GitHub issue: <owner>/<repository>#<number>` makes the pull request reference that issue. Cloving closes it after a merge only when the worker reports complete work.
+
+The daemon runs the ticket command when it admits a run. The printed text becomes the stored input of the run, so a later change of the ticket does not change the run. A ticket that the command does not give is refused with `ticket-not-available`. With no ticket command, `develop-ticket` is refused with `ticket-source-not-configured`. A ticket ID has letters, digits and the characters `. _ : -` only.
+
+This example ticket command reads a GitHub issue. Save it as `~/.local/bin/github-ticket`, and make it executable:
+
+```sh
+#!/bin/sh
+set -eu
+repository=OWNER/REPOSITORY
+title=$(gh issue view "$1" --repo "$repository" --json title --jq .title)
+body=$(gh issue view "$1" --repo "$repository" --json body --jq .body)
+printf '# %s\n\nGitHub issue: %s#%s\n\n%s\n' "$title" "$repository" "$1" "$body"
 ```
-Options:
-- `-s, --silent`: Run without asking for confirmation of submitting prompts
-- `-m, --model <model>`: Select the model to use
-- `-p, --prompt <prompt>`: Specify the prompt to use
 
-### Interactive Chat
+Then start the service with the setting:
 
-Start an interactive chat session with the AI:
-```bash
-cloving chat
+```sh
+CLOVING_TICKET_COMMAND='["github-ticket"]' cloving start
 ```
-Options:
-- `-f, --files <filenames...>`: Specify filenames of files with context to use for the chat
-- `-t, --temperature <temperature>`: Set the temperature for the model (default 0.2)
-- `-m, --model <model>`: Select the model to use
 
-### Proxy Server
+`cloving run develop-issue --next` and `cloving run develop-ticket --next` use the reserved ticket ID `next`, just like `--ticket next`. Set `CLOVING_NEXT_COMMAND` to a JSON list naming your selection command and its arguments. The daemon adds no argument. The command chooses a ready ticket in your tracker and prints its ID; the daemon trims it and reads the ticket with `CLOVING_TICKET_COMMAND`. Both commands share the resolver's 30-second deadline. Selection logic stays in your command, and each invocation submits only one run.
+
+An empty selection gives `no-ready-ticket`; a failed command gives `next-ticket-not-available`. Missing configuration gives `next-source-not-configured`. Multiple IDs, an invalid ID, or `next` as the selected ID give `invalid-ticket-id`. Use only one of `--next`, `--ticket`, `--prompt` and `--input`.
+
+### Review rounds of `develop-ticket` and `develop-prompt`
+
+Worker turns retry an exact Codex capacity refusal or a Claude overload after 60 seconds, then 180 seconds, for at most three attempts. Each retry keeps the work tree, profile, model, budget and limits, and asks the worker to continue from the current work. The step keeps one operation identity and sums usage across attempts. Private turn journals retain each attempt. Stopping during a wait returns `stopped`; a daemon restart fails the recorded operation for existing recovery. The same retry rule applies to the restricted analysis turn in `analyze-chats`. Other failures are not retried.
 
-Start a proxy server to use with Cloving:
-```bash
-cloving proxy
+A run of `develop-ticket` or `develop-prompt` has one to three review rounds. Each round does one Claude Code turn in the work tree of the run, on the branch `cloving/<ticket id>-…`, and then opens one approval. The first round makes the work tree. The approval text has the round, the ticket ID, the branch, the commits, the changed files and the report of the worker. Read the diff before you decide. The decision has these results:
+
+- An approval completes the run. It does not merge the branch. Merge the branch yourself.
+- A denial with a feedback text (`--text`) in round 1 or 2 starts the next round. The Claude worker gets the feedback text and adds commits to the same branch.
+- A denial with no text, or a denial in round 3, ends the run.
+
+The worker is not confined. It runs the `claude` command of the search path as the current user, with file edits and shell commands permitted in the work tree and a spend limit of 5 USD for each turn. `CLOVING_CLAUDE_COMMAND` (a JSON list of texts) replaces the command.
+
+Single-run status (`cloving status RUN_ID`, also with `--json`) and watch show each worker command call and its run totals. Token counts retain the reported input, cache read and output categories separately. Codex input includes cached tokens; cache read tokens are not added to input tokens. These selected counts are not complete billing usage or a record of all subagent work. Missing or invalid fields show `Token usage not known`. Costs show the worker-reported USD price when available, otherwise `≈ 7.82 USD (estimate)` when an estimate is available, otherwise `Price not known`; a reported zero shows `0.00 USD`. Totals for an unfinished run are labeled `so far`. JSON uses `null` for unknown numeric values, retains the total reported price field `claudeCostUsd`, and adds `costDisplay` to the run and each worker turn.
+
+The built-in table uses standard short-context prices read on **2026-10-18** from the [OpenAI pricing page](https://openai.com/api/pricing/), in USD per million tokens:
+
+| Model | Input | Cached input | Output |
+| --- | ---: | ---: | ---: |
+| `gpt-6.1-sol` | 2.00 | 0.10 | 10.00 |
+| `gpt-6-astra` | 10.00 | 1.00 | 50.00 |
+
+`CLOVING_TOKEN_PRICES` accepts a JSON object mapping model names to non-negative finite `input`, `cachedInput` and `output` prices per million tokens. Its entries override matching built-in entries and retain the others. Estimates use the reported model or the worker command's model argument, with `estimatedCostUsd` totals only when every ended turn has an estimate. There is no live price lookup; estimates do not change budgets or limits.
+
+`CLOVING_WORKER` selects `claude` (the default) or `codex`. With `codex`, `CLOVING_CODEX_COMMAND` replaces the native Codex command and must still emit native Codex events. A shared-format wrapper uses `CLOVING_CLAUDE_COMMAND` with the `claude` worker selection. Its last JSONL result supplies `total_cost_usd` and `usage.input_tokens`, `usage.cache_read_input_tokens` and `usage.output_tokens`, including on errors. Report only the usage and price of that command call; the wrapper must normalize resumed sessions or multi-input accounting. Cloving does not infer the output format from the executable or model name or reconstruct missing usage from old logs.
+
+Set `CLOVING_PROFILES` to a file such as:
+
+```json
+{
+  "profiles": {
+    "checker": {
+      "env": { "REVIEW_ONLY": "1", "TURN_NAME": "{turn}" },
+      "allowedTools": ["Read", "Grep", "Skill", "Agent"],
+      "maxBudgetUsd": 15,
+      "workflows": ["review-loop"]
+    },
+    "fixer": { "env": { "TURN_NAME": "{turn}" } }
+  }
+}
 ```
-Options:
-- `-f, --files <filenames...>`: Specify filenames of files with context to use for generating code
-- `-t, --temperature <temperature>`: Set the temperature for the model (default 0.2)
-- `-m, --model <model>`: Select the model to use
 
-The proxy server allows you to integrate Cloving with other tools or applications. It starts a local server that can receive requests and forward them to the AI model, returning the responses. This is useful for creating custom integrations or using Cloving in scenarios where a direct CLI interaction isn't suitable.
+A workflow selects a profile with a `protectedEffect` request for capability `claude` and method `run-turn:checker` or `run-turn:fixer`. Profile names contain 1–119 ASCII letters, digits, hyphens or underscores. All fields are optional; `model` and `permissionMode` also override the corresponding Claude command flags. Unspecified fields keep the service defaults, and `run-turn` keeps the original command. Flags after `--` remain unchanged.
+
+`workflows` restricts a profile to the service's registered workflow IDs; omitting it allows every workflow. Each turn receives its run ID and journal operation key joined with a hyphen in `CLOVING_TURN_ID`. That value replaces each `{turn}` in profile environment values. Variables added by one profile do not carry into the next turn. The four GitHub token variables and `GH_CONFIG_DIR` are forbidden in profiles; turns retain an empty GitHub configuration directory. Invalid files stop startup with `invalid-profiles`. Turns refuse unknown profiles with `unknown-profile`, disallowed workflows with `profile-not-allowed`, and Codex profiles with `profile-needs-claude`.
+
+To run a Claude or Codex turn on an existing branch, a custom workflow sets
+the effect target to `branch:feature-search`. The service finds that branch's
+linked work tree in its own repository. The main checkout is excluded. Before
+each turn, the work tree must be clean, including untracked files, submodule
+changes and executable bits. Index entries marked assume-unchanged or
+skip-worktree are refused even when unchanged. Missing or mismatched work trees
+fail with `branch-worktree-not-found`; dirty work trees fail with
+`branch-worktree-not-clean`. Branches beginning with `cloving/` and work trees
+inside the managed work-tree directory fail with `branch-reserved`.
+
+Cloving only inspects an existing branch work tree; the turn itself can edit
+and commit there. Cloving does not create, stash, reset, clean, remove or delete
+it or its branch. Results count commits and changed files from the first turn
+of that run and target, including after a worker restart. Sequential runs have
+separate starting commits; concurrent runs on one branch do not isolate their
+commits. Index flags inside submodules and other settings that hide changes
+are outside these checks. Every GitHub worker method refuses `branch:` targets
+with `branch-target-not-supported`, so this target adds no Cloving push or merge
+step. The bundled development workflows keep their existing targets.
+
+### Pull requests of `develop-issue`
+
+A run of `develop-issue` opens no approval. The GitHub worker makes the work tree from the newest commit of the default branch of `origin`. After the Claude turn, the worker pushes the branch and opens a pull request. The title and the referenced issue come from the ticket text (see "The ticket command"). The pull request body uses `Refs owner/repository#N`, so the merge itself does not close the issue. Then the worker waits for the Greptile review of the pushed commit, and asks for a review with a comment after 5 minutes.
+
+When the ticket names a GitHub issue, the workflow adds `cloving: in progress` after preparing the work tree and removes `cloving: ready` and `cloving: blocked`. A blocked run adds `cloving: blocked` and removes `cloving: in progress`. Start and blocked label failures leave the run's outcome unchanged. Cloving creates the labels it adds or removes with the fixed color `ededed`; existing labels have their color and description reset by `gh label create --force`.
+
+The last worker report must end with exactly one line: `Ticket status: complete` or `Ticket status: partial`. A partial report must put `Remaining:` immediately before a list with one `- ` item per line, followed by the status line. The worker records the parsed status and remaining items before shortening the summary, so summary limits cannot remove those fields. If the preserved fields exceed the result byte limit, the turn fails with `claude-result-too-large` and retains bounded cost metadata; the full report stays in the private turn log. Older recorded turns still use summary parsing. Missing, repeated, unknown or malformed status reports count as partial with the remaining item "The worker report has no ticket status line."
+
+After a merge, a protected GitHub operation updates the issue body and labels. Complete work closes the issue with reason `completed` and adds "Completed in pull request #M." to `## Cloving status`. Partial work keeps the issue open and appends `- Pull request #M: partial. Remaining: ...` to that section at the end of the body, preserving earlier partial lines and other body text. Items are separated by semicolons. The issue privacy check runs before new remaining text is written; a refusal uses "Remaining work is in the private run report." instead. No issue comment is posted. Status writes add and remove only workflow labels, preserving unrelated label edits. Before a body write, Cloving rereads the issue and refuses a changed body with `github-issue-conflict`; the merged outcome records `issueUpdate: failed`. GitHub does not support conditional PATCH requests for this endpoint, so this check cannot make the read and write atomic.
 
-### Token Estimation
+Partial work removes `cloving: in progress` and adds `cloving: ready`, so the next queue cycle can select the same issue and read its remaining work from the issue body. The third partial run adds `cloving: blocked` instead of `cloving: ready`. Completion removes these workflow labels. Status operations reconcile the pull request number in the stored history after a restart to avoid duplicate writes. The effect limit stays at 20 units: the post-merge status operation replaces the final label operation.
 
-Estimate the number of tokens in the current working directory or specified files:
-```bash
-cloving tokens
+Partial history comes only from a hidden HTML comment at the end of the issue body, beginning with `cloving-status`. Its JSON object has `version: 1`, a `partialRuns` array of pull request numbers and remaining-item lists, and an optional `completedPullRequest`. Double hyphens and greater-than signs in JSON strings are escaped so they cannot end the comment. Each write regenerates the readable section from this data and replaces the exact previously generated section. Other Markdown stays unchanged, including status examples, lists, tables, HTML and unclosed fences. Missing, broken or unknown metadata counts as zero earlier partial runs and is replaced on the next write; readable text is never used to reconstruct history. A block followed by other issue text is left unchanged and counts as missing terminal metadata.
+
+Partial history, including its JSON block, is bounded by the 48,000-byte ticket-read limit, reserving 2,048 bytes for the title, issue reference and worker notes. If the new remaining items do not fit, Cloving uses the private-report notice above. If even the notice cannot fit alongside the existing body and history, the issue update fails without requeueing it. Retries check the same size limit before restoring queue labels. Review and merge-fix turns receive the previous report's remaining items, including preserved items from shortened summaries, and must reassess each item before reporting completion.
+
+Merged runs retain `handoff_requested` with `ticketStatus: complete` or `partial`, visible in `cloving status` and watch. If the issue update fails, `issueUpdate: failed` is also shown. The queue reports each terminal run without a successful handoff and continues, stopping after three such runs in a row. A successful handoff resets the count; the queue journal preserves the count and run IDs across daemon restarts. Inspect failed GitHub operations and reconcile their issues before requeueing them. A later partial run does not mark an earlier blocked ticket as done.
+
+To resume a queue stopped at this limit, stop the service with Control-C, inspect the failures and reconcile the affected issues, then run `cloving start --reset-queue` with the same repository, runtime and queue settings. This clears the failure streak once and preserves tracked commands. Ordinary restarts, including automatic self-updates, preserve the count. Resetting the queue does not change issue labels or retry blocked issues.
+
+At the confidence score 5/5, the worker merges the pull request with a merge commit, with no human approval. Then it removes the remote branch, the work tree and the local branch. With a lower score, the Claude worker gets the summary and the findings of the review for one more round. After three such rounds, or after 60 minutes with no review, the run stops and the pull request stays open.
+
+The watch board keeps blocked `develop-issue` runs in `Stopped`. A qualifying later local run shows `Done in a later run`. Otherwise, the board reads the recorded pull request with `CLOVING_GH_COMMAND` (default `gh`). The service supplies its repository, and the board checks the local origin and the recorded PR identity. A confirmed merge shows `PR merged #N`; a read failure shows `PR status unavailable`. Other PR states keep `Needs attention`. These marks do not change the run outcome.
+
+Reads run in the background, one at a time, with a five-second limit. Board loads can refresh unresolved PRs at least 60 seconds after the previous attempt started. Confirmed merges remain cached until the watch process stops. A later normal page load shows each result.
+
+The GitHub worker does not push a change that has the path of the home folder in a file or in a commit message. `CLOVING_PRIVATE_TEXTS` (a JSON list of texts) adds more texts to refuse, with no difference between capital and small letters. `CLOVING_CHECK_COMMAND` (a JSON list of texts) names a check that must pass in the work tree before a merge. `CLOVING_GH_COMMAND` replaces the `gh` command. The worker uses the `gh` login and the git credentials of the current user.
+
+## Continuous process
+
+In a continuous process, Cloving develops one ticket after the next with `develop-issue`. Use one terminal session for the service that stays open, for example a `tmux` session. Do these steps for each issue:
+
+1. Write a small issue: one behavior, clear criteria that a test can check, and the first tests. The prompt "Write a ticket for Cloving" helps.
+2. Run it: `cloving run develop-issue --ticket ISSUE_NUMBER`.
+3. Follow the run on the watch page, or with `cloving status RUN_ID` and `cloving events RUN_ID --follow`.
+4. Check the merge. The run completes when the GitHub worker merges the pull request. The watch page shows the number of the pull request of the run (`PR_NUMBER`). It is also `pullRequest.number` of the run in `http://127.0.0.1:3663/data.json`. The pull request number and the issue number are different.
+   - Make sure that the pull request is merged: `gh pr view PR_NUMBER --json state,mergedAt`.
+   - Check the ticket status and issue: `gh issue view ISSUE_NUMBER --json state,body,labels`. Complete work closes the issue; partial work stays open and requeues until the third partial run blocks it.
+5. Update the local `main`: `git switch main`, then `git pull --ff-only`.
+6. When the repository is the Cloving checkout itself, also restart the service, so that it runs the new code. Stop it with Control-C, then start it again with the same settings.
+7. Go to the next issue.
+
+When a run stops and the pull request stays open, read the review. Fix the work yourself, or write a smaller issue.
+
+Know these limits before you start:
+
+- The cost limit of each Claude turn is 5 USD. A run of `develop-issue` can have up to four Claude turns. `CLOVING_CLAUDE_COMMAND` changes the command and its limit.
+- The text of a pull request is public in a public repository. The worker gets an instruction to write no local file path in a file or in a commit message.
+- `CLOVING_PRIVATE_TEXTS` adds texts that the GitHub worker refuses to push, for example the names of private projects. The path of the home folder is always refused.
+- `CLOVING_CHECK_COMMAND` names the checks of the repository. Set it, because a merge at 5/5 has no human approval. With no setting, the merge occurs with no check.
+
+## Prompts for a coding agent
+
+Copy a prompt, replace the words in capital letters, and give it to a coding agent.
+
+### Set up Cloving for a repository
+
+```text
+Set up Cloving for my repository REPOSITORY_PATH. Ask me for each value that you do not know. Do not push, publish or merge anything in this setup.
+
+1. Check the platform: macOS or Linux on arm64 or x64, with the Node and npm versions of "engines" in package.json of Cloving. Check that git and the claude command work. If I want develop-issue, check that gh has a login and that Greptile reviews the GitHub repository.
+2. If I have no Cloving checkout, clone https://github.com/cloving-ai/cloving-ai.git to ~/cloving. In the checkout, run: npm ci --ignore-scripts
+3. Write a launcher ~/.local/bin/cloving that runs src/cli.ts of the checkout with the correct node program, and make it executable. Do not use npm link, and do not install the npm package with the name cloving. Make sure that ~/.local/bin is on the search path and that "cloving --version" works.
+4. Ask me which tracker has my tickets. Write a ticket command for that tracker in ~/.local/bin. The command gets a ticket ID as its last argument and prints the text of the ticket. For develop-issue, the first line is "# " and the title, and one line is "GitHub issue: OWNER/REPOSITORY#NUMBER". Test the command with one ticket ID, and show me the output.
+5. Start the service in a terminal session that stays open, for example a tmux session. In that session, in my repository, run: CLOVING_TICKET_COMMAND='["TICKET_COMMAND"]' cloving start
+   For develop-issue, also set CLOVING_CHECK_COMMAND to the checks of my repository. Give me the address of the watch page.
+6. Make a first run with develop-prompt and a small task that I agree to. Show me the output of "cloving questions" and the diff of the branch. Do not approve or deny. I decide.
+7. Then run my first ticket: cloving run develop-ticket --ticket TICKET_ID
+   Show me the diff again before I decide.
 ```
-or
-```bash
-cloving t
+
+### Run a continuous process
+
+```text
+Run a continuous process with Cloving and develop-issue in my repository REPOSITORY_PATH. The Cloving service runs in the terminal session SESSION_NAME. Do the issues ISSUE_LIST one at a time, in this order.
+
+For each issue:
+1. Read the issue. Do not change it.
+2. Run: cloving run develop-issue --ticket ISSUE_NUMBER
+   ISSUE_NUMBER is the number of the issue. Record the run ID.
+3. Follow the run with "cloving status RUN_ID" and "cloving events RUN_ID --follow".
+4. When the run completes, get the number of its pull request (PR_NUMBER). It is pullRequest.number of the run in http://127.0.0.1:3663/data.json, and the watch page shows it too. Then:
+   - Make sure that the pull request is merged: gh pr view PR_NUMBER --json state,mergedAt
+   - Check the issue state, remaining work and queue labels: gh issue view ISSUE_NUMBER --json state,body,labels
+5. Update the local main branch: git switch main, then git pull --ff-only
+6. If the repository is the Cloving checkout itself, restart the service in its terminal session, so that it runs the new code. Stop it with Control-C, then start it again with the same settings.
+7. Run the checks of the repository on the new main branch.
+8. Add a record of the run to RECORD_FILE, outside the repository: the issue, the run ID, the pull request, the merge commit, the number of rounds and the result of the checks.
+9. Go to the next issue.
+
+Stop and ask me when:
+- an issue is not small, or has no criteria that a test can check;
+- a run stops, or its pull request stays open;
+- the checks fail on the main branch after a merge;
+- a step needs a change of the settings or of the credentials, or work in a different repository;
+- a step needs a force push, a change of the history, or a publication.
+
+Do not merge a pull request yourself. Do not approve or deny for me.
 ```
-Options:
-- `-f, --files <filenames...>`: Specify filenames of files to estimate tokens for
 
-### Generating Context
+### Write a ticket for Cloving
+
+```text
+Help me write a ticket for Cloving. A Claude Code worker gets the full text of the ticket and no other context. Ask me questions until each part is clear. Then write the ticket in Markdown with these parts:
+
+# TITLE
+  One line. For develop-issue, it becomes the title of the pull request.
+GitHub issue: OWNER/REPOSITORY#NUMBER
+  Only for develop-issue. The pull request references this issue; complete work closes it after the merge.
+## Problem
+  What is wrong now, with facts.
+## Desired outcome
+  What is true when the work is done.
+## Concrete scenario
+  One example from the start to the end, with real values.
+## Scope
+  The changes, with the names of the files, commands and functions that you know.
+## Non-goals
+  What the work must not change.
+## Acceptance criteria
+  A numbered list. A test can check each criterion.
+## First tests
+  The first tests to write. Each test fails before the change.
+
+Rules:
+- One ticket has one behavior. If the work needs more than one pull request, split the ticket.
+- Write no secret, no private data and no local file path. For develop-issue, the ticket text and the branch become public.
+- Use one term for one thing.
+```
+
+### Find workflows in your chats
+
+```text
+Find workflows in my chats with coding agents, and write a draft Cloving workflow for one of them.
 
-Create a context string for generating prompts outside of the cloving cli:
-```bash
-cloving generate context
+Rules:
+- Read only the chats that I select. Ask me for the list first. Do not read other chats.
+- Keep the chat text and private data out of the repository. Do not copy chat text, names of persons, secrets or local paths into a file of the repository. Keep your notes outside the repository.
+
+Steps:
+1. In the selected chats, find sequences of steps that repeat. For each sequence, list the steps, the tool of each step (for example git, a test command, gh or a model), and each decision of a person (for example "approve the diff").
+2. Show me the list, and ask me which sequence to use.
+3. Map each step that changes something outside the workflow to protectedEffect, with a capability and a method. Map each decision of a person to decisionGate.
+4. Use only the capabilities that have a worker: claude (method run-turn) and github. Put each step that needs a different capability in a list of open points, not in the draft.
+5. Write the draft in the form of workflows/develop-ticket.ts of the Cloving checkout: an exported async function with the directive "use workflow", and the step helpers from the subpaths of cloving/workflows.
+6. Write a list of the human decisions in the draft: for each decisionGate, the question, the person who decides, and the result of each answer.
+7. Write workflow tests with a fake step bridge, in the form of test/develop-workflow-fixture.ts.
+8. Tell me which changes of the Cloving code the draft needs before the service can run it. The section "Develop a workflow" of the Cloving README lists them.
+```
+
+## Develop a workflow
+
+A workflow is a TypeScript file in the form of `workflows/develop-ticket.ts`:
+
+- An exported async function with the directive `"use workflow"` as its first statement. The directive needs the compiler of the Workflow SDK, not only TypeScript.
+- The first argument is the input of the run. A resolver of the daemon makes it, for example `cycleId`, `ticketId`, `ticket` and `repository`. After a decision, the host calls the function again with the decision (`gateId`, `decision` and `answer`) as the second argument. The function must examine the decision before it asks for an effect, as `decided()` in `workflows/develop-ticket.ts` does. If it does not, it does the work of round 1 again.
+- The step helpers come from the subpaths of `cloving/workflows`: `protectedEffect` from `cloving/workflows/steps/protected-effect`, `decisionGate` from `cloving/workflows/steps/decision-gate` and `loadCycle` from `cloving/workflows/steps/load-cycle`. The type `CycleOutcome` comes from `cloving/workflows`. An import of `cloving/workflows` starts no service.
+- `protectedEffect` asks the daemon for one effect of a capability, for example a Claude turn. `decisionGate` opens a decision for a person.
+- The function returns a `CycleOutcome`: `waiting_for_decision`, `handoff_requested` or `blocked`.
+
+```ts
+import type { CycleOutcome } from "cloving/workflows";
+import { decisionGate } from "cloving/workflows/steps/decision-gate";
+import { protectedEffect } from "cloving/workflows/steps/protected-effect";
+
+export async function developTicket(
+  input: { readonly cycleId: string; readonly ticket: string },
+  decision?: {
+    readonly gateId: string;
+    readonly decision: string;
+    readonly answer: string | null;
+  },
+): Promise<CycleOutcome> {
+  "use workflow";
+  if (decision?.decision === "approved")
+    return {
+      kind: "handoff_requested",
+      cycleId: input.cycleId,
+      promotionId: `cloving-${input.cycleId}`,
+    };
+  if (decision !== undefined)
+    return {
+      kind: "blocked",
+      cycleId: input.cycleId,
+      reason: "The operator denied the work.",
+      evidenceId: decision.gateId,
+    };
+  const turn = await protectedEffect({
+    scope: { phase: "implement", operation: "claude-turn", round: 1 },
+    capability: "claude",
+    method: "run-turn",
+    target: input.cycleId,
+    payload: input.ticket,
+    units: 1,
+  });
+  if (turn.kind !== "completed")
+    return {
+      kind: "blocked",
+      cycleId: input.cycleId,
+      reason: "The Claude turn did not complete.",
+      evidenceId: "claude-turn",
+    };
+  const gate = await decisionGate({
+    gateId: "review-1",
+    kind: "approval",
+    prompt: "Review the work of the Claude worker.",
+  });
+  if (gate.kind !== "opened")
+    return {
+      kind: "blocked",
+      cycleId: input.cycleId,
+      reason: "The review gate did not open.",
+      evidenceId: "review-1",
+    };
+  return {
+    kind: "waiting_for_decision",
+    cycleId: input.cycleId,
+    decisionId: gate.decisionId,
+  };
+}
 ```
-Options:
-- `-f, --files <filenames...>`: Specify filenames of files with context
 
-### Generating Unit Tests
+In this example, an approval completes the run and a denial ends it. `workflows/develop-ticket.ts` also starts one more round after a denial with a feedback text.
+
+The workflow tests run the workflow function with a fake step bridge (`test/develop-workflow-fixture.ts`). The fixture resolves `cloving/workflows` to the files of `src`, records each effect request and gate request, and gives the results of a scenario. `test/develop-ticket-workflow.test.ts` and `test/develop-issue-workflow.test.ts` use it.
 
-Generate unit tests for changes or specific files:
-```bash
-cloving generate unit-tests
+`cloving start` compiles the TypeScript files in the application's `workflows` folder. Each file may contain one workflow function, and function names must be unique across files. The four built-in registrations (`develop-ticket`, `develop-issue`, `develop-prd` and `develop-prompt`) keep their existing input contracts and resolvers.
+
+To register another workflow, put `<name>.declaration.json` beside `<name>.ts`:
+
+```json
+{
+  "workflowId": "review-run",
+  "effectLimit": 14,
+  "capabilities": ["claude"],
+  "input": {
+    "maximumBytes": 65536,
+    "fields": {
+      "prompt": { "type": "string" },
+      "rounds": { "type": "integer", "minimum": 1, "maximum": 10, "optional": true }
+    }
+  }
+}
 ```
-Options:
-- `-s, --silent`: Run without asking for confirmation
-- `-f, --files <filenames...>`: Specify filenames for the unit tests
-- `-m, --model <model>`: Select the model to use
 
-## Command Line Options
+The ID accepts 1–64 letters, digits or hyphens. The effect limit is 1–100; capabilities must contain `claude`, `github`, or both. The input byte limit is 1–1048576, subject to the service's own limit. Fields accept nonempty strings, integers with optional inclusive bounds, or booleans. Fields are required unless `optional` is `true`; unknown fields are rejected. Bounds apply only to integers.
+
+After startup, `cloving status` lists the declared ID. Submit JSON with `cloving run review-run --input input.json`. The function receives `{ cycleId, repository, input }`, where `cycleId` is `task-` followed by 12 characters derived from the command ID, `repository` is the service repository, and `input` retains the checked JSON values. Invalid input is rejected before a run starts. Invalid declarations or duplicate workflow IDs or function names stop startup.
+
+Candidate policy checking is available internally through `checkWorkflowCandidate` in `src/workflow-candidate.ts`. It takes serializable analysis facts, an export snapshot and a candidate declaration containing `workflow` and `methods`. Each declared capability requires a nonempty list of distinct method names. The existing workflow sidecar format is unchanged. Results are sorted, unique refusal codes; an empty list grants no admission or execution authority.
+
+The caller supplies imported symbol names, literal effect pairs (`null` represents a dynamic value), direct-effect and unsupported-form findings, and known call and unit totals. Unknown portions of a total still require runtime budget enforcement. This pure checker does not analyze source or verify these facts. Source-to-facts analysis, SDK candidate compilation and the installed candidate admission adapter remain unimplemented.
+
+## Development of Cloving
+
+```sh
+npm ci --ignore-scripts
+npm run check:setup
+npm run build
+node dist/src/cli.js --help
+npm pack --ignore-scripts
+```
 
-Usage: `cloving [command] [options]`
+`npm pack` prints the file name of the tarball. Install it into a separate project with `npm install --ignore-scripts --omit=dev /absolute/path/to/TARBALL`, then run `./node_modules/.bin/cloving --version` or `./node_modules/.bin/cloving start`. The package includes the emitted CLI, start program, compiler and bundled workflows; startup uses the installed runtime dependencies. The package has no installation hooks. An import of `cloving/workflows` gives the step helpers `loadCycle`, `protectedEffect` and `decisionGate`, and starts no service.
 
-Options:
-- `-V, --version`: Output the version number
-- `-h, --help`: Display help for command
+`npm run check` and `npm run test:concurrency` currently reject admission because the complete quality policy is not implemented. Setup checks are not product acceptance. State and retained releases will live outside the package installation; installing or updating the package does not activate a daemon or migrate state.
 
-Commands:
-- `config`: Configure Cloving with your API key and models to use
-- `init`: Setup Cloving in the current directory
-- `chat`: Start an interactive chat with Cloving
-- `tokens`: Estimate the number of tokens in the current working directory or specified files
-- `proxy`: Start a proxy server to use with Cloving
-- `models`: List available models
-- `commit`: Alias for cloving generate commit
-- `generate`: Generate various items like unit-tests and code reviews
-  - `commit`: Generate a commit message and commit the changes
-  - `code`: Generate code based on a prompt
-  - `context`: Generate context for building a prompt outside of cloving
-  - `shell`: Generate a shell command based on a prompt
-  - `unit-tests`: Generate unit tests
-  - `review`: Review the code for committed changes
+Run `npm run test:scale` on an otherwise idle machine to measure authority opening at 1,000, 10,000 and 50,000 events. This command runs the benchmark alone, without coverage; the regular test suite excludes it. The fixture uses completed runs with budgets, gates and released continuations. It requires each opening to take less than two seconds and the largest opening to take less than eight times the 10,000-event opening. Replay uses the pure reducer with run-scoped projections and preserves shared effect and lease state. Large effect histories, growing gate or pending-intent state within one run, and cancelled-run recovery still require separate scaling work; this benchmark does not establish their bounds. The generated-history parity and tamper tests compare replay with the full reducer and cover every event type.
 
-Most commands support the following options:
-- `-s, --silent`: Run the command without asking for confirmation of submitting prompts
-- `-m, --model <model>`: Select the model to use (e.g., openai, claude, ollama, ollama:llama3, claude:claude-3-5-sonnet-20240620)
+`npm run check:quality` checks the npm manifest, lock and installed versions, regenerates TypeScript output in memory, inventories first-party files, and runs strict compilation, the proposed module catalog, workflow/effect boundaries, suppression and test-integrity checks, formatting, typed lint, structural checks, clone detection and the regular local test suite. Production modules require at least 90% line, statement and function coverage and 85% branch coverage per file. Coverage uses native V8 ranges mapped to the syntax tree of the exact Node-stripped source; unimported production files fail. Class and named object types allow at most 24 callable members; interfaces allow 10. Clone checks support ordinary TypeScript and JavaScript; JSX is rejected until separately qualified. `npm run check:lint`, `npm run check:format` and `npm run test:quality` run individual development checks.
 
-## Contributing
+The watch scrolling tests launch an isolated headless Chrome process at desktop and phone widths. They require Chrome on the test machine. Run them with `node --test test/watch-scrolling.test.ts`. The fixture serves bundled Preact and board data over loopback and blocks external page resources.
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Set `CLOVING_CHECK_TIME_FACTOR` to a whole number from 1 to 5 (default 1) to multiply the developer gate test and coverage command time limits, the inner hook check limit (5 seconds by default), and the installed hook limit (10 seconds by default). With factor 3, the hook limits are 15 and 30 seconds, respectively.
 
-## License
+The catalog and checker configuration are local proposals. The bounded SDK artifact, dependency-surface, production-coverage and mandatory-test inventory components have local qualification fixtures. Protected activation of their records, verifier execution and hooks remain pending. Dependency snapshots and supplied review records cannot activate a candidate. The local quality command cannot accept a product candidate. Static workflow checks are not isolation or replay proof. Deterministic sequencing fixtures qualify the test mechanism; they do not prove ownership or storage concurrency in the service.
 
-This project is licensed under the [MIT License](LICENSE).
+The coverage profile supports strip-only TypeScript and JavaScript (`ts`, `mts`, `cts`, `js`, `mjs`, `cjs`). It rejects source-map and coverage-ignore patterns interpreted by the provider, including patterns inside strings. Native V8 limitations around throwing calls and default arguments remain; coverage does not replace behavioral assertions. Production roles come from the complete module catalog, independently of which files tests import. Nested npm workspaces and unsupported dependency directory links fail explicitly until qualified.
 
-## Acknowledgements
+For trusted development fixtures, `npm run build:workflows -- SOURCE_DIRECTORY OUTPUT_DIRECTORY` runs the selected directive compiler with deterministic manifest ordering. Run the compiler in an isolated fixture project; its output directory must resolve that project's installed `workflow` dependency. Compiler caches and generated handlers stay outside the application source tree. Generated handlers are development artifacts and do not grant authority to execute effects.
 
-- This project is inspired by [aichat](https://github.com/sigoden/aichat) and [aider](https://github.com/paul-gauthier/aider)
-- Special thanks to the open-source community for inspiration and support.
+SDK qualification uses a fixed logical output path and an empty root TypeScript configuration. Its separate input preflight rejects ancestor/nested compiler configuration, outside first-party inputs, dynamic/CommonJS loading and ambiguous local declaration/runtime resolution. Record the full installed tool/helper closure and every generated handler, manifest and debug artifact, then regenerate at the same logical path and compare preserved bytes. The direct build command does not authenticate these records. Real packed-helper execution is qualified with a disposable prototype.