scriveno 2.0.8 → 2.0.10

package/docs/architecture.md

@@ -4,7 +4,7 @@ How Scriveno works under the hood -- for developers who want to understand the s
 
 ## Overview
 
-Scriveno is a pure skill system. There is no compiled code, no runtime library, no framework. AI coding agents (Claude Code, Cursor, Gemini CLI, and others) read markdown command files and follow their instructions using their built-in tools (Read, Write, Bash).
+Scriveno is a markdown-first skill system with a small Node.js support layer. AI coding agents (Claude Code, Cursor, Gemini CLI, and others) read markdown command files and follow their instructions using their built-in tools (Read, Write, Bash). Node.js handles installation, packaging, runtime synchronization, and the shared read-only status engine.
 
 The entire system is a collection of files:
 
@@ -13,7 +13,7 @@ The entire system is a collection of files:
 - **CONSTRAINTS.json** is the central registry that controls which commands are available for which work types
 - **Templates** provide starting content for new projects
 
-Nothing compiles. Nothing bundles. Changes take effect immediately because the agent reads files at runtime.
+Nothing compiles for the command layer. Changes to markdown commands take effect immediately because the agent reads files at runtime. Changes to the installer or shared status engine are tested and shipped through the npm package.
 
 ## Skill System Design
 
@@ -351,9 +351,27 @@ Codex uses a skill-native variation of this strategy. The installer generates on
 
 ### Shared status engine
 
-Scriveno also ships `lib/auto-invoke-engine.js`, exposed through `scriveno status --project .` and `scriveno status . --json`. The installer copies this library into the shared Scriveno asset directory for global and project installs, so command surfaces can call a single read-only status engine before falling back to embedded markdown logic.
+Scriveno also ships `lib/auto-invoke-engine.js`, exposed through `scriveno status --project .`, `scriveno status . --json`, `scriveno status --project . --apply-safe`, `scriveno sync --check`, `scriveno smoke`, `scriveno agents`, and `scriveno routes`. The installer copies this library into the shared Scriveno asset directory for global and project installs, so command surfaces can call a single status and audit engine before falling back to embedded markdown logic.
 
-The engine checks disk evidence only: project presence, STATE.md, CONTEXT.md freshness, review files, translation work, exports, history, and save signals. It recommends the next command, but it does not mutate files and does not spawn agents by itself. That boundary keeps proactive behavior portable across Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Antigravity, Manus, Perplexity Desktop, and the generic fallback.
+The engine checks disk evidence only: project presence, required project files, STATE.md, CONTEXT.md freshness, plan files, draft files, review coverage, unresolved notes, revision-track proposals, translation work, publishing prerequisites, exports, history, and save signals. It recommends the next command, but it does not mutate files and does not spawn agents by itself. That boundary keeps proactive behavior portable across Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Antigravity, Manus, Perplexity Desktop, and the generic fallback.
+
+The engine now reports three automation lanes:
+
+- **Candidate agents**: bounded specialist routes that may spawn when the host supports it, such as `drafter`, `voice-checker`, `continuity-checker`, `translator`, `plan-checker`, beta-reader workers, and import analysis workers.
+- **Candidate local helpers**: deterministic file or status helpers such as `/scr:save`, `/scr:scan`, `/scr:check-notes`, `/scr:progress`, `/scr:session-report`, and `/scr:sync`.
+- **Manual gates**: writer-owned routes that need explicit confirmation, including publishing packages, export overwrites, and revision-track merge or proposal decisions.
+
+Every command registry category has an automation lane through `getCommandAutomationPolicy()`. This makes route coverage testable: core routes are mixed, navigation routes are read-only, quality and review routes are agent-or-local, publishing and collaboration routes are manual-gated, utility and session routes are local-helper, and structure-management routes stay manual because they can rename or remove manuscript units.
+
+This turns disconnected side features into visible routes. A plan without a draft recommends `/scr:draft` and lists the drafter route as a candidate agent path. Drafts without reviews recommend `/scr:editor-review` before export. Notes route to `/scr:check-notes`. Revision proposals route to `/scr:editor-review --proposal` or `/scr:track`. Publishing gaps route to `/scr:front-matter`, `/scr:back-matter`, `/scr:blurb`, `/scr:cover-art`, or `/scr:publish` depending on disk evidence.
+
+The same engine now exposes:
+
+- **Safe apply reporting**: `status --apply-safe` runs read-only checks, identifies safe helpers, lists agent candidates, and marks write-gated actions as skipped.
+- **Sync check**: `sync --check` combines project status, safe apply, agent availability, and runtime smoke into one transcript.
+- **Agent availability**: `agents` verifies prompt fallback readiness for non-Codex runtimes and metadata readiness for Codex.
+- **Runtime smoke**: `smoke` checks installed command, skill, guide, agent, metadata, and shared-engine surfaces.
+- **Route graph audit**: `routes` derives a command graph from constraints, command intents, dependencies, and automation lanes.
 
 ### Installation modes
 
