scriveno 2.0.7 → 2.0.9

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
 
@@ -349,6 +349,22 @@ Codex uses a skill-native variation of this strategy. The installer generates on
 
 **Guided local-MCP (type: `guided-mcp`).** Writes setup assets and connector recipes for runtimes that expose a documented local-MCP surface instead of a writable slash-command directory. Perplexity Desktop currently fits this model: Scriveno writes a setup guide and filesystem-server command recipe under `.scriveno/perplexity/`, and the user adds that command inside Perplexity Desktop's Connectors UI.
 
+### 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.
+
+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.
+
 ### Installation modes
 
 The installer supports two scopes:
@@ -360,7 +376,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`, 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 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

@@ -2,6 +2,12 @@
 
 Scriveno can be proactive, but it must be proactive from disk evidence. Commands should inspect `.manuscript/`, reports, timestamps, config, and installed runtime surfaces before choosing an automatic helper.
 
+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.
+
 ## Cross-Platform Agent Rules
 
 Scriveno agent prompts live in `agents/*.md`. Each host runtime exposes them differently:
@@ -10,6 +16,7 @@ Scriveno agent prompts live in `agents/*.md`. Each host runtime exposes them dif
 - Codex installs `$scr-*` skills, mirrored command files, agent prompts, and `.toml` metadata so Codex can expose agent types.
 - Cursor, Gemini CLI, OpenCode, Copilot, Windsurf, and Antigravity install nested command directories and agent prompts in their runtime-specific agent directories.
 - Manus and the generic skill runtime bundle `SKILL.md`, commands, and agents inside the skill directory.
+- All runtimes share the same installed auto-invoke engine under the Scriveno shared asset directory.
 
 When a host supports native fresh-context spawning, use the native agent or subagent mechanism. When it does not, load the installed agent prompt from the active runtime and run it in an isolated fresh context. When the action is only a file operation, report `Agent: none`.
 
@@ -20,8 +27,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>
@@ -44,8 +57,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.7",
+  "scriveno_version": "2.0.9",
   "work_type": "<chosen>",
   "group": "<group>",
   "command_unit": "<unit>",

package/docs/getting-started.md

@@ -24,6 +24,15 @@ This installs Scriveno into the runtime you choose. Command-directory and skills
 
 Once installed, Claude Code uses flat `/scr-*` commands such as `/scr-help` and `/scr-new-work`. Other command-directory runtimes currently keep `/scr:*`. Codex uses generated `$scr-*` skills such as `$scr-help` and `$scr-new-work`. Guided targets explain their supported setup path directly in the generated setup files.
 
+You can also ask Scriveno for a read-only project status from any terminal:
+
+```
+scriveno status --project .
+scriveno status . --json
+```
+
+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.
+
 ## Step 2: Explore the Demo (Optional)
 
 Not sure what Scriveno does? Try the demo before starting your own project:
@@ -181,6 +190,8 @@ $scr-next
 
 `/scr-next` reads your project state and runs the right next step automatically. A writer who only ever types `/scr-next` in Claude Code can complete an entire manuscript from start to finish.
 
+For a terminal-readable version of the same project-state reasoning, run `scriveno status --project .`.
+
 Beyond the core workflow, Scriveno offers:
 
 - **Revision** -- `/scr-editor-review`, `/scr-line-edit`, `/scr-continuity-check`
@@ -194,5 +205,6 @@ For the full command list, see [Command Reference](command-reference.md).
 If you want the trust surfaces around installation and shipping details, continue with:
 
 - [Runtime Support](runtime-support.md) -- installer targets, support levels, and verification status
+- [Auto-Invoke Policy](auto-invoke-policy.md) -- status engine, visible automation, and agent-spawn boundaries
 - [Shipped Assets](shipped-assets.md) -- what the npm package actually includes on the trust-critical surface
 - [Release Notes](release-notes.md) -- what changed in the latest package release

package/docs/release-notes.md

@@ -2,6 +2,74 @@
 
 This document is the public-facing summary of what changed between package releases. For package history, see the root [CHANGELOG](../CHANGELOG.md).
 
+## 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
+
+- Scriveno now exposes proactive project status through `scriveno status --project .` and `scriveno status . --json`.
+- A shared read-only engine at `lib/auto-invoke-engine.js` computes status from disk evidence and recommends the safest next command.
+- The installer copies the engine into Scriveno shared assets for global and project installs, so Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Antigravity, Manus, Perplexity Desktop, and the generic fallback can share the same status contract.
+- `/scr:next`, `/scr:progress`, `/scr:session-report`, and `/scr:sync` now try the public status CLI first, then fall back to source, global, or project engine paths.
+- The README now includes a status CLI badge, quick-start status command, proactive status section, and a direct Auto-Invoke Policy link.
+- Package and shipped metadata are aligned on `2.0.8`.
+
+### Why it matters
+
+The previous release made automation visible. This release makes the safest read-only part executable as a real package surface. Users and host runtimes can now ask Scriveno what the project needs next without relying on a hidden background process or a Codex-only path.
+
+The engine still does not mutate files or spawn agents by itself. It gives a consistent, inspectable status answer; command workflows decide what to run next.
+
+### Affected areas
+
+- public CLI
+- shared auto-invoke engine
+- installer shared assets
+- `/scr:next`, `/scr:progress`, `/scr:session-report`, and `/scr:sync`
+- README badges and launch copy
+- runtime support and auto-invoke documentation
+- release metadata and package contents
+- regression tests for CLI output, JSON output, install assets, and package inclusion
+
+### Verification
+
+- `node --test`
+- `npm run release:check`
+- `npm pack --dry-run --json`
+- `git diff --check`
+
 ## 2.0.7 - 2026-05-16
 
 ### What changed

package/docs/runtime-support.md

@@ -10,9 +10,11 @@ Node is required for:
 
 - running `npx scriveno@latest`
 - executing `bin/install.js`
+- running `scriveno status --project .`
+- executing the shared auto-invoke status engine at `lib/auto-invoke-engine.js`
 - running the repo's JavaScript test suite
 
-Node is not a runtime dependency for Scriveno's markdown command system itself. Once installed, Scriveno's command files, agent prompts, templates, and constraints are read by the host AI coding agent.
+Node is not a runtime dependency for Scriveno's markdown command system itself. Once installed, Scriveno's command files, agent prompts, templates, constraints, and shared auto-invoke engine are read by the host AI coding agent. Runtimes that can run local shell commands can call the engine directly; runtimes that cannot should use the same command text as a fallback contract.
 
 ## Evidence Levels
 
@@ -61,6 +63,27 @@ Node is not a runtime dependency for Scriveno's markdown command system itself.
 - Manus Desktop and the generic skills fallback install a manifest `SKILL.md`, mirrored command files, and agent prompts inside the skill bundle.
 - Perplexity Desktop receives setup assets for a local-MCP connector. It does not receive writable command or agent prompt directories from the installer.
 
+## Shared Auto-Invoke Engine
+
+Every install target receives the same read-only status engine through Scriveno's shared asset directory:
+
+- global installs: `~/.scriveno/lib/auto-invoke-engine.js`
+- 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, 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
+```
+
+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.
+
 ## What Scriveno Proves Today
 
 Scriveno currently proves all of the following in-repo: