@skein-code/cli 0.2.2 → 0.3.0

package/docs/MULTI_MODEL_TEAMS.md

@@ -3,8 +3,10 @@
 Skein's team mode treats models as replaceable specialists, not fixed brand
 stereotypes. A project can route `frontend`, `backend`, `architect`, `research`,
 `security`, `tester`, and `reviewer` profiles to different providers. The main
-agent remains the only writer; specialists inspect independently, exchange
-bounded reports, and a reviewer accepts or requests one revision round.
+agent remains the only writer of the active workspace; specialists inspect
+independently, exchange bounded reports, and a reviewer accepts or requests one
+revision round. An opt-in writer lane may prepare a patch in a disposable Git
+worktree, but it cannot integrate that patch itself.
 
 ## Why This Shape
 
@@ -94,6 +96,49 @@ reports. The normal default is local persistence because it makes interrupted
 runs, reviewer disagreements, and delivery audits recoverable without sending
 the blackboard to a hosted service.
 
+Writer runs always persist their audit record even when ordinary council
+persistence is disabled. Integration depends on the recorded patch hash,
+review verdict, base commit, file list, cleanup result, and checkpoint.
+
+## Isolated Writer Lane
+
+The first writer lane is deliberately opt-in and single-lane:
+
+```json
+{
+  "agents": {
+    "writerEnabled": true,
+    "writerProfile": "implementer",
+    "writerReviewerProfile": "reviewer",
+    "maxWriterPatchBytes": 60000
+  }
+}
+```
+
+`writer_run` asks for write, Git, and shell permission, creates a detached
+worktree at the current `HEAD`, and gives the writer only `read_file`,
+`list_files`, `search_code`, `write_file`, and `apply_patch`. Shell, Git,
+network, hooks, MCP, memory, external CLI runtimes, workspace-authored writer
+profiles, and recursive agents remain unavailable. The reviewer must also use
+an API route so it receives the complete patch. The patch is rejected rather
+than truncated above `maxWriterPatchBytes` (60,000 by default; 120,000 maximum).
+
+The worktree is removed and pruned before the tool returns. Team Run v2 stores
+the Git `--binary` text patch, SHA-256, base commit, file list, writer and
+reviewer reports, cleanup result, and integration state. `skein agents show
+<run-id>` displays that evidence.
+
+`writer_integrate` is a separate main-agent action. It requires the accepted
+Team Run ID and patch SHA, reparses and bounds every path, requires the same
+`HEAD`, refuses dirty target files, runs `git apply --check`, and captures every
+target in a checkpoint. A failed apply restores that checkpoint; conflicts are
+reported without overwriting the active workspace. A successful result prints
+the exact `skein checkpoint restore <session> <checkpoint>` rollback command.
+
+Dirty main-workspace state is not mirrored into the writer worktree. Parallel
+writers, automatic merge or rebase, submodule mutation, and external CLI writer
+mode remain future increments.
+
 ## Configuration
 
 Credentials are referenced by environment-variable name. They are never stored
@@ -321,7 +366,12 @@ activity, and reviewer decisions are the explainable artifacts.
 ## Current Safety Boundary
 
 - Specialist agents are read-only and cannot recursively delegate.
-- Only the main agent may mutate the active workspace.
+- Only the main agent may mutate the active workspace. An enabled writer can
+  mutate only its disposable worktree and returns a reviewed patch.
+- Writer and integration operations share a repo-scoped exclusive lease, while
+  Team Run and checkpoint storage retain their separate namespace leases.
+- Workspace-authored profiles cannot receive writer authority, and repository
+  config cannot enable or retarget the writer lane without explicit trust.
 - Peer messages are summaries capped before entering another context.
 - Review rounds are capped at three by schema and default to one.
 - Cancellation uses the parent abort signal.
@@ -334,7 +384,8 @@ activity, and reviewer decisions are the explainable artifacts.
    search without granting arbitrary shell/network authority.
 2. Persist a content-addressed team blackboard and compact provenance bundle.
 3. Add per-route cost accounting and user-confirmed spend controls.
-4. Add worktree-isolated writer agents with explicit merge/review gates.
+4. Add dependency-aware parallel writer worktrees after conflict-rate and
+   rollback evidence justify relaxing the single-lane gate.
 5. Score routes from project-local eval outcomes instead of relying on model
    brand assumptions.
 6. Add Gemini CLI and optional tmux/iTerm visible-pane hosts. Codex, Claude,

package/docs/NEXT_STEPS.md

@@ -9,7 +9,7 @@ one of the milestones below.
 
 - Product name: `Skein`; primary executable: `skein`.
 - Compatibility executables: `mosaic` and `mosaic-code`.
-- Current release: `0.2.1`.
+- Current release: `0.3.0`.
 - Runtime requirement: Node.js `>=22.16.0` (the runtime uses unflagged
   `node:sqlite` with FTS5, and current CLI/build dependencies require this
   Node 22 baseline).
@@ -35,11 +35,11 @@ npm ci
 npm run check
 npm run test:pty
 npm audit --omit=dev