@@ -366,7 +384,7 @@ The user chooses during installation. Guided local-MCP targets still write their
 
 ### Runtime credibility
 
-Scriveno's installer compatibility floor is `Node.js >=20.0.0`. For new installs, prefer a currently supported LTS such as Node.js 24. The compatibility floor applies to `npx scriveno@latest`, `bin/install.js`, `scriveno status --project .`, the shared status engine, and the repo's JavaScript test suite, not to the markdown command system once files are installed.
+Scriveno's installer compatibility floor is `Node.js >=20.0.0`. For new installs, prefer a currently supported LTS such as Node.js 24. The compatibility floor applies to `npx scriveno@latest`, `bin/install.js`, `scriveno status --project .`, the proactive audit commands, the shared status engine, and the repo's JavaScript test suite, not to the markdown command system once files are installed.
 
 This architecture doc is intentionally about mechanics: detection rules, install path shapes, `commands` versus `skills` versus `guided-mcp`, and global versus project scope. For the authoritative runtime matrix, support levels, and verification status, see [`docs/runtime-support.md`](runtime-support.md).
 

package/docs/auto-invoke-policy.md

@@ -4,6 +4,26 @@ Scriveno can be proactive, but it must be proactive from disk evidence. Commands
 
 The executable policy lives in `lib/auto-invoke-engine.js` and is exposed through `scriveno status --project .`. The installer copies it to `.scriveno/lib/auto-invoke-engine.js` for project installs and `~/.scriveno/lib/auto-invoke-engine.js` for global installs, so every runtime can use the same read-only status logic.
 
+The engine reports candidates instead of silently acting. It can identify planned-but-undrafted work, drafts without review coverage, unresolved note files, revision proposals, translation follow-ups, publishing prerequisite gaps, stale exports, and stale session context. It then separates what could spawn an agent, what could run as a local helper, and what must stay behind a manual gate.
+
+The same file exports `getCommandAutomationPolicy()`, which classifies every command registry route into an automation lane. Tests assert that every command category is covered, so newly added routes cannot sit outside the proactive policy by accident.
+
+## Safe Apply and Audit Commands
+
+Scriveno now exposes the proactive layer as executable checks instead of documentation-only guidance:
+
+```bash
+scriveno status --project . --apply-safe
+scriveno sync --check
+scriveno smoke --json
+scriveno agents --json
+scriveno routes --json
+```
+
+`--apply-safe` runs the read-only status sweep, reports safe local helpers that are ready, lists agent candidates, and marks writer-owned or write-gated helpers as skipped instead of mutating files. It is intentionally conservative: `/scr:save`, `/scr:scan`, `/scr:sync --apply`, publish packaging, export overwrites, track merges, and undo remain explicit actions.
+
+`sync --check` combines four reports: project status, safe apply, agent availability, and runtime smoke. `smoke` checks installed commands, skills, prompts, Codex metadata, and the shared engine path. `agents` checks prompt fallback readiness and Codex metadata readiness. `routes` builds a route graph from `data/CONSTRAINTS.json` and the automation policy so disconnected command flows are visible in one audit.
+
 ## Cross-Platform Agent Rules
 
 Scriveno agent prompts live in `agents/*.md`. Each host runtime exposes them differently:
@@ -23,8 +43,14 @@ Agent status:
 Trigger: <command or state condition>
 Spawned agents:
 - <agent-name>: <count, none, or prompt-run fallback used>
+Candidate agents:
+- <command>: <agent names or none>
 Local operations:
 - <operation>: <result>
+Candidate local helpers:
+- <command>: <reason or none>
+Manual gates:
+- <command>: <reason or none>
 Auto-invoked:
 - <command or helper>: yes/no
 Why: <one sentence tied to disk state>
