scriveno 2.0.6 → 2.0.8

package/docs/auto-invoke-policy.md

@@ -0,0 +1,103 @@
+# Auto-Invoke Policy
+
+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.
+
+## Cross-Platform Agent Rules
+
+Scriveno agent prompts live in `agents/*.md`. Each host runtime exposes them differently:
+
+- Claude Code installs command files in `~/.claude/commands/` and agent prompts in `~/.claude/agents/`.
+- 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`.
+
+Every automatic path must make the distinction visible.
+
+```text
+Agent status:
+Trigger: <command or state condition>
+Spawned agents:
+- <agent-name>: <count, none, or prompt-run fallback used>
+Local operations:
+- <operation>: <result>
+Auto-invoked:
+- <command or helper>: yes/no
+Why: <one sentence tied to disk state>
+```
+
+Use `Automation status:` for command chains and `Sync status:` for runtime install or sync checks.
+
+## Levels
+
+| Level | Behavior | Default | Examples |
+|-------|----------|---------|----------|
+| 1 | Read-only suggestion | Run by default | `/scr:next` route, progress sweep, review queue surfacing |
+| 2 | Safe local helper | Run when directly triggered | `CONTEXT.md` regeneration, `HISTORY.log` append, scan report, stats count |
+| 3 | Scoped agent | Spawn when the command implies it or evidence is bounded | drafter, plan-checker, voice-checker, continuity-checker, translator, beta-reader |
+| 4 | Writer-owned action | Require confirmation | publishing, destructive edits, merge decisions, accepting review findings |
+
+## Level 1: Auto-Suggest
+
+Run these read-only checks in `/scr:next`, `/scr:progress`, and closeouts for major commands:
+
+- 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 editor notes or track proposals exist, suggest `/scr:editor-review --notes`, `/scr:editor-review --respond`, or `/scr:track`.
+- If translation folders exist or config lists target languages, suggest translation follow-ups.
+- 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`.
+
+These checks must not mutate files.
+
+## Level 2: Auto-Run Local Helpers
+
+Run these only when the current command directly owns the file operation:
+
+- `/scr:save` regenerates `.manuscript/CONTEXT.md`, appends `HISTORY.log`, and commits `.manuscript/`.
+- `/scr:scan --fix` applies deterministic state repairs after confirmation and appends `HISTORY.log`.
+- `/scr:resume-work` may regenerate `CONTEXT.md` from disk state.
+- `/scr:progress` may count drafts, submitted units, open record threads, and stale reports, but does not write.
+- Runtime `/scr:sync --apply` runs the installer and verifies installed command, skill, and agent surfaces.
+
+Report these as local operations, not spawned agents.
+
+## Level 3: Auto-Spawn Scoped Agents
+
+Spawn or prompt-run fallback is appropriate when the command already implies a specialist role:
+
+- `/scr:plan` invokes `plan-checker` per plan.
+- `/scr:draft` invokes `drafter` per atomic unit and a voice diagnostic pass when a draft was produced.
+- `/scr:voice-check` invokes `voice-checker`.
+- `/scr:continuity-check` invokes `continuity-checker`.
+- `/scr:translate` invokes `translator` per unit.
+- `/scr:beta-reader` invokes a beta reader persona.
+- `/scr:map-manuscript` invokes analysis workers, or isolated sequential analysis if parallel workers are unavailable.
+- `/scr:editor-review` invokes revision diagnostics only for flagged issue groups.
+
+Do not pretend command-local analysis workers are installed agent files unless they actually are.
+
+## Level 4: Manual Only
+
+Never auto-run these without explicit writer confirmation:
+
+- deleting or removing units
+- accepting, rejecting, or applying editor decisions
+- merging revision tracks
+- clearing review findings
+- final publish or submission packaging
+- overwriting generated export packages
+- destructive repair, reset, revert, or cleanup
+- broad translation or cultural adaptation chains outside autopilot
+
+## Required Closeout
+
+Every proactive command should end with:
+
+- one recommended next command
+- a short reason tied to disk state
+- status showing whether agents spawned, local operations ran, or manual boundaries stopped automation

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.6",
+  "scriveno_version": "2.0.8",
   "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.
+
 ## 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.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
