@skein-code/cli 0.3.7 → 0.3.8

package/docs/ARCHITECTURE.md

@@ -44,7 +44,34 @@
 7. Execute tools, emit events, and append their grounded results to the model
    conversation.
 8. Continue until the model returns a final response or the turn limit is hit.
-9. Run configured verification commands after changes and persist the session.
+9. Run configured verification commands after changes. The completion gate accepts
+   only current successful test, typecheck, lint, build, check, or `git diff
+   --check` evidence recorded after the last mutation. An early final response
+   receives one bounded recovery turn; the runtime persists `verified`,
+   `unverified`, or `verification_failed` instead of trusting completion claims
+   in model text.
+10. Persist the outcome and expose the same status through the TUI, text, JSON,
+    and JSONL surfaces.
+
+## Interactive startup gate
+
+New interactive sessions establish local context readiness before creating or
+saving a session. Resumed sessions keep their existing transcript-first startup
+and rely on the same per-turn retrieval freshness checks:
+
+1. Inspect and schema-check the persisted local index.
+2. Compare its manifest with the current workspace.
+3. Incrementally scan, chunk, and write only when the index is missing, stale,
+   or first-run setup explicitly requests a visible build.
+4. Reload the written artifact from disk and match generation, file count,
+   chunk count, and manifest freshness.
+5. Pass the immutable readiness snapshot to the TUI; only then enable the
+   composer and initialize session extensions.
+
+An empty workspace produces a valid zero-file generation. Validation failures
+stay in a retry/exit state and occur before an empty session is persisted.
+Headless runs retain non-animated lazy indexing so structured automation does
+not acquire terminal-only behavior.
 
 ### Prompt layers
 
@@ -82,6 +109,12 @@ Index state is persisted in the active project namespace. Search results are
 revalidated against current files before packing, so a stale index reduces
 recall rather than silently injecting old code.
 
+The fresh-session TUI consumes the same verified readiness snapshot. Wide
+terminals expose it in a factual workspace rail alongside the selected model,
+mode, permission posture, tool/Skill/MCP counts, and memory state. Narrow
+terminals collapse to one column, and team activity takes precedence over this
+welcome-only rail.
+
 ## Storage
 
 Project-local data is kept in `.mosaic/` and ignored by default:
@@ -122,6 +155,10 @@ useful without silently accumulating guesses.
   Plan mode additionally injects a read-only, approval-oriented planning
   directive; Build mode is required before workspace mutation is possible.
 - Hooks are bounded subprocesses and receive structured environment metadata.
+- Dynamic shell commands with no statically resolvable target use bounded
+  before/after content-fingerprint snapshots across workspace files. Incomplete
+  observation is persisted as unknown mutation tracking and forces an
+  unverified completion rather than a false no-change result.
 - Checkpoint restore validates paths before writing snapshots back.
 - Session and checkpoint directories reject symlinked `.mosaic` storage paths;
   local index files are schema-checked and out-of-root entries are discarded.

package/docs/NEXT_STEPS.md

@@ -9,16 +9,18 @@ one of the milestones below.
 
 - Product name: `Skein`; primary executable: `skein`.
 - Compatibility executables: `mosaic` and `mosaic-code`.
-- Current repository version: `0.3.5`.
+- Current repository version: `0.3.8`.
 - 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).
-- Retrieval: local BM25/path/symbol index with freshness validation and bounded
-  packing; no retrieval service is required.
+- Retrieval: local BM25/path/symbol index with visible interactive preparation,
+  persisted-content validation, and bounded packing; no retrieval service is
+  required.
 - Agent: provider-agnostic multi-turn runner for OpenAI, Anthropic, Gemini, and
   OpenAI-compatible endpoints; built-in tools, permissions, checkpoints,
   workflows, Skills, MCP, expert profiles, sessions, and memory are present.
-- UI: real Ink/React terminal UI, not a browser prototype. It supports prompt
+- UI: real Ink/React terminal UI, not a browser prototype. Fresh wide sessions
+  include a factual workspace rail; all sizes support prompt
   history, `@file` completion, command completion, multiline editing, queued
   follow-ups, live context inspection, permission approval, themes, ASCII mode,
   `NO_COLOR`, and narrow-height degradation.
@@ -38,8 +40,8 @@ npm audit --omit=dev
 npm run release:verify -- --output-dir artifacts/package
 ```
 
-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
+The latest verified package is `skein-code-cli-0.3.8.tgz`. The verifier writes
+its SHA-256 to `artifacts/package/skein-code-cli-0.3.8.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,7 +49,7 @@ 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 35-file test suite passes the full check.
+40x10 short-height case. The current 37-file test suite passes the full check.
 
 ## Recommended Order
 
@@ -75,11 +77,10 @@ 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`.
-- 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.
+- The `main` branch rule requires the strict `check` status. Version 0.3.8 adds
+  the startup context-readiness gate, branded wide welcome rail, runtime
+  completion evidence, and conservative dynamic-shell mutation tracking. Its
+  tag, GitHub verification, and npm publication use the same source commit.
 
 ### P1: Skein Storage Namespace And Migration
 

package/docs/PRODUCT.md

@@ -68,14 +68,14 @@ Sources:
 
 | Surface | Capability |
 |---|---|
-| Context | Local BM25/path/symbol index, freshness checks, token packing, multi-root, `@file` mentions |
+| Context | Local BM25/path/symbol index, visible startup build/validation gate, freshness checks, token packing, multi-root, `@file` mentions |
 | Models | OpenAI, Anthropic, Gemini, OpenAI-compatible endpoints |
-| Agent | Multi-turn tool loop, task plan, automatic verification, ask-only mode |
+| Agent | Multi-turn tool loop, task plan, evidence-gated completion, automatic verification, ask-only mode |
 | Tools | Read, list, search, write, patch, shell, Git, context search, task updates |
 | Trust | Workspace path boundary, allow/ask/deny policy, command rules, hooks, checkpoints |
 | Sessions | Local persistence, resume/latest, list/show/delete/export |
-| UX | Ink TUI, action timeline, context telemetry, plan rail, inline permission band, interruption |
-| Automation | Prompt/stdin input, queue, quiet mode, JSON and JSONL event output, exit codes |
+| UX | Ink TUI, responsive branded welcome/workspace rail, action timeline, context telemetry, plan rail, inline permission band, interruption |
+| Automation | Prompt/stdin input, queue, quiet mode, JSON and JSONL output with verified/unverified status, exit codes |
 | Operations | Init, doctor, config, index/search/context/status, checkpoint management |
 
 ## Differentiation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-code/cli",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   "type": "module",
   "license": "MIT",
@@ -16,9 +16,9 @@
   },
   "skein": {
     "releaseNotes": [
-      "Terminal startup no longer leaks Kitty keyboard probes or wraps long model names into stray rows",
-      "The fresh-session summary is denser and verified across narrow, wide, and short terminal layouts",
-      "Prompt assembly now keeps optional orchestration guidance out of simple runs and strengthens language, user-work, and verification guardrails"
+      "Startup builds or reuses the local index and validates persisted workspace content before chat",
+      "Wide fresh sessions add a factual workspace rail for model, context, permissions, tools, and extensions",
+      "Completion requires current runtime evidence and conservatively tracks dynamic shell mutations"
     ]
   },
   "bin": {