dev-flow-deepseek 0.1.0 → 0.5.2

package/skills/dev-flow/SKILL.md

@@ -1,59 +1,414 @@
----
-name: dev-flow
-description: Start or resume a governed single-repository Dev Flow lite task.
-whenToUse: Use only when the user explicitly invokes /dev-flow for substantive repository work.
-disable-model-invocation: true
-user-invocable: true
----
-
 # Dev Flow
 
-Use this Skill only after the user explicitly invokes `/dev-flow` with a
-substantive repository task. Never activate it for an ordinary coding request.
-
-Read [activation-and-routing.md](references/activation-and-routing.md) before
-discovering, selecting, starting, or applying a task.
-
-## Entry checks
-
-Before task discovery or mutation:
-
-1. Verify that all and only the required Dev Flow surface is available to this
-   Skill under these six model-facing names:
-   `mcp__dev-flow__dev_flow_server_info`,
-   `mcp__dev-flow__dev_flow_find_tasks_for_path`,
-   `mcp__dev-flow__dev_flow_get_task`,
-   `mcp__dev-flow__dev_flow_get_next_action`,
-   `mcp__dev-flow__dev_flow_start_task`, and
-   `mcp__dev-flow__dev_flow_apply_action`.
-2. Call `mcp__dev-flow__dev_flow_server_info` and parse its complete canonical
-   JSON text. Require server `dev-flow`, release `0.6.12`, model version and
-   model namespace `0.4.0`, interface `dev-flow-mcp/1.0.0`, result schema
-   `dev-flow-mcp-result/1.0.0`, transport `stdio`, and health status `ready`.
-   Stop and name the exact incompatible field when any value differs; never
-   infer compatibility from a version range.
-3. Require a substantive task after `/dev-flow`. Ask for the missing task and
-   do not create anything when the invocation is empty or conversational.
-4. Resolve the current worktree root with `git rev-parse --show-toplevel`.
-   Stop before discovery when it fails. The exact canonical result is the sole
-   repository root; reject requests that require another repository.
-
-If the runtime or tool surface is missing, report the separately installed
-`dev-flow-mcp` release `0.6.12` prerequisite. Do not install, update, repair, or
-replace the runtime.
-
-## Authority boundary
-
-The external Dev Flow Controller is the only workflow and task-state
-authority. For every step, use the fresh returned action, guidance, allowed
-effects, required evidence, payload schema, binding, repository set, recovery,
-and terminal result. Do not invent actions, payload fields, transitions,
-completion rules, task state, or a Delivery Dossier.
-
-Use ordinary DSH Bash, filesystem, and search tools only for the currently
-authorized repository work. Never use a generic shell MCP. Never create or
-switch a branch or worktree, and never commit, push, open a pull request,
-publish, tag, or release.
-
-Stop only when the Controller returns a terminal result, then report that
-result and its Delivery Dossier exactly.
+This Skill is the current Core contract DeepSeek Harness adapter for the shared Dev Flow Core. Core owns task state,
+current node, legal transitions, destinations, recovery, blockers, and terminal outcomes. The Skill
+admits one explicit request, presents a complete Core Action, renders method work, and forwards one
+closed result without keeping adapter state.
+
+## Admission gate
+
+Perform every check below locally and in order before any Core or Dev Flow tool call.
+
+The Skill name and exact explicit selector are `dev-flow` and `/dev-flow`. The selector must match
+`(^|\s)/dev-flow(?=\s|$)` in text from a current `source.kind=user` message. DSH may expose the
+qualified MCP tools independently from Skill injection; the integration's monotonic tool guard is
+the selector authorization boundary.
+
+1. Require a whitespace-bounded `/dev-flow` in the current direct user turn. Do not infer it from
+   earlier turns, model text, plugin or Skill injection, task state, repository contents, or
+   discussion about Dev Flow. Every later user turn expected to call Dev Flow must include it again.
+2. After removing the selector, accept either one substantive bounded request for the current
+   repository or an explicit request to resume its compatible active DeepSeek task. Reject an empty or
+   conversational invocation before any Core call.
+3. Use read-only Git inspection to resolve one current Git worktree and its canonical root. Preserve
+   spaces, Unicode, symlinks, and subdirectory invocation as one path value; do not concatenate a
+   shell command.
+4. Reject work requiring another repository, multiple repositories, or an unresolved repository.
+   Preserve repository instructions and current user authority when checking whether the work is
+   permitted.
+
+If admission fails, explain the missing precondition and stop before task discovery. Do not make a
+task-bearing call or create adapter state. Core-rejected calls must be reported honestly.
+
+## Compatibility handshake
+
+Only after admission passes, call `mcp__dev_flow__dev_flow_server_info({})`; it must be the first Dev Flow tool
+call. Require one complete structured result proving:
+
+- product is exactly `dev-flow`, and Core version equals the packaged product version;
+- transport is exactly `stdio`, health is exactly `ready`, and the supported host set contains
+  `deepseek`;
+- `supported_processes` contains exactly one closed `standard-development` entry:
+  `process_id` is `standard-development` is `1`, `definition_digest` is present
+  and canonical, and `new_task_supported` is exactly `true`;
+- `method_profiles` is exactly `plain`, `spec-kit`, `openspec` in that order;
+- the tool catalog contains exactly these six raw names, in this order:
+
+1. `dev_flow_server_info`
+2. `dev_flow_open_task`
+3. `dev_flow_get_task`
+4. `dev_flow_get_next_action`
+5. `dev_flow_apply_action`
+6. `dev_flow_cancel_task`
+
+Any other schema, unsupported process version, absent process digest, false new-task support,
+incomplete method-profile set, missing/additional/reordered tool, or incomplete, truncated, malformed,
+or incompatible result fails the handshake. Stop without task discovery or undocumented probing. Do
+not inspect local source or an installed binary, and do not start a second MCP server to bypass a
+failed handshake.
+
+## Task discovery
+
+After the handshake, call `mcp__dev_flow__dev_flow_open_task` with `host=deepseek` and the canonical current worktree.
+
+- For an explicit resume, omit `new_task` or send `new_task=null`. Do not resend a guessed intent or
+  select another profile; accept the immutable profile returned by Core.
+- For a new request, select one profile from explicit current user intent. An explicit `plain`,
+  `spec-kit`, or `openspec` request selects that exact profile. An explicit request to use Spec Kit
+  selects `spec-kit`; an explicit request to use OpenSpec selects `openspec`; otherwise use the
+  conservative `plain` profile.
+- Installed tooling does not select or switch a profile. Never change the profile after creation. If
+  the user explicitly requests conflicting profiles, report the profile conflict and stop.
+- Derive the new-task contract only from the admitted user request, repository instructions, known
+  initial bounds, known acceptance, and granted verification authority. Formal acceptance does not
+  need to be complete at creation; the current requirements work forms that authority.
+- Forward `new_task` with exactly the members `request`, `initial_scope`,
+  `initial_out_of_scope`, `known_acceptance_criteria`, `verification_budget`, and `method_profile`,
+  with no additional members. Forward `verification_budget` with exactly `level`,
+  `max_automatic_commands`, `allow_full_suite`, and `allow_manual_handoff`.
+- `request` is a JSON string. `initial_scope`, `initial_out_of_scope`, and
+  `known_acceptance_criteria` are JSON arrays of strings and may be empty. Never collapse an array
+  into prose. `verification_budget.level` is exactly `minimal`, `targeted`, or `full`.
+
+Use this exact `new_task` JSON shape, changing only values derived from the admitted request:
+
+<!-- new-task-example:start -->
+```json
+{
+  "request": "Return the requested field from the bounded endpoint.",
+  "initial_scope": ["Update the endpoint response"],
+  "initial_out_of_scope": ["Change unrelated endpoints"],
+  "known_acceptance_criteria": ["The response contains the requested field"],
+  "verification_budget": {
+    "level": "targeted",
+    "max_automatic_commands": 4,
+    "allow_full_suite": false,
+    "allow_manual_handoff": true
+  },
+  "method_profile": "plain"
+}
+```
+<!-- new-task-example:end -->
+
+Ask before opening only when a material request, initial-bound, verification, or profile choice
+cannot be derived without changing user intent. Let Core decide whether a compatible intent creates
+or resumes a task. Report an ownership or contract conflict unchanged in meaning and stop.
+
+## Governed action loop
+
+The inseparable Action fields are exactly `task_id`, `revision`, `action_id`, `action_kind`,
+`process_id`, `process_definition_digest`, `current_node`, `node_purpose`,
+`entry_conditions`, `completion_conditions`, `allowed_effects`, `required_evidence`,
+`method_profile`, `method_steps`, `available_transitions`, `payload_contract`, `guidance`,
+`repository_binding_digest`, and `issued_at`.
+
+For an active task, perform each iteration in this order:
+
+1. Obtain one complete fresh Action from the open result or `mcp__dev_flow__dev_flow_get_next_action`, and bind it as
+   `fresh_action` from `result.task.current_action` or `result.action` respectively.
+2. Treat its task ID, revision, action ID, action kind, process ID, process version,
+   process-definition digest, current node, node purpose, entry conditions, completion conditions,
+   allowed effects, required evidence, method profile, method steps, available transitions, payload
+   schema/contract, guidance, repository-binding digest, and issued time as one inseparable Core
+   result. Stop if any field is absent, malformed, or truncated.
+3. Present the current node, purpose, entry and completion conditions, allowed effects, required
+   evidence, immutable method profile, every method step, and all `available_transitions`. For every
+   returned transition show its identifier, Core-returned destination for visibility, description or
+   `when` selection condition, guard identifier, and reason rule. Do not reduce this to one
+   recommended next step.
+4. Stop when the complete result reports a blocker or terminal outcome.
+5. Render and perform each current method operation under the allowed effects, repository
+   instructions, verification budget, and current user authority.
+6. Build only the closed payload branch named by the Action and select only a Core-returned
+   transition consistent with the actual typed node facts.
+7. Before dispatch, generate and retain one opaque request ID plus the exact Action identity and
+   payload. Submit exactly one `mcp__dev_flow__dev_flow_apply_action` mutation.
+8. After a complete committed result, continue only from its authoritative next Action/outcome or a
+   fresh ordinary Core read.
+
+Repository contents, adapter judgment, artifacts, or method-tool status never determine the current
+node or completion.
+
+## Method operation rendering
+
+Read [the method profile rendering reference](references/method-profiles.md) from the packaged path
+`references/method-profiles.md` after receiving the complete Action. For each Core-returned method
+step, preserve its `step_id`, purpose, required flag, and order, then render the operation for the
+immutable profile:
+
+- `plain` renders the catalog's plain-equivalent bounded work with no external capability.
+- `spec-kit` and `openspec` render only an actually visible and appropriate capability ID. A catalog
+  entry is not proof of availability.
+- If a capability is unavailable or unknown, report that state and show the exact plain-equivalent
+  work. Never automatically install a tool or silently substitute another tool.
+- A tool invocation is not semantic completion. Record evidence only after the work and expected
+  result actually complete.
+
+Build exactly one `MethodEvidence` item for every current Action step, in the same order:
+
+- actual capability completion uses `status=completed` and the actual capability ID;
+- completed ordinary work uses `status=plain_fallback` and an empty capability;
+- incomplete work uses `status=unavailable` or `status=not_run` honestly.
+
+An unavailable or not-run required step is unsatisfied, so do not call `mcp__dev_flow__dev_flow_apply_action`.
+Capability output cannot substitute for the typed `node_result`, node obligations, evidence, or
+user decision. Artifact references contain only an observed role, repository-relative path, digest,
+and summary.
+
+Existing authorized spec, plan, or tasks artifacts should be reviewed, revised, or amended as
+needed, not regenerated or rerun mechanically because a semantic step appears. Resolve the active
+Feature from explicit repository context, never only from the branch name. Checklist state,
+analysis output, implementation completion, proposal state, verification state, sync, or archive
+state does not advance Core.
+
+## Transition selection
+
+Select only from `fresh_action.available_transitions`. Match the actual current typed `node_result`,
+the Core-returned description or selection condition, current `problem_class`, any explicit user
+decision, and the returned reason rule. Submit the matching transition identifier; Core validates
+the facts and owns/derives the destination.
+
+Never infer an edge from a fixed stage sequence, artifact checkbox, AI belief, profile, method-tool
+result, or capability status. A checkbox or method tool cannot advance, select, or complete Core.
+Never submit a transition absent from the fresh Action and never maintain a copied transition list.
+
+## Closed forwarding contract
+
+Use the same `fresh_action` already bound from `result.task.current_action` or `result.action`; do
+not construct another Action view.
+
+Read [the node payload construction reference](references/node-payloads.md) from the packaged path
+`references/node-payloads.md` before every ordinary apply. The reference is construction guidance;
+the fresh Action, live `mcp__dev_flow__dev_flow_apply_action` `inputSchema`, and Core remain authoritative.
+
+Before calling `mcp__dev_flow__dev_flow_apply_action`, perform this order exactly:
+
+`fresh_action.payload_contract` identifies the payload branch that must agree with the live schema
+and packaged template.
+
+1. Rebind the complete `fresh_action` and read its `action_kind`, `current_node`, `payload_contract`,
+   `method_steps`, and all `available_transitions`.
+2. Read the live `mcp__dev_flow__dev_flow_apply_action` `inputSchema`; under `allOf`, choose the `oneOf` payload
+   branch whose `action_kind.const` matches the current action kind and source node.
+3. Open the corresponding marked template in `references/node-payloads.md`.
+4. Preserve the template's complete common envelope and `node_result` wrapper; replace only dynamic
+   values with facts from the current Task, Action, user decision, repository work, and actual check.
+5. Use current baseline revisions, work-item IDs, record IDs, acceptance, and evidence sets; never
+   guess or reuse stale values.
+6. Confirm all six common payload members exist and no seventh member exists.
+7. Confirm every branch-specific required `node_result` key exists and arrays remain arrays.
+8. Confirm every ArtifactReference role belongs to the live closed enum. Never convert a
+   `required_evidence` kind such as `repository_observation` into an artifact role. Use
+   `"artifacts": []` when no real repository-relative process artifact exists.
+9. Confirm MethodEvidence exactly matches current Action steps in ID, order, and count. Completed
+   `plain` work uses `plain_fallback` with an empty capability.
+10. Confirm the selected transition is present in the fresh Action and its reason rule matches.
+11. Confirm `destination`, `next_node`, `next_cursor`, caller classification, repository facts,
+    payload digest, raw output, and unknown members are absent.
+12. Map the mutation top-level identity from that same fresh Action.
+13. Retain the exact request and call `mcp__dev_flow__dev_flow_apply_action` once.
+
+If the live schema and packaged reference disagree, stop before mutation and report the packaging
+contract defect. Do not choose whichever shape appears more convenient.
+
+Do not derive payload keys from `required_evidence`. Do not search the repository or installed
+package, inspect a binary or log, or start another MCP server to recover a schema. The selected
+payload contains exactly `transition_id`, `summary`, `reason`, `artifacts`, `method_evidence`, and
+`node_result`; put `problem_class` exactly where that node branch's actual schema requires it. Keep
+arrays as arrays and the payload as an object. Do not add unknown fields, caller classification,
+caller digest, authoritative repository facts, command/output/configuration data, `destination`,
+`next_node`, or `next_cursor`, and do not wrap the whole request in an outer `payload`.
+
+Map every mutation top-level field from the same fresh Action:
+
+- caller-generated opaque identity -> top-level `request_id`;
+- exact value `deepseek` -> top-level `host`;
+- `fresh_action.task_id` -> top-level `task_id`;
+- `fresh_action.revision` -> top-level `revision`;
+- `fresh_action.action_id` -> top-level `action_id`;
+- `fresh_action.action_kind` -> top-level `action_kind`;
+- `fresh_action.process_id` -> top-level `process_id`;
+- `fresh_action.process_definition_digest` -> top-level `process_definition_digest`;
+- `fresh_action.current_node` -> top-level `source_cursor`;
+- `fresh_action.repository_binding_digest` -> top-level `repository_binding_digest`;
+- the selected closed payload -> top-level `payload`.
+
+```text
+apply_arguments = {
+  "request_id": caller_request_id,
+  "host": "deepseek",
+  "task_id": fresh_action.task_id,
+  "revision": fresh_action.revision,
+  "action_id": fresh_action.action_id,
+  "action_kind": fresh_action.action_kind,
+  "process_id": fresh_action.process_id,
+  "process_definition_digest": fresh_action.process_definition_digest,
+  "source_cursor": fresh_action.current_node,
+  "repository_binding_digest": fresh_action.repository_binding_digest,
+  "payload": payload_for_selected_schema_branch
+}
+```
+
+`revision` remains an integer, not a string. `payload` remains an object, not a string. Do not wrap
+that request inside an outer `payload` object. For an ordinary mutation, omit `recovery_apply` or
+send `recovery_apply=null`.
+
+If Core returns `INVALID_ARGUMENT`, treat it as a complete payload-contract rejection. Stop the
+current mutation, report the failing action/payload contract without private data, and do not delete
+fields, submit a second candidate payload for the same Action, automatically retry, or treat the
+result as transport uncertainty.
+
+## Comprehension user interaction
+
+At `COMPREHENSION_REVIEW`, present a bounded explanation of current requirements, design, and major
+code paths; list unnecessary abstractions and maintenance risks; explicitly ask whether the
+developer can explain and maintain the result; and wait for an explicit user answer or verdict.
+
+A later developer response that may call a Dev Flow tool must include `/dev-flow` again in that
+current direct user turn. The earlier comprehension prompt and earlier selector do not authorize it.
+
+Use that answer and only the fresh Core transitions to form a candidate transition and matching
+typed facts. `comprehension_passed` requires explicit current user confirmation. AI must not answer,
+self-confirm, or infer that the user understands. Neither Spec Kit nor OpenSpec can own or replace
+the verdict.
+
+When the explicit verdict and fresh Core transitions identify excessive complexity, use only the
+matching Core-returned transition and current typed facts. At `REFACTOR`, perform only the current
+Action's bounded simplification and artifact reconciliation. Submit `refactor_ready_for_test` only
+when it is present in that fresh Action; after Core commits it, continue from Core's returned `TEST`
+Action and run the newly current budgeted checks before considering delivery.
+
+## SCHEMA_UNSUPPORTED
+
+When Core returns `SCHEMA_UNSUPPORTED`, explain that the selected data directory contains pre-graph
+or otherwise incompatible data and that Core did not modify or delete the old data. The user must
+act explicitly outside Core by choosing a fresh `DEV_FLOW_DATA_DIR`, manually archiving the old
+directory, manually renaming it, or manually deleting it.
+
+Stop current task discovery and do not continue open/create, automatically retry, reset, convert,
+migrate, install a migration tool, or create a substitute task. Never run delete, move, truncate, or
+reset operations for the user. Do not search for a local data directory or database path, and do not
+display, reveal, or expose a private path or location. Report only the stable error code and bounded
+guidance: never include a `HOME` value, username, result-envelope data path, raw SQLite error, or raw
+Git error. After the user completes an explicit external choice, they may invoke the exact Skill
+selector again; no background handling is promised.
+
+## Recovery-before-retry contract
+
+A mutation result is uncertain when it is missing, cancelled, malformed, truncated, or
+transport-failed instead of returning one complete structured result. Do not immediately repeat
+`mcp__dev_flow__dev_flow_apply_action` and do not infer the result from repository state or worktree contents.
+
+Before calling `mcp__dev_flow__dev_flow_apply_action`, retain the original `request_id`, `task_id`, `process_id`,
+`process_definition_digest`, `source_cursor`, `revision`, `action_id`,
+`action_kind`, `repository_binding_digest`, and exact closed `payload` from the same fresh action and
+the same apply dispatch. Never derive or reconstruct them from an incomplete response or partial
+output.
+
+When all required original identity values are retained, construct exactly this closed
+`operation_probe`:
+
+```json
+{
+  "operation_id": "<original apply request_id>",
+  "process_id": "standard-development",
+  "process_definition_digest": "<original process definition digest>",
+  "source_cursor": "<original source cursor>",
+  "expected_revision": 3,
+  "action_id": "<original action id>",
+  "action_kind": "<original action kind>",
+  "repository_binding_digest": "<original issuance binding digest>",
+  "payload": {}
+}
+```
+
+`operation_id` is the original apply `request_id`, never a read request ID.
+`expected_revision` is the original action `revision`. `repository_binding_digest` is the original
+issuance binding. `payload` is the exact original closed payload; when it was not completely
+retained, send JSON `null`. Never reconstruct it from partial output, repository text, or model
+memory.
+
+Use the original `task_id` to call `mcp__dev_flow__dev_flow_get_task` with that exact probe. A stale pre-dispatch
+Task snapshot is not an authoritative read-back. Require one complete `recovery_assessment` with the
+original graph operation identity, binding relations, operation evidence, optional committed proof,
+retry flag, `next_advice`, optional unblock condition, and observation time. Stop if it is absent,
+truncated, malformed, or refers to another operation.
+
+Then call `mcp__dev_flow__dev_flow_get_next_action` for the same task before considering any mutation.
+Compare the fresh Task and next Action's revision, action identity, current node, last operation, and
+recovery advice with the retained original identity. A missing, malformed, truncated, blocker, or
+terminal next-action result is a safe-stop, not permission to replay.
+
+DSH reconnect restores transport and tool registrations only. It never replays, retries, resumes, or
+completes a workflow mutation. After reconnect, the same `get_task` then `get_next_action` sequence
+still applies, and any later user turn that dispatches those reads must contain `/dev-flow` again.
+
+Do not implement or branch on the five-class decision table. Obey only Core's complete
+`next_advice`:
+
+- `retry_current_action`: retry the ordinary current action only when Core also returns
+  `action_retry_safe=true` and the authoritative task still exposes the exact original action;
+- `submit_recovery_apply`: submit the retained original top-level operation identity and payload,
+  adding exactly `recovery_apply={"operation_id":<original request_id>,"source_cursor":<original
+  source_cursor>}`; do not add a new recovery operation ID, destination, or classification;
+- `read_next_action`: read the authoritative next action and continue only from that result;
+- `resolve_blocker`: stop ordinary work and handle only the Core-returned current
+  `RESOLVE_BLOCKER` action;
+- `stop_for_repository_drift`: report the bounded drift condition and stop.
+
+Never infer that an unlisted action is safe. A recovery read itself cannot create a blocker or adopt
+work. Only a Core-requested explicit recovery apply may do so, and its result becomes the next
+authority.
+
+If any required identity is missing or incomplete, do not construct or send an `operation_probe`;
+send no fabricated or half probe. Do not fill missing values from a partial response, do not assume
+`not_started`, and do not automatically retry. Stop and report that the Skill cannot prove the
+mutation state.
+
+Do not branch, decide, or interpret any recovery classification and do not guess from repository
+state. Core owns classification, effect proof, blocker eligibility, and mutation directives.
+
+A complete structured `ok=false` result is an authoritative domain error, not transport
+uncertainty. Never convert or treat that domain error as missing or transport failure. Obey Core's
+`code`, `message`, `recovery.retry_safe`, `recovery.action`, and `recovery.message`. When it reports
+`retry_safe=false` and `action=none`, stop; do not call `mcp__dev_flow__dev_flow_get_next_action` or
+`mcp__dev_flow__dev_flow_apply_action`.
+
+## Evidence and verification budget
+
+- Count verification commands exactly against Core's immutable budget.
+- Do not run a prohibited full suite. When automatic capacity is exhausted, report the remaining
+  permitted work as manual handoff without claiming it ran.
+- Preserve repository instructions and explicit user authority.
+- Keep static inspection, simulated Core execution, user-performed evidence, and native automated
+  evidence distinctly labelled.
+- Submit actual sources and outcomes. Never relabel failed, skipped, or unavailable work as passed.
+
+## Blocked and terminal behavior
+
+Stop repository work when Core returns authoritative `BLOCKED`, `DONE`, `CANCELLED`, an ownership or
+contract conflict, or another safe-stop. Report Core's blocker and condition, terminal outcome,
+evidence summary, cancellation, or conflict without replacing or merging a task. Use
+`mcp__dev_flow__dev_flow_cancel_task` only after explicit user authority and a fresh current Core identity.
+
+Adapter belief that work is complete does not override Core, and a blocker is not success.
+
+## Presentation contract
+
+Use complete structured Core results for every decision. A concise user summary still preserves task
+identity, revision, current node, whether a mutation committed, method capability/fallback status,
+verification evidence and limits, every blocker or recovery condition, and the terminal outcome.
+Never request or display private database locations.
+
+Treat a truncated preview as uncertainty and follow the recovery-before-retry contract. Never fill
+missing data from a local catalog or discard outcome-bearing fields.