+
+- Codex installs now generate agent metadata beside Scriveno agent prompts so native agent spawning can work when the host exposes those roles.
+- Non-Codex runtimes keep their own install surfaces: Claude Code flat commands and agents, command-directory runtimes, skill-file runtimes, Manus, guided Perplexity Desktop setup, and the generic fallback.
+- Scriveno now has a shared auto-invoke policy for read-only suggestions, deterministic local helpers, scoped agent spawns, and manual-only writer actions.
+- `/scr:next` and `/scr:progress` now do read-only proactive checks and explain what they found.
+- `/scr:save`, `/scr:scan`, `/scr:health`, `/scr:session-report`, `/scr:sync`, and multi-agent workflows now show visible status blocks that say what spawned, what ran locally, and why.
+- Package and shipped metadata are aligned on `2.0.7`.
+
+### Why it matters
+
+Writers and developers should not have to guess whether Scriveno used a native agent, a prompt fallback, or a local file operation. This release makes those paths visible and keeps runtime behavior honest across Codex, Claude Code, and the other supported install targets.
+
+The practical effect is calmer automation: Scriveno can be more proactive about the next safe move, while still keeping writer-owned actions like publishing, destructive edits, merges, and submissions behind explicit approval.
+
+### Affected areas
+
+- Codex agent metadata generation
+- Claude Code and other runtime install verification
+- proactive command guidance
+- local helper visibility
+- `/scr:sync` status reporting
+- README, changelog, release notes, and version metadata
+- regression tests for agent spawning, prompt fallback, and runtime install surfaces
+
+### Verification
+
+- `node --test`
+- `npm run release:check`
+- `git diff --check`
+
 ## 2.0.6 - 2026-05-15
 
 ### 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
 
@@ -34,23 +36,51 @@ Node is not a runtime dependency for Scriveno's markdown command system itself.
 
 - **Registry-tested**: installer registry shape is covered by automated tests.
 - **Repo-documented**: detection and install strategy are documented in the repo.
+- **Install-surface tested**: automated tests run the installer logic for representative targets and assert command files, agent prompts, and runtime-specific metadata or manifests are written in the expected place.
 - **No host-runtime parity verification yet**: Scriveno does not currently ship an end-to-end verification artifact for behavior inside the host runtime.
 
 ## Runtime Compatibility Matrix
 
 | Runtime | Install Type | Install Path Shape | Repo Evidence | Support Level | Verification Status |
 |---------|--------------|--------------------|---------------|---------------|---------------------|
