2.0.0 - living feature docs, documentation obligations, and a smaller core

OSpec 2.0.0 replaces generated per-change knowledge documents with a living documentation layer — human-owned feature docs with declared code: scopes, a one-row-per-feature catalogue, a section-level locator, and a documentation-obligation engine that tells the AI exactly which section each change owes — and removes the plugin system, ospec batch, and a batch of dead library surface.

Breaking changes

• Plugin system removed. The stitch and checkpoint built-ins, ospec plugins, and the third-party extension mechanism are gone. ospec update strips plugin configuration from .skillrc and managed guidance into an auditable .ospec/plugin-migration.json; .ospec/plugins/ is user data and is never touched. Older 1.x CLIs that fetch the plugin registry from this repository now receive 404.
• Archived changes no longer generate knowledge documents. Nothing is written under docs/project/changes/; archiving writes the index entry, updates docs/project/feature-catalog.md rows, and maintains an idempotent ospec:last-change traceability comment. Render any archive on demand with ospec changes show <archive>. Projects with legacy generated documents migrate with the four-phase, gated ospec docs migrate.
• feature-index.md is replaced by feature-catalog.md. The prose blocks stop being generated; the catalogue carries one row per declared feature.
• CLI surface: ospec batch (with stats/export/import) is removed, and the always-failing 1.9 tombstones ospec execute orchestrate, ospec workflow simulate, and ospec loop watch are deleted outright.
• Library surface: 25 package-root exports are removed (including BatchOperations, CachingLayer, FeatureUpdater, HookSystem, IndexRegenerator, PerformanceMonitor, SkillUpdateEngine, StatePersistence, VerificationSystem, WorkflowEngine, AgentCliRunnerService, BatchCommand, StringUtils, DateUtils and their singletons), 15 type exports leave the package root, 16 deep dist/** import paths are deleted (including the whole dist/advanced subtree), and 29 members are removed from modules that still ship — most notably TemplateEngine's eight generate*Template methods and TaskGraphExecutionService.launchAndRun/orchestrate/runReview. Importing the package as a library no longer auto-executes the CLI.
• Task graphs from before contract 1.8.6: a task without parallelizable is treated as serial, and serial-task mutual exclusion is now actually enforced — an unmarked IN_PROGRESS task defers other ready tasks (scheduling.deferred reason serial_task_running:<id>). Add parallelizable: true to genuinely independent tasks or regenerate the graph.
• Index ordering switches from locale-dependent localeCompare to fixed codepoint order: the first ospec index build after upgrading re-sorts the index once, and collaborators stop producing byte-different indexes across locales.
• Verification evidence accepts negative exit codes and records timedOut/signal/infraFailure as independent fields.

Migration

1. npm install -g @clawplays/ospec-cli@2.0.0
2. In each project: ospec update — refreshes assets, repairs legacy footprints, strips plugin configuration with an audit record, and reports legacy generated documents without touching them.
3. ospec index build — applies the one-time codepoint re-sort.
4. When ready, ospec docs migrate --plan starts the guided migration from generated documents to feature docs; nothing is deleted until phase 3 verifies every document is mapped or explicitly marked historical.

New

• Living feature docs: declare a feature section with <!-- ospec:feature <slug> code:<paths> --> inside human-owned docs; docs/project/feature-catalog.md carries one row per declared feature (slug, one line, doc#section, status, last-change archive).
• ospec docs locate --feature <slug> | --affects <path>: resolves the ONE section that describes a behavior — path, heading, and line range — through the code: declarations, longest prefix first, so an agent reads one section instead of a document.
• Documentation-obligation engine: ospec docs obligations --apply derives per-change_type obligations at planning time with the resolved path#section already filled in (a fix checks the section for the pre-fix wrong behaviour; a refactor verifies it and can record verified_unchanged via ospec docs confirm). When features: is empty, obligations fall back to resolving affects through the code: declarations. .skillrc docs_contract.mode: warn|strict decides whether an unmet required obligation warns or blocks archiving; the default is warn for this release cycle.
• ospec docs audit: read-only drift detection — lists feature sections whose code: paths changed since the archive named by their ospec:last-change comment.
• ospec changes show <archive>: renders an archived change (summary, affects, file list, verification commands, evidence links) from the index and archive directory; fuzzy name matching offers candidates.
• ospec docs migrate: four-phase migration for pre-2.0 projects — plan (inventory + draft skeletons), rewrite (AI work, the engine never writes prose), verify (refuses to proceed while any legacy document is unmapped), finalize (deletes only after printing and recording the list).
• ospec index gc: lists index entries whose archive no longer exists and cleans them on confirmation.
• Controller batch protocol: ospec loop step --batch-file settles a whole action batch in one round trip (controller round trips drop from 7 to 2 per cycle), and structured worker reports validate at completion time.
• Forward-compatible config: a .skillrc declaring a schema version this CLI does not know has its unknown workflow keys tolerated, preserved through save round-trips, and warned about once — while a known-version config still fails loud on typos.

Improved

• ospec archive --check and ospec execute status are truly read-only: they no longer take the task-graph mutation lease or rewrite state; --repair restores the old reconciling behaviour explicitly, and goal-progress coordination diagnostics are still reported read-only.
• Command output is budgeted: prose output over the cap spills the complete text to artifacts/spill/ and references it inline; machine output (--json/--brief) is never truncated — over the cap it is replaced by one valid JSON envelope with ospecOutputSpill: true.
• ospec update migrates legacy plugin configuration safely, repairs older project footprints, refreshes managed skills and archive layout, and points at ospec docs migrate when it finds legacy generated documents — it never migrates or deletes them itself.
• Serial-task scheduling is enforced correctly under concurrency, state files use compare-and-swap and atomic writes, and repeated repair findings stop instead of cycling.

Fixed

• Verification and review-evidence validation always derives from the bytes actually read — the caching layer that could return a stale PASS after a file changed mid-validation was removed entirely.
• ospec index query matches project documents, not only archived changes.
• A damaged .skillrc fails loud with recovery steps everywhere (25 call sites no longer silently fall back to the classic layout), and checklist gates handle CRLF content instead of failing open.
• --help, -h, and a leading help print help and never act: previously 11 subcommands swallowed them as positional arguments, and ospec goal help really created 18 files.
• Unreadable archives keep their index entries and warn instead of being silently dropped, and runGit no longer truncates large git evidence at 1MB.

Docs

• READMEs in all four languages present the 2.0 documentation layer; usage pages list the new docs, changes show, and index gc commands; every reference to removed features (plugin system, ospec batch, generated knowledge documents, tombstone commands) is gone from the shipped docs and protocol assets.

Upgrade

npm install -g @clawplays/ospec-cli@2.0.0
ospec update

Full Changelog: 1.9.10...2.0.0