package/skills/dev-flow/references/method-profiles.md

@@ -0,0 +1,153 @@
+# Host Method Profile Rendering Reference
+
+This is the closed Host-rendering reference for current Core contract semantic method steps. Read it only
+after Core returns a complete current Action. It explains how the Host may perform the work; it
+is not a process definition or a second task cursor.
+
+## Authority boundary
+
+Core owns task and process identity, the current node and Action, node obligations, semantic step
+IDs and order, legal transitions and guards, problem-class validation, destination, evidence
+validity, recovery, blockers, and terminal outcome. The Adapter owns capability visibility checks,
+rendered instructions, expected artifact descriptions, plain-equivalent work, and honest bounded
+method evidence.
+
+The Adapter must not derive or select a transition or destination outside the complete current
+Action. A command result, artifact checkbox, proposal status, verification status, or archive status
+does not advance or mutate Core. Only a valid Core apply using one returned transition can do that.
+The Adapter keeps no independent current node, baseline, profile cursor, or completion state.
+
+## Profiles and rendered operation
+
+The immutable task profile is exactly one of `plain`, `spec-kit`, or `openspec`. `plain` uses no
+external method capability. The other profiles map only capabilities actually visible in the
+current Host; listing a capability here does not prove that it is installed.
+
+Present each Core-returned step with this closed shape:
+
+<!-- rendered-operation-example:start -->
+```json
+{
+  "step_id": "requirements.clarify",
+  "purpose": "Resolve material requirement ambiguity.",
+  "required": true,
+  "profile": "spec-kit",
+  "capability_id": "speckit-clarify",
+  "rendered_instruction": "Use the installed Spec Kit clarify capability for the active feature.",
+  "expected_artifacts": ["active feature specification clarification"],
+  "availability": "available"
+}
+```
+<!-- rendered-operation-example:end -->
+
+`availability` is closed and ordered as:
+
+```text
+available
+unavailable
+not_applicable
+unknown
+```
+
+This shape is presentation and admission guidance only. It is never persisted as Core task state.
+
+## Semantic step rendering catalog
+
+Capability cells name preferred stable capability IDs. A slash-command spelling is not part of the
+contract. “Direct” means the profile has no mandatory external capability for that step; render
+`not_applicable` and perform the listed plain-equivalent work. Conditional capabilities are rendered
+only when actually visible and appropriate to the current authorized artifacts.
+
+<!-- semantic-step-table:start -->
+| Step ID | Developer-readable purpose | Plain-equivalent work | Spec Kit capability guidance | OpenSpec capability guidance | Expected artifacts or result |
+| --- | --- | --- | --- | --- | --- |
+| `requirements.capture` | Capture a bounded goal, scope, exclusions, acceptance criteria, constraints, and assumptions. | Write or revise those bounded requirements. | `speckit-specify` only when no prepared feature exists; otherwise review and revise the current specification. | Use visible `openspec-explore` when intent is unclear, then visible `openspec-propose` when a proposal is needed. | Current requirements specification or proposal/delta specification. |
+| `requirements.clarify` | Resolve material requirement questions with the developer. | Ask only material questions and record the answers. | `speckit-clarify`. | Direct proposal/specification revision; visible `openspec-explore` may support exploration. | Recorded material clarifications. |
+| `requirements.validate` | Verify that requirements are observable, bounded, and free of material ambiguity. | Review acceptance and confirm that no material question remains. | `speckit-checklist` or direct checklist review. | `openspec-validate` plus human review. | Requirements-quality review or structurally valid current change. |
+| `design.choose_approach` | Select the simplest viable approach for the current requirements. | Choose a direct bounded design. | `speckit-plan`. | Revise the proposal/design through visible `openspec-propose`. | Current design artifact. |
+| `design.review_complexity` | Identify unnecessary abstractions and justify retained complexity. | Review the design and justify every retained abstraction. | `speckit-plan` plus direct design review. | Direct review; visible `openspec-explore` may support comparison. | Complexity rationale and rejected alternatives. |
+| `design.record_decisions` | Record components, decisions, rejected alternatives, and risks. | Record the current decisions and affected components. | `speckit-plan` artifact updates. | Update the proposal/design through visible `openspec-propose`. | Current decisions, risks, and design references. |
+| `tasks.decompose` | Decompose the current design into bounded, ordered work items. | Create bounded items with dependencies and expected paths. | `speckit-tasks`. | Revise proposal task artifacts through visible `openspec-propose`. | Current bounded task plan. |
+| `tasks.map_acceptance` | Map every current acceptance criterion to work and verification. | Record acceptance-to-work and verification traceability. | `speckit-tasks`. | Review delta specifications and tasks through visible `openspec-propose`. | Acceptance traceability. |
+| `tasks.analyze_consistency` | Check requirements, design, and tasks for gaps or contradictions. | Perform a direct cross-artifact consistency review. | `speckit-analyze`. | `openspec-validate` plus direct consistency review. | No unresolved blocking consistency gap, or exact findings. |
+| `implementation.execute_plan` | Execute only the work authorized by the current task plan. | Implement the current authorized slice. | `speckit-implement`. | `openspec-apply`. | Implemented current work slice. |
+| `implementation.record_surface` | Record exact changed paths or the no-change state and deviations. | Observe and record the exact changed surface. | Direct implementation result; no mandatory capability. | Direct apply result; no mandatory capability. | Changed paths or explicit no-change result. |
+| `implementation.classify_deviations` | Classify deviations as requirement, design, or complexity concerns. | Record the exact concern and route it through Core facts. | Direct classification; amend active artifacts before continuing when semantics change. | Direct classification and current change-artifact update. | Exact deviations and findings. |
+| `test.run_budgeted_checks` | Run only verification authorized by the current verification budget. | Run the current bounded verification steps. | Direct plan-defined checks; no mandatory Spec Kit capability. | Use `openspec-verify` only when visible; otherwise run plan-defined checks. | Actual current verification result. |
+| `test.record_evidence` | Record actual evidence sources, outcomes, and unverified or manual items. | Record actual sources and statuses without relabeling. | Direct evidence recording; no mandatory capability. | Direct evidence recording; no mandatory capability. | Current bounded evidence summary. |
+| `test.classify_failure` | Classify failures as implementation, design, or requirement problems. | Classify current failures from observed facts. | Direct classification; no mandatory capability. | Direct classification; no mandatory capability. | Exact failure class and findings. |
+| `comprehension.explain` | Explain current behavior, design, and code paths in developer-readable terms. | Present a bounded explanation to the developer. | Direct review; no Spec Kit command owns the verdict. | Direct review; no OpenSpec command owns the verdict. | Developer-readable explanation. |
+| `comprehension.identify_complexity` | Identify unnecessary abstractions and maintenance risks. | List concrete complexity and maintenance concerns. | Direct review; no mandatory capability. | Direct review; no mandatory capability. | Exact abstraction and risk findings. |
+| `comprehension.obtain_user_verdict` | Obtain the developer's explicit understanding or remediation verdict. | Ask the developer and wait for an explicit answer. | Direct user interaction; no Spec Kit capability can answer. | Direct user interaction; no OpenSpec capability can answer. | Explicit current user verdict. |
+| `refactor.simplify` | Remove unnecessary complexity within the approved behavior boundary. | Perform the bounded simplification. | `speckit-implement` only after affected artifacts and tasks are current. | Update change artifacts as needed, then use visible `openspec-apply`. | Bounded simplification. |
+| `refactor.reconcile_artifacts` | Reconcile affected process artifacts with the simplification. | Amend only artifacts affected by the simplification. | Use visible `speckit-clarify`, `speckit-plan`, `speckit-tasks`, or `speckit-analyze` only as needed. | Revise proposal/design/spec/task artifacts through visible `openspec-propose` as needed. | Current affected artifacts. |
+| `refactor.record_surface` | Record exact simplifications and the changed surface. | Record simplifications and exact changed paths. | Direct refactor result; no mandatory capability. | Direct apply result; no mandatory capability. | Refactor summary and changed surface. |
+| `delivery.reconcile_acceptance` | Map the latest acceptance criteria to current test and comprehension evidence. | Reconcile every current criterion with current evidence. | `speckit-analyze` or direct final consistency review. | Use visible `openspec-verify` and/or `openspec-validate` as appropriate. | Current acceptance/evidence mapping. |
+| `delivery.reconcile_method_artifacts` | Reconcile method artifacts with delivered behavior. | Ensure current process artifacts describe the delivered behavior. | Direct status reconciliation; `speckit-converge` may be used only when available and appropriate. | Use visible `openspec-sync` and/or `openspec-archive` only when appropriate. | Current reconciled or archived change artifacts. |
+| `delivery.prepare_summary` | Prepare a bounded delivery summary and remaining risks. | Write the final bounded summary and risks. | Direct summary; no mandatory capability. | Direct summary; no mandatory capability. | Delivery summary and remaining risks. |
+<!-- semantic-step-table:end -->
+
+The recognized Spec Kit capability IDs are `speckit-specify`, `speckit-clarify`, `speckit-plan`,
+`speckit-checklist`, `speckit-tasks`, `speckit-analyze`, and `speckit-implement`.
+`speckit-converge` is an optional repository capability and is never a Core required step.
+
+The recognized OpenSpec capability IDs are `openspec-explore`, `openspec-propose`, `openspec-apply`,
+`openspec-verify`, `openspec-sync`, `openspec-archive`, and `openspec-validate`. Some integrations do
+not expose verify, sync, or archive. Render only a capability actually visible to the Host. The
+presence of an ID in this reference does not prove installation, and OpenSpec installation or
+initialization is never automatic Core behavior.
+
+## Availability and fallback
+
+For each step returned by Core:
+
+1. Check only the Host's actual capability surface.
+2. When the preferred capability is visible and appropriate, render its exact ID and expected result.
+3. When visibility is absent or cannot be confirmed, report `unavailable` or `unknown` honestly.
+4. Always show the catalog's plain-equivalent work.
+5. Do not automatically install a tool, silently run another tool, or treat invocation as completion.
+6. Record completion only after the semantic work actually completes.
+
+For `plain`, render external capability availability as `not_applicable`. When the ordinary work
+actually completes, evidence uses `status="plain_fallback"` and an empty `capability`; plain work is
+never labeled as an external capability completion. The same `plain_fallback` rule applies when a
+selected external capability is unavailable but the equivalent work actually completes.
+
+When equivalent work remains incomplete, record `unavailable` or `not_run` honestly. Neither status
+can satisfy a required semantic step, so the Adapter must not call apply for that Action.
+
+## MethodEvidence
+
+A normal mutation supplies exactly one `MethodEvidence` item for every current Action method step,
+in Action order. Each item contains only `step_id`, `status`, `capability`, and `summary`.
+
+- `completed` requires the non-empty ID of the actual capability that completed the work.
+- `plain_fallback` requires an empty `capability` and completed plain-equivalent work.
+- `unavailable` and `not_run` do not satisfy a required step.
+- Unknown, duplicate, previous-node, reordered, or omitted steps are invalid.
+- Capability output cannot substitute for the typed `node_result` or any current Core evidence gate.
+
+## Artifact references
+
+Submit artifact evidence only as `role`, repository-relative `path`, `digest`, and `summary`. Refer
+only to a file actually observed by the Host. Never submit full contents, command output, prompts,
+token data, runtime configuration, or private locations. An artifact digest does not replace the
+repository binding. File existence, checkboxes, validation, sync, or archive status never advances
+Core by itself.
+
+For Spec Kit, determine the exact active Feature from explicit repository context. Never infer it
+only from the branch name. Existing specification, design, and task artifacts should be reviewed and
+amended intentionally; step names do not require rerunning specify, plan, or tasks. Checklist marks
+are reviewer evidence, not implementation progress. Analyze findings become typed node facts, and
+implement work produces repository changes, but neither selects a Core transition.
+
+For OpenSpec, propose, apply, verify, sync, and archive results remain method evidence only. Archive
+cannot replace DELIVERY acceptance, current test, comprehension, or evidence gates.
+
+## Comprehension verdict
+
+All profiles present a bounded requirements/design/code-path explanation, list unnecessary
+abstractions and maintenance risks, ask whether the developer can explain and maintain the result,
+and wait for an explicit user verdict. No AI statement or Spec Kit/OpenSpec capability may provide
+that confirmation. The Adapter then considers only the matching transition that Core returned; Core
+still validates the typed result and derives the destination.