Ospec Change

Required Logic

1. Inspect repository state first when posture is unclear.
2. If the repo is not initialized, stop at initialization guidance instead of forcing a change.
3. If the request is a new requirement, derive a concise kebab-case change name and create it with ospec change <change-name> [path] (ospec new remains a compatibility alias).
4. If the matching active change already exists, continue it instead of duplicating it.
5. Keep the work inside the active change container.
6. Keep proposal.md, tasks.md, state.json, verification.md, and review.md aligned with actual execution.
7. Do not create design.md, implementation-plan.md, task graphs, worker packets, or Goal review artifacts for changes.
8. Put batch changes in the queue and execute them sequentially in a shared worktree.
9. Use OSpec closeout commands instead of inventing a parallel process.
10. The current AI performs one lightweight review.md review. APPROVED and APPROVED_WITH_CONCERNS may close automatically; PENDING, NEEDS_CHANGES, and BLOCKED stop closeout.
11. Set the proposal change_type and documentation contract. Bug fixes may record documentation_impact: none with a concrete reason. Features and docs changes require at least one real project, module, API, or user document; a legacy generated archive summary (OSpec no longer produces them) does not count. Update SKILL.md only when module rules or AI usage contracts changed. Index rebuild is automatic. At planning time run ospec docs obligations --apply: the engine derives the located documentation obligations for this change_type and writes each resolved path#section into state.json and the tasks.md checklist, so you never have to search for where to write. A refactor or perf change that genuinely changed no documented behaviour records ospec docs confirm --id <obligation-id> instead of making a cosmetic edit. A fix with no feature document gets an optional obligation and never blocks archiving.
12. Closeout is automatic when ready: once implementation, verification.md, documentation policy, and review.md are aligned and ospec verify [changes/active/<change>] passes, run ospec finalize [changes/active/<change>] yourself. Do not stop at ospec archive ... --check (it is a preview only) and do not wait for the user to ask before archiving. Closeout uses direct-closeout (archive locally, no PR) and manual merge as defaults — do NOT ask the user about PR, merge, branch, or worktree strategy; uncommitted change/OSpec files in the working tree are normal and do not block archive. Only open a PR if the user explicitly asked. Only pause closeout when a gate genuinely needs a human: a pending required user decision, real blockers reported by verify or archive, or an explicit user request to preview or approve before archiving.
13. Force archive is never automatic and is never inferred from urgency, a blocker, or a request to "finish". First report the failing gates and every NOT_VERIFIED item to the user, so their acceptance is informed. Only after they explicitly accept that incomplete work, run ospec finalize [changes/active/<change>] --force-archive --confirm-force-archive <exact-change-name> --reason "<accepted risk>"; the CLI enforces the exact-name confirmation and a non-empty reason itself. Preserve the failed and NOT_VERIFIED evidence: the archive stays incomplete and accepted-risk and must never be presented as completed behavior. Full text: for-ai/change-protocol.md.
14. Activated optional steps must appear in tasks.md and verification.md, and each one that passed must be listed in the verification.md frontmatter field passed_optional_steps — archive validates that field and blocks while an activated step is missing from it.

Commands

ospec status [path]
ospec change <change-name> [path]
ospec changes status [path]
ospec progress [changes/active/<change>]
ospec verify [changes/active/<change>]
ospec archive [changes/active/<change>] --check   # optional preview only — do not stop here
ospec finalize [changes/active/<change>]          # run automatically once verify passes and no human gate is pending
ospec finalize [changes/active/<change>] --force-archive --confirm-force-archive <exact-change-name> --reason "<accepted risk>"   # explicit user exception only, after reporting the failing gates

Guardrails

• Progress checklists track reality: tick each proposal.md acceptance criterion as it is actually verified — archiving blocks while proposal.md has unchecked items. review.md stays your one lightweight review; record its decision and complete its checklist before closeout. Never tick an item whose work was not done.
• The worktree is serial: closeout blocks on uncommitted files outside the proposal affects and documentation scopes. Declare affects honestly, and when unattributed dirty files appear (for example another session's edits), commit, stash, or isolate them instead of archiving over them.
• Do not assume dashboard workflows exist.
• Do not confuse repository initialization with change execution.
• Do not enter queue mode unless the user explicitly asks for queue behavior.
• Do not claim completion until implementation, verification notes, and closeout status are aligned.
• If real project tests exist, run or recommend them separately from ospec verify.
• Archived changes are frozen evidence: never edit anything under changes/archived/ (state.json, documents, or artifacts). Archive-time metadata is synced from the authoritative sources by the CLI; if something still looks inconsistent, report it instead of rewriting history — the knowledge index derives from the authoritative documents and self-heals its cache.