Specgate work preparation

Preparing Work

Apply the SpecGate operating contract. This phase produces an approved implementation handoff; it never implements product code.

1. Define the contract and route

Read the request, governing repository instructions, and author-selected source documents. Show the human the exact title, description, observable acceptance criteria, and non-goals. Split work that can be accepted independently. Use an @check:<name> binding only when the human confirms that exact deterministic check.

Choose one route with the human:

• Quick work for a small change that does not need a governed source snapshot.
• Artifact-backed work when an existing spec, design, plan, verification document, or other source must be versioned and approved.

Do not create a durable record until the human approves the displayed contract.

Completion criterion: the human-approved preview contains every slice's title, scope, criteria, and non-goals, and names one route.

2A. Create quick work

Quick work is available in Local and Full mode. Persist the approved contract with explicit criteria, then read it back:

specgate work create-quick "$TITLE" --description "$DESCRIPTION" \
  --ac "$CONFIRMED_CRITERION_1" --json
specgate work show "$WORK_REF" --json
specgate work context "$WORK_REF" --json

Never derive criteria from filenames, headings, numbering, or keywords. If the persisted title, description, or ordered criteria differ from the preview, stop instead of implementing.

Completion criterion: the returned Context Pack reproduces the approved quick contract exactly. Quick work ends here; switch to specgate-work-delivery.

2B. Preview and publish an artifact

The originating framework owns source paths, names, lifecycle, and Git policy. Never relocate, copy, rename, delete, commit, or change ignore rules for source documents to fit SpecGate. Do not detect frameworks from directory names. Edit source content only when the user's preparation or readiness-repair request authorizes that edit.

SpecGate does not detect frameworks or infer roles; the agent maps each selected source explicitly.

Keep the transient manifest at .specgate/work/artifact.json. For every mapped document:

• set path to its unchanged repository-relative POSIX path;
• set its explicit governance role;
• use source_file only when the source is contained by the manifest directory;
• use an explicit absolute local file_url when the source is outside the manifest directory;
• set exactly one of content, source_file, or file_url.

Start from this minimum shape. The human selects feature_key; request_type must be new_feature, change_request, bugfix, or unknown:

{
  "feature_key": "<human-selected-key>",
  "request_type": "new_feature",
  "documents": [{
    "path": "docs/framework/spec.md",
    "role": "spec",
    "file_url": "file:///absolute/path/to/docs/framework/spec.md"
  }]
}

Do not use .. traversal or copy sources under .specgate/work. Preview the package without a server write:

specgate artifact publish --file .specgate/work/artifact.json --preview --json

For an update, set the exact base_version and compare with the selected base:

specgate artifact publish --file .specgate/work/artifact.json \
  --preview --compare "$BASE_ARTIFACT_ID" --json

Report added, removed, changed, and unchanged paths. If preview lists an omitted impact declaration, ask for the exact yes, no, or unknown answers it requires; never infer no. Resolve feature identity from an explicitly named work item or human selection rather than similarity.

Completion criterion: every selected source appears exactly once in preview under its unchanged repository-relative path and explicit role; source files and Git policy are unchanged except for authorized content edits.

Only after explicit human confirmation of that preview may the agent publish:

specgate artifact publish --file .specgate/work/artifact.json --json

Completion criterion: publication succeeded and its artifact ID and immutable version are recorded. On failure, stop; do not run readiness.

3. Complete readiness

specgate gates check "$ARTIFACT_ID" --json --summary

When dispatched_to_ide_agent.pending_task_ids is non-empty, complete every frozen task. List tasks, read each task's skill_content, judge only against that rubric, and write .specgate/work/gate-<task-id>.json:

{
  "gate": "<gate_key>",
  "gate_digest": "<task gate_digest>",
  "input_digest": "<task artifact_digest>",
  "state": "pass|warn|fail|needs_human_review|not_applicable",
  "summary": "<deciding evidence>",
  "evaluator": {"executor": "ide_agent", "name": "<agent name>"}
}

specgate gates tasks list "$ARTIFACT_ID" --json
specgate gates tasks submit-result <task-id> \
  --file .specgate/work/gate-<task-id>.json --json

tasks list already returns each task's skill_content, gate_digest, and artifact_digest; do not call tasks show for a task it listed. Copy both digests exactly — a mismatched digest leaves the gate not_run.

aggregate=not_run means work remains; it is never a pass. Stale digests require a fresh task. Readiness errors preserve the artifact and become explicit blockers.

Completion criterion: every pending task has a submitted result for its exact digests, and the final aggregate plus every remaining gap is recorded.

4. Repair without taking ownership

For an authorized content correction, publish a new version using the same path-preserving manifest, exact base_version, comparison, human-confirmed preview, and readiness loop. Ask the human about ambiguous product intent. Report out-of-scope gaps without editing their source.

Completion criterion: readiness is acceptable under the stored policy, or each remaining gap has an explicit human owner and no unauthorized source edit.

5. Obtain the human decision

Show the exact immutable snapshot and readiness evidence:

specgate artifact show "$ARTIFACT_ID" --json

Reuse the readiness rows already read in section 3; do not refetch them. Render every gate before asking, preserving each state and hint verbatim:

SpecGate readiness — <artifact-id> <version> (<aggregate>)
[<state>] <gate> — <hint>
Not yet judged: <count>

Never summarize a fail, warn, needs_human_review, or not_run gate as acceptable, and never present an aggregate without its per-gate lines.

Stop for the human decision. After the human explicitly approves and authorizes that exact snapshot, run the normal handoff with every confirmed criterion:

specgate --yes change approve "$ARTIFACT_ID" \
  --title "$TITLE" \
  --ac "$CONFIRMED_CRITERION_1" \
  --json
specgate work context "$WORK_REF" --json

Require the returned work item's lead_artifact_id to equal the approved artifact and its Context Pack to reference the governed sources. A conflicting existing work contract is a blocker, never a silent relink.

Completion criterion: either the human is reviewing the named immutable artifact, or the approved work reference and matching Context Pack are recorded; no implementation file was edited in this phase.