feat(instructions): add runtime context and operation guidance

.changeset/runtime-operation-guidance.md

@@ -0,0 +1,7 @@
+---
+"@fission-ai/openspec": minor
+---
+
+Add current project context and per-operation guidance to apply and archive workflows. Projects can configure `operations.apply.guidance` and `operations.archive.guidance`; `openspec instructions apply` returns apply inputs, and the new read-only `openspec instructions archive` surface returns archive inputs for the selected root.
+
+Archive, bulk archive, and sync skills now load current archive inputs and `specs` artifact rules at execution time, fail before writes or moves when required instruction lookups fail, and reuse specs-rule snapshots during inline sync.

docs/agent-contract.md

@@ -27,7 +27,7 @@ Diagnostics appear in two positions: **status arrays** (`status: StoreDiagnostic
 
 ## 3. Root selection and `RootOutput`
 
-All root-resolving commands (`list`, `show`, `validate`, `status`, `instructions`, `instructions apply`, `new change`, `archive`, `doctor`, `context`) resolve one OpenSpec root with one precedence:
+All root-resolving commands (`list`, `show`, `validate`, `status`, `instructions`, `instructions apply`, `instructions archive`, `new change`, `archive`, `doctor`, `context`) resolve one OpenSpec root with one precedence:
 
 1. `--store <id>` → the registered store's root (`source: "store"`).
 2. Otherwise, nearest ancestor with `openspec/`: planning shape → `source: "nearest"` (a `store:` pointer is ignored with a stderr warning); config-only dir with a valid `store:` pointer → that store, `source: "declared"`.
@@ -63,24 +63,27 @@ Change: `{ "id", "title", "deltaCount", "deltas": [...], "root" }`. Spec: `{ "id
 `ReferenceIndexEntry`: `{ "store_id", "root"?, "specs"?: [{id,summary}], "fetch"?, "status": [] }` — resolved entries carry root/specs/fetch; unresolved carry store_id + warning status. Index capped at 50KB (`reference_index_truncated`).
 
 ### 4.6 `instructions apply --json`
-`{ "changeName", "changeDir", "schemaName", "contextFiles": { "<artifactId>": ["/abs", ...] }, "progress": {total,complete,remaining}, "tasks": [{id,description,done}], "state": "blocked"|"all_done"|"ready", "missingArtifacts"?, "instruction", "references"?, "root" }`.
+`{ "changeName", "changeDir", "schemaName", "contextFiles": { "<artifactId>": ["/abs", ...] }, "progress": {total,complete,remaining}, "tasks": [{id,description,done}], "state": "blocked"|"all_done"|"ready", "missingArtifacts"?, "instruction", "references"?, "context"?, "operationGuidance"?, "root" }`. Both optional fields are read from the selected root on every invocation. `context` is a required prompt-level input whose relevant project facts, conventions, and constraints must be applied; `operationGuidance` is advisory input whose entries are followed only when applicable and compatible with the built-in workflow. Both remain separate from state, tasks, progress, context files, and the built-in instruction.
 
-### 4.7 `new change <name> --json`
+### 4.7 `instructions archive --json`
+`{ "changeName", "context"?, "operationGuidance"?, "root" }`. Requires a valid `--change` in the resolved repo/store root and uses the same required-context/advisory-guidance semantics as apply. This is a read-only runtime-input surface: it does not return the static archive workflow, inspect or merge delta specs, write main specs, or move the change.
+
+### 4.8 `new change <name> --json`
 Success: `{ "change": { "id", "path", "metadataPath", "schema" }, "root" }`. Failure: `{ "change": null, "status": [d] }`, exit 1.
 
-### 4.8 `archive <name> --json`
+### 4.9 `archive <name> --json`
 Success: `{ "archive": { "change", "archivedAs": "YYYY-MM-DD-name", "path", "specsUpdated", "totals"?, "warnings"? }, "root" }`. Failure: `{ "archive": null, "root"?, "status": [d] }`, exit 1. `specsUpdated` is true only when at least one spec file was written; an already-synced change archives with all-zero totals and the skips listed in `warnings`. JSON mode is strictly non-interactive: every prompt point becomes an `archive_*` code.
 
-### 4.9 `doctor --json`
+### 4.10 `doctor --json`
 `{ "root": { "path", "source", "store_id"?, "healthy", "status": [] }, "store": { "id", "metadata": {present,valid,remote?}, "origin_url"?, "drift"?: {ahead,behind}, "status": [] } | null, "references": [...], "status": [] }`. `drift` (present only for a git-backed store checkout that has an upstream tracking ref) is ahead/behind counts against the last-fetched upstream, not the live remote. Health findings of any severity exit 0. Failure payload: `{ "root": null, "store": null, "references": [], "status": [d] }`, exit 1.
 
-### 4.10 `context --json`
+### 4.11 `context --json`
 `{ "root": { "path", "source", "store_id"?, "role": "openspec_root" }, "members": [ { "role": "referenced_store", "id", "path"?, "remote"?, "fetch"?, "status": [] } ], "status": [] }`. AVAILABLE = path present AND status empty. `--code-workspace <path>` writes `{folders:[{name,path}]}` (available referenced stores only, `ref:` prefixes); in JSON mode the write runs before printing so stdout holds exactly one document even on write failure. Failure: `{ "root": null, "members": [], "status": [d] }`, exit 1.
 
-### 4.11 `store ... --json`
+### 4.12 `store ... --json`
 setup/register: `{ "store": {id, root, metadata_path?}, "registry": {path, registered, already_registered}, "git": {is_repository, initialized, committed}, "created_files": [], "status": [] }`. unregister/remove: `{ "store", "registry": {path, removed}, "files": {deleted, deleted_path, left_on_disk}, "status": [] }`. list: `{ "stores": [{id, root}], "status": [] }`. doctor: `{ "stores": [ { id, root, metadata_path?, openspec_root: {...healthy, status}, metadata: {present, valid, id?, remote}, git: {is_repository, has_commits, has_uncommitted_changes, has_remote, origin_url}, status } ], "status": [] }` (`null` = unknown/not probed). Health findings exit 0; failures exit 1 with the matching null-shape. Prompt cancellation exits 130.
 
-### 4.12 `schemas --json` / `templates --json`
+### 4.13 `schemas --json` / `templates --json`
 `schemas`: bare array `[ {name, description, artifacts, source} ]`. `templates`: keyed object `{ "<artifactId>": {path, source} }`. Both cwd-based, no root/status keys.
 
 ## 5. Exit-code contract

docs/cli.md

@@ -727,7 +727,7 @@ openspec instructions [artifact] [options]
 
 | Argument | Required | Description |
 |----------|----------|-------------|
-| `artifact` | No | Artifact ID: `proposal`, `specs`, `design`, `tasks`, or `apply` |
+| `artifact` | No | Artifact ID, or workflow input surface: `apply` or `archive` |
 
 **Options:**
 
@@ -737,7 +737,9 @@ openspec instructions [artifact] [options]
 | `--schema <name>` | Schema override |
 | `--json` | Output as JSON |
 
-**Special case:** Use `apply` as the artifact to get task implementation instructions.
+**Special cases:** Use `apply` to get task implementation instructions. Use
+`archive` to fetch current, read-only archive inputs (`context` and
+`operationGuidance`) for a valid change; it does not archive or mutate anything.
 
 **Examples:**
 
@@ -751,6 +753,9 @@ openspec instructions design --change add-dark-mode
 # Get apply/implementation instructions
 openspec instructions apply --change add-dark-mode
 
+# Get current archive operation inputs without archiving
+openspec instructions archive --change add-dark-mode --json
+
 # JSON for agent consumption
 openspec instructions design --change add-dark-mode --json
 ```
@@ -761,6 +766,19 @@ openspec instructions design --change add-dark-mode --json
 - Project context from config
 - Content from dependency artifacts
 - Per-artifact rules from config
+- Current project context and matching operation guidance for `apply`/`archive`
+
+Operation inputs are read from the resolved repo or selected store on every
+invocation. Project context is a required prompt-level input: agents read it and
+apply relevant project facts, conventions, and constraints. Operation guidance is
+optional additive advice: agents consider every entry and follow only entries that
+are applicable and compatible with the built-in workflow. Both fields remain
+separate from explicit user choices, CLI-controlled state, built-in instructions,
+and artifact rules. Conflicting context is reported; conflicting or inapplicable
+guidance is not followed and the reason is explained. These are behavioral
+contracts for generated agents, not enforceable CLI checks. `instructions archive`
+returns only the selected change, optional inputs, and root metadata; it does not
+include the static archive workflow.
 
 For an artifact skipped via `skip_specs: true`, the output is a warning only (JSON adds `skipped`/`warning` fields) — the artifact must not be created.
 

docs/customization.md

@@ -17,6 +17,7 @@ The `openspec/config.yaml` file is the easiest way to customize OpenSpec for you
 - **Set a default schema** - Skip `--schema` on every command
 - **Inject project context** - AI sees your tech stack, conventions, etc.
 - **Add per-artifact rules** - Custom rules for specific artifacts
+- **Add per-operation guidance** - Advisory preferences for apply and archive work
 
 ### Quick Setup
 
@@ -43,6 +44,14 @@ rules:
   specs:
     - Use Given/When/Then format
     - Reference existing patterns before inventing new ones
+
+operations:
+  apply:
+    guidance:
+      - Run focused tests before the full suite
+  archive:
+    guidance:
+      - Keep the completion summary concise
 ```
 
 ### How It Works
@@ -80,6 +89,60 @@ Tech stack: TypeScript, React, Node.js, PostgreSQL
 - **Context** appears in ALL artifacts
 - **Rules** ONLY appear for the matching artifact
 
+**Operation guidance:**
+
+`operations.apply.guidance` and `operations.archive.guidance` are optional arrays
+of advisory instructions for how an agent should conduct those operations. They
+are separate from `rules`: operation guidance does not constrain artifact content,
+and artifact rules are never relabeled as operation guidance.
+
+Apply and archive fetch these inputs at execution time:
+
+```bash
+openspec instructions apply --change my-feature --json
+openspec instructions archive --change my-feature --json
+```
+
+Both surfaces return current project `context` and matching
+`operationGuidance` as separate optional fields. Each invocation reads a fresh
+snapshot from the resolved root. When `--store <id>` is selected, the change,
+context, and guidance all come from that store rather than the current repository.
+The archive instruction command is read-only: it does not inspect or merge delta
+specs, write main specs, move the change, or run the static archive workflow.
+
+Project context is a required prompt-level input. Generated workflows read it and
+apply relevant project facts, conventions, and constraints. Operation guidance is
+optional additive advice: workflows consider every entry and follow entries that
+are applicable and compatible with the built-in workflow.
+
+Both fields remain separate from CLI-controlled state, resolved paths, built-in
+steps, explicit user choices, and artifact rules. A workflow reports context
+conflicts while preserving the controlling value. It does not follow inapplicable
+or conflicting guidance and explains why. Neither field is an enforceable check,
+and workflows do not copy their text into implementation files, specs, change
+artifacts, or summaries unless the user separately requests that content.
+
+**Archive and spec-sync input safety:**
+
+Archive, bulk archive, and standalone sync use
+`artifactPaths.specs.existingOutputPaths` from `openspec status --json` as the
+only delta-spec source. A schema without a `specs` artifact, or a change whose
+concrete output list is empty, has nothing to sync; other artifacts are not used
+to infer delta specs.
+
+Before a semantic merge writes a main spec, the workflow consumes current
+`openspec instructions specs --change <name> --json` output. The returned
+`specs` rules constrain only the main specs produced by that merge. Single archive
+passes that snapshot into inline sync, standalone sync fetches it directly, and
+bulk archive obtains every required snapshot before its first spec write. A
+non-zero or invalid JSON archive/specs instruction response is a lookup failure,
+not an empty input: the workflow stops before the affected spec write or change
+move (for bulk archive, before any batch write or move).
+
+This configuration does not change archive execution phases, user prompts,
+filesystem operations, semantic merge ownership, the direct `openspec archive`
+command, or the structure and output of artifact `rules`.
+
 ### Schema Resolution Order
 
 When OpenSpec needs a schema, it checks in this order:

openspec/changes/extend-config-injection-to-apply-archive/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-22