-npm pack
+npm run release:verify -- --output-dir artifacts/package
 ```
 
-The latest verified package was `skein-code-cli-0.2.1.tgz`. The verifier writes
-its SHA-256 to `artifacts/package/skein-code-cli-0.2.1.tgz.sha256`, and CI
+The latest verified package was `skein-code-cli-0.3.0.tgz`. The verifier writes
+its SHA-256 to `artifacts/package/skein-code-cli-0.3.0.tgz.sha256`, and CI
 retains the checksum beside the package metadata. The checksum is deliberately
 not copied into this packaged document because doing so would change the
 archive it describes.
@@ -47,11 +47,11 @@ archive it describes.
 The final verification included a fresh install and real PTY interaction for
 all three executable aliases, `/about`, a permission prompt, denial, and clean
 Ctrl+C exit. PTY coverage included 20, 24 ASCII, 40, 80, 120 columns and a
-40x10 short-height case. The current suite contains 31 test files and 253 tests.
+40x10 short-height case. The current suite contains 34 test files and 317 tests.
 
 ## Recommended Order
 
-### P0: Continuous Integration And Release Reproducibility (Branch Rule Pending)
+### P0: Continuous Integration And Release Reproducibility
 
 `.github/workflows/ci.yml` now covers Node 22 on macOS and Linux. It runs
 typecheck, unit tests, build, smoke, the PTY suite when `expect` is available,
@@ -75,8 +75,11 @@ Implementation notes:
 - `npm run release:verify` reproduces the package from source, installs it into
   an isolated prefix, rejects packaged local state, and exercises `skein`,
   `mosaic`, and `mosaic-code`.
-- Configure the `main` branch rule to require the `check` status after the
-  workflow is present on GitHub.
+- The `main` branch rule requires the strict `check` status. The v0.2.3 CI and
+  release workflows completed successfully and npm published
+  `@skein-code/cli@0.2.3` under the `latest` tag. The v0.3.0 package was
+  reproduced and verified locally (34 test files, 317 tests, all three bin
+  aliases); its tag, CI run, and `npm publish` to `latest` follow this commit.
 
 ### P1: Skein Storage Namespace And Migration
 
@@ -261,9 +264,19 @@ Implementation progress:
   that is parsed into a structured conflict report and surfaced in the returned
   team summary. The TUI Team Cockpit and Workbench render the queued and
   cancelled states with distinct glyphs, colors, and the cancellation reason.
-- See `docs/MULTI_MODEL_TEAMS.md`. Writer worktrees, persistent blackboard
-  artifacts, cost controls, Gemini CLI, and optional tmux/iTerm pane hosts remain
-  next.
+- The first writer lane is implemented behind `agents.writerEnabled=false` by
+  default. `writer_run` creates one repo-leased disposable worktree, confines an
+  API writer to five path-safe read/write tools, requires an API Reviewer, and
+  persists a bounded patch plus lifecycle evidence in Team Run v2.
+- `writer_integrate` is the only main-workspace integration path. It gates on
+  patch SHA, accepted review, base `HEAD`, clean target paths, patch parsing,
+  `git apply --check`, and a mandatory checkpoint; failed applies restore the
+  checkpoint and conflicts never overwrite user work.
+- Writer regression coverage proves success and rollback, concurrent-lane
+  rejection, cancellation cleanup, oversize rejection, SHA and dirty-target
+  gates, simulated partial-apply recovery, workspace-profile rejection, and v1
+  Team Run compatibility. Parallel writers, external CLI writer mode, cost
+  controls, Gemini CLI, and optional tmux/iTerm pane hosts remain next.
 
 ### P2: MCP, Skills, And Workflow Trust UX
 
@@ -322,9 +335,7 @@ deprecation window is complete.
 
 ## Suggested Next Conversation Opening
 
-Start with: “Implement the first worktree-isolated writer lane from the P1
-multi-agent scheduler milestone. Preserve the current read-only council and
-review gate, serialize integration into the main workspace, and prove cancel,
-conflict, checkpoint, and rollback behavior before enabling parallel
-mutation.” Then inspect the scheduler, team-run persistence, permissions, and
-namespace lease boundaries before changing runtime behavior.
+Start with: “Audit the opt-in P1 writer lane against its Team Run v2 evidence,
+then decide whether the next increment should add external CLI writers or
+dependency-aware parallel worktrees. Keep active-workspace integration explicit
+and preserve SHA, review, clean-target, checkpoint, and rollback gates.”

package/examples/config.yaml

@@ -42,6 +42,14 @@ agent:
     - npm test
   checkpointBeforeWrite: true
 
+agents:
+  enabled: true
+  # Enable only in user-owned or explicitly trusted project configuration.
+  writerEnabled: false
+  writerProfile: implementer
+  writerReviewerProfile: reviewer
+  maxWriterPatchBytes: 60000
+
 hooks:
   beforeTool: []
   afterTool: []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-code/cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   "type": "module",
   "license": "MIT",
@@ -14,6 +14,13 @@
   "publishConfig": {
     "access": "public"
   },
+  "skein": {
+    "releaseNotes": [
+      "Guided first-run setup for official APIs and third-party relays",
+      "Protocol-aware OpenAI-compatible and Anthropic-compatible routing",
+      "Update notices now include a bounded summary of what changed"
+    ]
+  },
   "bin": {
     "skein": "dist/cli.js",
     "mosaic": "dist/cli.js",