-| Claude Code | commands | `~/.claude/commands/scr-*.md` + `~/.claude/agents` or `.claude/commands/scr-*.md` + `.claude/agents` | Installer registry, registry-tested, repo-documented | Primary reference runtime | Registry-tested; repo-documented; no host-runtime parity verification yet |
-| Cursor | commands | `~/.cursor/commands/scr` + `~/.cursor/agents` or `.cursor/commands/scr` + `.cursor/agents` | Installer registry, registry-tested, repo-documented | Standard installer target | Registry-tested; repo-documented; no host-runtime parity verification yet |
-| Gemini CLI | commands | `~/.gemini/commands/scr` + `~/.gemini/agents` or `.gemini/commands/scr` + `.gemini/agents` | Installer registry, registry-tested, repo-documented | Standard installer target | Registry-tested; repo-documented; no host-runtime parity verification yet |
-| Codex | skills | `~/.codex/skills/scr-*` or `.codex/skills/scr-*` (with mirrored command files in `~/.codex/commands/scr` or `.codex/commands/scr`) | Installer registry, registry-tested, repo-documented | Skills installer target | Registry-tested; repo-documented; no host-runtime parity verification yet |
-| OpenCode | commands | `~/.config/opencode/commands/scr` + `~/.config/opencode/agents` or `.config/opencode/commands/scr` + `.config/opencode/agents` | Installer registry, registry-tested, repo-documented | Standard installer target | Registry-tested; repo-documented; no host-runtime parity verification yet |
-| GitHub Copilot | commands | `~/.github/commands/scr` + `~/.github/agents` or `.github/commands/scr` + `.github/agents` | Installer registry, registry-tested, repo-documented | Standard installer target | Registry-tested; repo-documented; no host-runtime parity verification yet |
-| Windsurf | commands | `~/.windsurf/commands/scr` + `~/.windsurf/agents` or `.windsurf/commands/scr` + `.windsurf/agents` | Installer registry, registry-tested, repo-documented | Standard installer target | Registry-tested; repo-documented; no host-runtime parity verification yet |
-| Antigravity | commands | `~/.gemini/antigravity/commands/scr` + `~/.gemini/antigravity/agents` or `.gemini/antigravity/commands/scr` + `.gemini/antigravity/agents` | Installer registry, registry-tested, repo-documented | Standard installer target | Registry-tested; repo-documented; no host-runtime parity verification yet |
-| Manus Desktop | skills | `~/.manus/skills/scriveno/SKILL.md` or `.manus/skills/scriveno/SKILL.md` | Installer registry, registry-tested, repo-documented | Skills installer target | Registry-tested; repo-documented; no host-runtime parity verification yet |
+| Claude Code | commands | `~/.claude/commands/scr-*.md` + `~/.claude/agents` or `.claude/commands/scr-*.md` + `.claude/agents` | Installer registry, registry-tested, install-surface tested, repo-documented | Primary reference runtime | Registry-tested; install-surface tested; repo-documented; no host-runtime parity verification yet |
+| Cursor | commands | `~/.cursor/commands/scr` + `~/.cursor/agents` or `.cursor/commands/scr` + `.cursor/agents` | Installer registry, registry-tested, install-surface tested, repo-documented | Standard installer target | Registry-tested; install-surface tested; repo-documented; no host-runtime parity verification yet |
+| Gemini CLI | commands | `~/.gemini/commands/scr` + `~/.gemini/agents` or `.gemini/commands/scr` + `.gemini/agents` | Installer registry, registry-tested, install-surface tested, repo-documented | Standard installer target | Registry-tested; install-surface tested; repo-documented; no host-runtime parity verification yet |
+| Codex | skills | `~/.codex/skills/scr-*` or `.codex/skills/scr-*` (with mirrored command files in `~/.codex/commands/scr` or `.codex/commands/scr`, plus agent prompts and `.toml` metadata in `~/.codex/agents` or `.codex/agents`) | Installer registry, registry-tested, install-surface tested, repo-documented | Skills installer target | Registry-tested; install-surface tested; repo-documented; no host-runtime parity verification yet |
+| OpenCode | commands | `~/.config/opencode/commands/scr` + `~/.config/opencode/agents` or `.config/opencode/commands/scr` + `.config/opencode/agents` | Installer registry, registry-tested, install-surface tested, repo-documented | Standard installer target | Registry-tested; install-surface tested; repo-documented; no host-runtime parity verification yet |
+| GitHub Copilot | commands | `~/.github/commands/scr` + `~/.github/agents` or `.github/commands/scr` + `.github/agents` | Installer registry, registry-tested, install-surface tested, repo-documented | Standard installer target | Registry-tested; install-surface tested; repo-documented; no host-runtime parity verification yet |
+| Windsurf | commands | `~/.windsurf/commands/scr` + `~/.windsurf/agents` or `.windsurf/commands/scr` + `.windsurf/agents` | Installer registry, registry-tested, install-surface tested, repo-documented | Standard installer target | Registry-tested; install-surface tested; repo-documented; no host-runtime parity verification yet |
+| Antigravity | commands | `~/.gemini/antigravity/commands/scr` + `~/.gemini/antigravity/agents` or `.gemini/antigravity/commands/scr` + `.gemini/antigravity/agents` | Installer registry, registry-tested, install-surface tested, repo-documented | Standard installer target | Registry-tested; install-surface tested; repo-documented; no host-runtime parity verification yet |
+| Manus Desktop | skills | `~/.manus/skills/scriveno/SKILL.md` or `.manus/skills/scriveno/SKILL.md`, with mirrored `commands/scr/` and `agents/` inside the skill bundle | Installer registry, registry-tested, install-surface tested, repo-documented | Skills installer target | Registry-tested; install-surface tested; repo-documented; no host-runtime parity verification yet |
 | Perplexity Desktop | guided-mcp | `~/.scriveno/perplexity/SETUP.md` or `.scriveno/perplexity/SETUP.md` plus Perplexity Desktop Connectors setup | Installer registry, registry-tested, guided setup assets, repo-documented | Guided desktop MCP target | Registry-tested; repo-documented; no host-runtime parity verification yet |
-| Generic (SKILL.md) | skills | `~/.scriveno/skills/SKILL.md` or `.scriveno/skills/SKILL.md` | Installer registry, registry-tested | Generic skills fallback | Registry-tested; no host-runtime parity verification yet |
+| Generic (SKILL.md) | skills | `~/.scriveno/skills/SKILL.md` or `.scriveno/skills/SKILL.md`, with mirrored `commands/scr/` and `agents/` inside the skill bundle | Installer registry, registry-tested, install-surface tested | Generic skills fallback | Registry-tested; install-surface tested; no host-runtime parity verification yet |
+
+## Agent Surface By Runtime
+
+- Claude Code installs flat command files such as `scr-sync.md` plus agent prompts in its `agents` directory. It does not receive Codex `.toml` metadata.
+- Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, and Antigravity install nested command directories plus agent prompts in their runtime-specific `agents` directory. They do not receive Codex `.toml` metadata.
+- Codex installs per-command skills, mirrored command files, agent prompts, and `.toml` metadata because Codex uses that metadata to expose agents.
+- 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, 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 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.
 
 ## What Scriveno Proves Today
 
@@ -60,6 +90,7 @@ Scriveno currently proves all of the following in-repo:
 - each target has a declared install strategy (`commands`, `skills`, or `guided-mcp`)
 - each target has expected install-path properties in the installer registry
 - the runtime registry shape is covered by automated installer tests
+- representative install surfaces are covered for Claude Code, standard command-directory runtimes, Codex, Manus Desktop, and the generic skills fallback
 - the high-level install strategies and detection rules are documented in [Architecture](architecture.md)
 
 Scriveno does not currently prove: