Contracts

accept-canceled-wps.schema.json

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "accept-canceled-wps", "title": "accept --json canceled_wps field", "description": "Contract for the canceled_wps array emitted by spec-kitty accept --json (NFR-003). Accept-eligible cancellations only; non-provenance cancellations appear under blockers, not here.", "type": "object", "required": ["canceled_wps"], "properties": { "canceled_wps": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["wp_id", "reason", "actor", "at"], "properties": { "wp_id": { "type": "string", "pattern": "^WP[0-9]+$" }, "reason": { "type": "string", "minLength": 1, "description": "operator-authored note (reason_source=operator)" }, "actor": { "type": "string", "minLength": 1 }, "at": { "type": "string", "format": "date-time" } } } } } }

acceptable-ending-predicate.md

Contract — Acceptable-Ending Authority

Symbol: specify_cli.status_lanes.is_acceptable_ending(lane: str, *, has_provenance: bool) -> bool

Single authority deciding whether a work-package lane is an acceptable mission ending. Consumed by accept, merge, and the dependency-readiness gate. Replaces the three _ACCEPTED_READY_LANES definitions (acceptance/__init__.py:145, gates_core.py:52, summary_core.py:173,202).

Behavior

Input lanehas_provenanceReturns
approvedignoredTrue
doneignoredTrue
canceledTrueTrue
canceledFalseFalse
planned/claimed/in_progress/for_review/in_review/blockedignoredFalse

redefine terminality or acceptability elsewhere (C-001, directive 044).

cancellation_reason/reason_source (C-002).

  • MUST reference canonical TERMINAL_LANES only to classify canceled; MUST NOT
  • MUST be pure (no I/O). Provenance is resolved by the caller from the reduced snapshot's

Consumer obligations

report; a non-provenance canceled WP → structured blocker naming the missing provenance; all other non-terminal lanes → blockers (FR-006). Acceptance-matrix and issue-matrix verdict gates still run and can still fail (SC-005 gate-integrity).

branch only when every WP in the lane is canceled.

(dependency_graph.py:59).

  • accept: buckets each WP via the predicate; an acceptable canceled WP → canceled_wps
  • merge: excludes canceled WPs from all_wp_ids (executor.py:1660) and skips a
  • dependency gate: a canceled dependency with provenance counts as resolved

Non-fakeable tests (directive 034/036)

both driven through the canonical move-task surface (not hand-edited events).

  • Unit truth-table over all nine lanes × provenance.
  • Command-level: approved+canceled(provenance) → eligible; canceled(synthetic) → blocker,

adversarial-evidence-contract.md

Contract — Adversarial Evidence Disposition

Every contested finding from an adversarial pass (here: the post-spec squad) MUST carry an explicit disposition; none may be silently dropped.

Disposition vocabulary

  • accepted — the finding stands; captured as a constraint/note without a code change now.
  • changed — the artifact was revised to resolve the finding (spec/plan edit).
  • deferred_with_rationale — not acted on in this mission; the reason is recorded.

Record

The disposition table lives in ../research.md ("Adversarial evidence dispositions"), keyed by finding id (F1…F7 + lower-severity items), with the lens(es) that raised it. The full evidence with file:line anchors is in ../research/post-spec-squad-findings.md.

All squad findings are dispositioned there. No contested finding was silently dropped.

authoring-warning.contract.md

Contract — Authoring-Time Un-Terminable-Work Warning (FR-007/FR-008)

Advisory warning surfaced during tasks authoring/finalization when a work package's acceptance criteria can only be satisfied post-integration. Advisory only — never blocks authoring (FR-008).

Trigger

A work package matches when its acceptance-criteria / subtask text contains a phrase from the enumerable post-integration trigger set. Initial set (extensible, versioned in code):

  • "after merge" / "post-merge" / "once merged"
  • "on a branch the forge will run" / "in CI once enabled"
  • "consecutive runs" / "N consecutive"
  • "merge-blocked-when-absent"

Output

Per matched work package, a warning record: { wp_id, matched_phrase, criterion_excerpt }, rendered to the operator with guidance to re-home the content to a tracked post-merge obligations document at planning time.

Oracle (SC-003)

Validated against a fixed labeled corpus committed with the mission (tests/.../fixtures/authoring_warning_corpus/):

controls") → MUST warn (100% recall).

whose completion is observable in their own diff → MUST NOT warn (0 false positives).

  • Positive fixtures: the #3590 shapes ("enable the real system", "prove it with
  • Negative / adversarial-near-miss fixtures: work packages that mention CI/merge but

The corpus is the measurement oracle; the metric is not an open-world claim.

Non-goals

  • No structured completion_kind field (deferred to #3550, C-003).
  • No refusal / no gate. The warning cannot fail authoring.