@@ -47,8 +73,12 @@ Run these read-only checks in `/scr:next`, `/scr:progress`, and closeouts for ma
 
 - If `STATE.md`, `CONTEXT.md`, `HISTORY.log`, or draft mtimes disagree, suggest `/scr:scan`.
 - If voice or continuity reports have unresolved issues, suggest `/scr:voice-check`, `/scr:continuity-check`, or `/scr:editor-review`.
+- If plan files exist with no corresponding drafts, suggest `/scr:draft` before reopening planning.
+- If drafts exist without review coverage, suggest `/scr:editor-review` before export.
 - If editor notes or track proposals exist, suggest `/scr:editor-review --notes`, `/scr:editor-review --respond`, or `/scr:track`.
+- If note files contain unresolved items, suggest `/scr:check-notes`.
 - If translation folders exist or config lists target languages, suggest translation follow-ups.
+- If front matter, back matter, blurb, or cover handoff assets are missing, surface the specific publishing prerequisite before packaging.
 - If export outputs are older than source files, suggest `/scr:export` or `/scr:publish`.
 - If no save exists after recent manuscript changes, suggest `/scr:save`.
 

package/docs/configuration.md

@@ -57,7 +57,7 @@ When a writer runs `/scr:new-work`, Scriveno creates `.manuscript/config.json`.
 
 ```json
 {
-  "scriveno_version": "2.0.8",
+  "scriveno_version": "2.0.10",
   "work_type": "<chosen>",
   "group": "<group>",
   "command_unit": "<unit>",

package/docs/getting-started.md

@@ -29,9 +29,13 @@ You can also ask Scriveno for a read-only project status from any terminal:
 ```
 scriveno status --project .
 scriveno status . --json
+scriveno status --project . --apply-safe
+scriveno sync --check
 ```
 
-That status command is the same shared auto-invoke engine used by `/scr-next`, `/scr:next`, `/scr:progress`, `/scr:session-report`, and `/scr:sync` when local command execution is available. It recommends the next safest command, but does not mutate files or spawn agents by itself.
+That status command is the same shared auto-invoke engine used by `/scr-next`, `/scr:next`, `/scr:progress`, `/scr:session-report`, and `/scr:sync` when local command execution is available. It recommends the next safest command, but does not mutate files or spawn agents by itself. Current status output separates candidate agents, candidate local helpers, and manual gates so you can tell whether Scriveno is pointing at a specialist route, a deterministic file helper, or a writer-owned decision.
+
+Use `--apply-safe` when you want Scriveno to run the read-only checks and show which helpers are safe, skipped, or agent-ready. Use `sync --check` when you want the installed runtime surfaces checked too.
 
 ## Step 2: Explore the Demo (Optional)
 

package/docs/release-notes.md

@@ -2,6 +2,73 @@
 
 This document is the public-facing summary of what changed between package releases. For package history, see the root [CHANGELOG](../CHANGELOG.md).
 
+## 2.0.10 - 2026-05-16
+
+### What changed
+
+- `scriveno status --project . --apply-safe` now runs the read-only proactive checks and reports safe helpers, agent candidates, and write-gated actions.
+- `scriveno sync --check` now produces a read-only sync transcript with project status, safe apply, agent availability, and runtime smoke.
+- `scriveno smoke`, `scriveno agents`, and `scriveno routes` expose installed-surface checks, agent prompt and metadata checks, and generated route graph audits.
+- Runtime checks cover Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Antigravity, Manus, Perplexity Desktop, and the generic skill fallback through the shared engine.
+- README badges, Runtime Support, Auto-Invoke Policy, Architecture, Getting Started, Testing, sync command docs, Route Graph Audit, changelog, and package metadata are aligned on `2.0.10`.
+
+### Why it matters
+
+The previous releases made proactive routing visible. This release makes the support tooling executable. Users can now ask Scriveno what is safe to run, whether installed agent surfaces are present, whether Codex metadata is ready, and how every route fits into the automation graph without relying on a hidden host-specific behavior.
+
+### Affected areas
+
+- shared auto-invoke engine
+- public CLI audit commands
+- runtime smoke and agent availability checks
+- route graph audit docs
+- README badges and launch copy
+- architecture, runtime support, auto-invoke policy, getting started, testing, and sync command docs
+- package metadata and generated project examples
+- regression tests for safe apply, runtime smoke, agent availability, and route graph coverage
+
+### Verification
+
+- `node --test test/auto-invoke-engine.test.js`
+- `node --test test/installer.test.js`
+- `npm test`
+- `npm run release:check`
+- `npm pack --json`
+- `git diff --check`
+
+## 2.0.9 - 2026-05-16
+
+### What changed
+
+- `scriveno status --project .` now detects connected workflow gaps instead of only broad project state.
+- The shared engine can route planned-but-undrafted work to `/scr:draft`, drafts without review coverage to `/scr:editor-review`, unresolved notes to `/scr:check-notes`, revision proposals to `/scr:editor-review --proposal`, translation work to verification follow-ups, and publishing gaps to the specific missing prerequisite.
+- Status output now separates `Candidate agents`, `Candidate local helpers`, and `Manual gates`.
+- Every command registry category now has an automation lane through `getCommandAutomationPolicy()`.
+- Markdown fallback contracts for `/scr:next`, `/scr:progress`, `/scr:session-report`, `/scr:save`, `/scr:scan`, and `/scr:health` now show the same route-intelligence shape when a host cannot call the Node engine.
+- README badges, README status copy, Architecture, Auto-Invoke Policy, Configuration, changelog, and package metadata are aligned on `2.0.9`.
+
+### Why it matters
+
+The status engine now connects previously separate flows. A writer can see whether Scriveno is recommending an agent-backed route, a deterministic local helper, or a writer-owned manual action. That makes automation more proactive without making it mysterious or pushy.
+
+### Affected areas
+
+- shared auto-invoke engine
+- public status CLI output
+- route automation policy
+- command fallback status blocks
+- README badges and launch copy
+- architecture and auto-invoke documentation
+- package metadata and generated project examples
+- regression tests for route intelligence and command policy coverage
+
+### Verification
+
+- `npm test`
+- `npm run release:check`
+- `npm pack --json`
+- `git diff --check`
+
 ## 2.0.8 - 2026-05-16
 
 ### What changed

package/docs/route-graph.md

@@ -0,0 +1,51 @@
+# Route Graph Audit
+
+Scriveno's route graph is generated from `data/CONSTRAINTS.json` and `lib/auto-invoke-engine.js`. It is not a separate hand-maintained registry.
+
+Run the audit with:
+
+```bash
+scriveno routes
+scriveno routes --json
+```
+
+The text report summarizes command count, graph edges, agent-capable routes, local-helper routes, manual-gated routes, read-only routes, and lane counts. The JSON report includes nodes and edges for host adapters, CI checks, and future visualizations.
+
+## Current Shape
+
+As of `2.0.10`, the route graph contains:
+
+- 112 commands
+- intent-order edges from `command_intents`
+- dependency-chain edges from `dependencies.core_chain`
+- automation lanes from `getCommandAutomationPolicy()`
+- route priority fixtures for high-value state transitions
+
+## Automation Lanes
+
+Each command receives one lane:
+
+- `read-only`: inspect and recommend
+- `local-helper`: deterministic local helper, visible in status
+- `agent-ready`: bounded specialist route with known agent prompts
+- `agent-or-local`: route may use a specialist or local diagnostic pass
+- `mixed`: lifecycle route whose behavior depends on project state
+- `manual-gated`: writer-owned action that must stay explicit
+
+## Priority Fixtures
+
+The engine exports priority fixtures for the flows most likely to regress:
+
+- empty workspace routes to `/scr:new-work`
+- scanned project without drafts routes to `/scr:plan`
+- planned work without drafts routes to `/scr:draft`
+- drafts without review coverage route to `/scr:editor-review`
+- revision proposals route to `/scr:editor-review --proposal`
+- translation work routes to `/scr:back-translate`
+- publishing prerequisite gaps route to the first missing packaging prerequisite
+
+These fixtures are covered by `test/auto-invoke-engine.test.js`.
+
+## Cross-Runtime Use
+
+All runtimes use the same route graph audit. Claude Code, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, and Antigravity read command files and prompt agents. Codex reads generated `$scr-*` skills plus `.toml` agent metadata. Manus and the generic fallback read bundled skill files. Perplexity Desktop receives guided local-MCP setup. The graph stays shared even when the host's native spawning behavior differs.

package/docs/runtime-support.md

@@ -11,6 +11,8 @@ Node is required for:
 - running `npx scriveno@latest`
 - executing `bin/install.js`
 - running `scriveno status --project .`
+- running `scriveno status --project . --apply-safe`
+- running `scriveno sync --check`, `scriveno smoke`, `scriveno agents`, and `scriveno routes`
 - executing the shared auto-invoke status engine at `lib/auto-invoke-engine.js`
 - running the repo's JavaScript test suite
 
@@ -71,17 +73,37 @@ Every install target receives the same read-only status engine through Scriveno'
 - project installs: `.scriveno/lib/auto-invoke-engine.js`
 - source checkouts: `lib/auto-invoke-engine.js`
 
-The engine computes proactive state from disk evidence: missing or stale context, unresolved review files, translation work, stale exports, missing history, and the recommended next command. It does not mutate manuscript files and does not spawn agents. Host commands such as `/scr:next`, `/scr:progress`, `/scr:session-report`, and `/scr:sync` should call it first when local command execution is available, then fall back to their embedded markdown logic when the host cannot run Node.
+The engine computes proactive state from disk evidence: missing or stale context, plan and draft coverage, unresolved review files, unresolved notes, revision proposals, translation work, publishing prerequisites, stale exports, missing history, and the recommended next command. It does not mutate manuscript files and does not spawn agents. Host commands such as `/scr:next`, `/scr:progress`, `/scr:session-report`, and `/scr:sync` should call it first when local command execution is available, then fall back to their embedded markdown logic when the host cannot run Node.
 
 The public CLI entrypoint is:
 
 ```bash
 scriveno status --project .
 scriveno status . --json
+scriveno status --project . --apply-safe
 ```
 
 The JSON form is intended for CI, host adapters, and future runtime smoke tests.
 
+Status output uses the same route-intelligence shape across runtimes: `Candidate agents`, `Candidate local helpers`, and `Manual gates`. That keeps Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Antigravity, Manus, Perplexity Desktop, and generic skill installs aligned even when their native spawning mechanisms differ.
+
+## Runtime Smoke and Agent Checks
+
+The package now exposes cross-runtime checks through the public CLI:
+
+```bash
+scriveno sync --check
+scriveno smoke --json
+scriveno agents --json
+scriveno routes --json
+```
+
+`scriveno smoke` checks installed command surfaces, Codex skill directories, bundled skill manifests, agent prompt counts, Codex `.toml` metadata, guided Perplexity setup assets, and the shared engine under `~/.scriveno/lib/auto-invoke-engine.js`.
+
+`scriveno agents` checks whether each runtime has the expected Scriveno agent prompts and reports the correct fallback: prompt-run fallback for Claude Code and standard command runtimes, metadata-ready for Codex when `.toml` files are present, guided setup for Perplexity Desktop, and bundled skill prompts for Manus or generic skill installs.
+
+`scriveno routes` audits the command graph and automation lanes from `data/CONSTRAINTS.json`. It is useful when adding commands because it surfaces whether a route is read-only, local-helper, agent-ready, agent-or-local, mixed, or manual-gated.
+
 ## What Scriveno Proves Today
 
 Scriveno currently proves all of the following in-repo:

package/docs/shipped-assets.md

@@ -39,6 +39,7 @@ These files ship in `templates/` and `docs/` and provide the trust trio for sess
 ## Runtime Sync Asset Shipped Today
 
 - `commands/scr/sync.md` -- local runtime-surface synchronization command. It compares and refreshes installed Scriveno commands, Codex skills, command mirrors, and agent prompts from the current source tree by delegating to `bin/install.js`.
+- `lib/auto-invoke-engine.js` -- shared project status, safe apply, runtime smoke, agent availability, and route graph audit engine used by `scriveno status`, `scriveno sync --check`, `scriveno smoke`, `scriveno agents`, and `scriveno routes`.
 
 ## Export Templates Shipped Today
 

package/docs/testing.md

@@ -136,6 +136,16 @@ For the standard release gate, prefer:
 npm run release:check
 ```
 
+When changing proactive routing, runtime install paths, or agent surfaces, also run:
+
+```bash
+scriveno status --project . --apply-safe
+scriveno sync --check
+scriveno smoke --json
+scriveno agents --json
+scriveno routes --json
+```
+
 Use those for release prep so you can inspect what would ship without mutating the registry.
 
 ## Practical workflow