create-agdf 0.14.5 → 0.20.0

package/generated/submissions/openai/agdf/meta/contracts/gate-transition.md

@@ -56,12 +56,30 @@ They must not override AGDF gates, approvals or the Runtime Contract.
 - For UR, PRD, SD, TP and QA, approval and durable artefact presence are separate requirements. A gate is not satisfied by approval text alone when its artefact is missing from `.agdf/control/` or not linked to the authoritative repository SoT.
 - Approval of one user gate permits work on the next allowed gate artefact or required internal step only. It does not permit implementation unless the approved gate is `TP` and required internal implementation prerequisites are satisfied.
 - Gates must never be skipped or inferred from urgency, tone, chat history, task wording or an instruction to "start". The next allowed action is always the next unsatisfied gate or internal mandatory step.
-- Missing control files or missing current-state fields do not forbid the agent from preparing the current allowed artefact. They forbid later-gate work and implementation. For a fresh request, the default allowed work is to draft a minimal UR in the response and request `Approval: UR`. Initialize or write `.agdf/control/` only when the user explicitly asks for durable AGDF control state, the repository already uses `.agdf/control/` as its live working state, or a deterministic CLI/CI setup path is being executed.
+- After positive Request Activation and task-target resolution, missing control files or missing
+  current-state fields do not forbid drafting the current minimal UR when the turn supplies a concrete
+  outcome. They do forbid later-gate work, implementation and every gate-approval request. Obtain
+  explicit setup or link authority, initialize or link canonical control and persist a revision-stable
+  UR first; only then may revalidation determine whether `Approval: UR` is ready. This branch is
+  unreachable for `target_unresolved` and never creates a free-standing legacy live run.
+- Brownfield Review and its route may be recorded while the UR card is ready, so that card can name the next gate; this grants nothing beyond the pending `Approval: UR`.
 - `Approval: UR` permits Brownfield Review after G-00 first. The review records its Mode/Slice Decision in the same internal operation when evidence is sufficient; the user is told that no action is required now. A separate `Mode/Slice Decision` step is fail-closed recovery for incomplete or legacy review state, not a normal user decision. UR approval never permits implementation by itself and does not preselect PRD.
 - PRD, SD and TP depth is chosen after Brownfield Review through the Mode/Slice Decision, not before existing-system impact is understood.
 - The Mode/Slice Decision must be visible before any PRD shortcut, Quick Task execution or implementation: record the decision, required next gate, scope reason and evidence in the selected canonical `RUN_STATE.md` or an equivalent linked control artefact.
 - `Approval: PRD` permits Solution Design drafting, not implementation.
+- Before presenting a PRD approval, the PRD `Approval Decisions` table must resolve every `before_prd` product, acceptance, owner and release-scope decision and name its PRD owner. Collect related missing answers in one request. `later_sd` and `later_tp` rows may remain open only with a named owner; they cannot silently carry a product decision past PRD approval. The runtime suppresses `run-present` and `run-approve` when PRD readiness is open.
+- The `criteria-chain-v1` contract keeps PRD acceptance as the sole product source: every PRD criterion has one stable `criterion_id`; SD maps every criterion exactly once to its design, source-of-truth owner, decision and compatibility/risk treatment; TP maps every criterion and SD decision to task IDs, scenario IDs, expected results and evidence. Existing gate readiness checks suppress the SD or TP presentation when a marked artefact has incomplete or inconsistent mappings. Do not create a parallel acceptance register or copy acceptance prose downstream.
+- A clarification after approval that does not change approved scope, behavior or acceptance may be attributed as run evidence without changing the approved PRD. The no-mode `run-revise --run <run_id> --revision <revision_id>` remains the early PRD-to-SD revision path before downstream artefacts are linked. It requires a revised PRD, new `run-present` and a new deliberate `Approval: PRD`.
+- Versioned approved-source revision uses the existing `source_revision.preview` then separately confirmed `source_revision.apply` owner. Proposal schema 2 and receipt schema 3 bind `policy_version: 2`, original initiating phase, concrete source statements, exact quality/source-set/result assessment and full impact/quality digests. In an active structured Run before deliberate UAT approval, UR may reopen from PRD/SD/TP/CD+Tests/QA/pending UAT; PRD from SD/TP/CD+Tests/QA/pending UAT; SD from TP/CD+Tests/QA/pending UAT; TP from CD+Tests/QA/pending UAT. The actually approved earliest changed statement determines the source, never the phase or a keyword. Unknown or conflicting upstream intent requires clarification; pure implementation defects with unchanged sources stay under the valid TP and checks. Unapproved drafts use existing authoring/update, not approved-source revision.
+- New preview binds exact target/Run/revision/UUID, reviewed proposal, source bytes, registered quality facts and impact. Unchanged verified upstream approvals remain exact; selected and transitive downstream source approvals/bindings require renewal. Affected or unknown analytical/quality fulfillment is reassessed; UR requires fresh post-UR Review/Mode and required UX. Lower-source analytical retention requires exact current writer-owned applicability and specific rationale. Archive affected reports, approvals and presentations before atomic application under existing locks/journal; affected QA report and approval lose current authority together, and pending old UAT material is superseded. Fresh applicable checks/reviews and QA precede renewed UAT. Deliberate UAT approval, done OR, completed/closed/foreign/stale/damaged or incompatible pending state prohibits this path.
+- Legacy proposal schema 1 and source receipt schemas 1/2 keep their original predicates: active structured CD+Tests before QA/UAT, or UR at SD with approved UR/PRD and linked draft SD before downstream work. Historical verification selects the original receipt policy and archived initiating state; never widen old proof retrospectively or rewrite its bytes. Unsupported new versions reject concretely. The existing early PRD reopening boundary remains unchanged.
+- Under legacy policy 1, the same explicit preview/apply owner also supports UR revision in an active structured Run at SD with exact approved UR/PRD and a linked, reviewed draft SD, before SD approval, linked TP, implementation, reviews or closeout. Its reviewed proposal binds the current UR/PRD/SD sources, marks applicable analyses for reassessment and returns the same Run to UR. Other cases remain unsupported by legacy policy 1; expanded cases require the version 2 proposal and proof. The no-mode PRD boundary is unchanged. The canonical fixed-group MCP revision facade uses the same reviewed preview/apply owner and deliberate confirmation; it grants no gate approval.
+- Source revision apply archives the exact previous sources, mappings, presentations (including pending SD cards) and Run before its atomic commit. Append-only `Source Revisions` in the sealed Run determine invalidated bindings; archive files are historical evidence only. Old files, approvals, replies and presentations never authorize renewal. Draft and record the affected sources through their current owners, present them afresh and obtain new deliberate approvals.
+- UR revision requires fresh post-UR Review/Mode and required UX. Later source revision retains only reviewed exact applicable analytical inputs; reassessment routes existing owners before dependent source authoring. Every approved-source revision clears preparation, CD+Tests and review fulfillment; retained code/tests require fresh assessment under the renewed TP. Read-only inspection never recovers. Use explicit `--inspect`/`--recover` for the exact pending operation; a replay reports its historical effect separately from current state and grants no approval.
 - `Approval: SD` permits Task/Test Plan drafting, not implementation.
+- New SD drafts from sd-definition declare sd-decisions-v1 with same-artifact Design Decisions.
+  Material before_sd decisions must be resolved with named owners before presentation/approval.
+  Legacy designs without declaration/table retain existing checks; no automatic migration.
 - `Approval: TP` permits implementation-preparation Brownfield Analysis and then CD+Tests when Brownfield evidence supports it.
 - `CD+Tests` is implementation and test status only, not a delivery signal.
 - `code-review` standardizes the mandatory `CR` step, but does not replace QA.
@@ -69,6 +87,20 @@ They must not override AGDF gates, approvals or the Runtime Contract.
 - `release-or` reports the run, but does not replace QA or produce the operative commit/PR handoff.
 - `delivery-closeout` owns the operative Git handoff text when QA/OR/UAT state allows it.
 
+## Canonical Authoring Templates
+
+Bound authoring continuations use only their supplied absolute `template_path` from the installed,
+version-matched plugin. This applies exactly to UR, PRD, SD, TP, UX Intent Definition, Brownfield
+Review, Verified Change, QA Report and OR. `RUN_STATE.md`, `AGDF_RUN.md`, `MASTER_BACKLOG.md`,
+`CONTEXT_GRAPH.md`, `SOT_REGISTRY.md` and `AGENT_QUALITY_CONTRACTS.json` remain owned by their
+existing scaffold/control writers. Repository `.agdf/control/templates/` files are derived,
+reviewable references and never a runtime fallback.
+
+UX Intent Definition and Brownfield Review consume the supplied template only at their existing
+analytical owner. Verified Change consumes it only through the existing gate-check/evaluator compact
+record owner. Missing, unsupported or unsafe plugin templates stop authoring before any repository
+mutation and require explicit plugin repair or reinstall; status and inspection remain available.
+
 
 ## Brownfield Review After G-00
 
@@ -79,6 +111,8 @@ It is the sizing and routing step that decides how much later gate discipline is
 When evidence is sufficient, persist the review and Mode/Slice selection together; do not expose a
 second routine user decision. Keep the standalone Mode/Slice step only for fail-closed recovery when
 the review record is incomplete or legacy.
+The same review records conditional Architecture Impact under `brownfield-analysis`; its evidence
+feeds the existing Mode/Slice Decision, whose structured-depth policy remains in `modes.md`.
 
 Its output is limited to:
 
@@ -123,8 +157,16 @@ Classify impact as:
 - `high`: the change spans capabilities or modes, creates competing or safety-relevant authority,
   adds high-consequence decisions or materially changes cross-surface activation and recovery.
 
+Assess the proposed user-facing behavior, not whether implementation code has already changed.
 `medium | high` requires `ux-intent-definition` before PRD readiness. `low` requires it when any
-mandatory PRD UX semantics remain ambiguous. `none` records the analytical decision
+mandatory PRD UX semantics remain ambiguous or approved UR scope explicitly requires a UI preview
+for UX/PRD clarification. Preserve that requested deliverable in routing evidence and set
+`ux_intent_definition_required: yes`; do not replace it with a text-only analysis or inflate impact
+merely to route it. Distinguish a required clarification preview from the actual product deliverable
+and from optional illustrative aids. A missing preview does not require UR creation to be repeated.
+Preserve an explicitly requested before-PRD review in the Mode/Slice Decision; compact routes must
+not bypass that agreed review sequence. Use the existing proportional modes, not a new preview mode.
+`none` records the analytical decision
 `not_applicable`. The skill is an internal, non-authorizing step: it adds no gate, approval value or
 implementation permission. A required `blocked` result keeps PRD readiness closed.
 
@@ -135,6 +177,7 @@ This table is the canonical transition model. Skills may reference it, but must
 
 | State | Current gate or step | Allowed | Forbidden | Missing approval |
 |---|---|---|---|---|
+| Positive delivery intake has one resolved target, but canonical control is absent or incomplete | `Control setup` | draft the minimal UR, obtain explicit setup or link authority, initialize or link canonical control and persist the revision-stable UR | gate approval requests, live legacy run creation, PRD, SD, TP, Brownfield Analysis, implementation, QA, release | none |
 | No approved UR | `UR` | clarify user need, formulate and persist UR, request `Approval: UR` | PRD, SD, TP, Brownfield Analysis, implementation, QA, release | `Approval: UR` |
 | `UR` approved and UR artefact persisted or linked, Brownfield Review missing | `Brownfield Review` | classify workstream, existing owners, SoT, reuse risks, change size and PRD/SD open questions; mark review done or not_applicable | PRD, SD, TP, implementation, QA, release | none |
 | Brownfield Review done or not_applicable, Mode/Slice Decision missing or incomplete | `Mode/Slice Decision` | decide `quick_task`, `verified_change`, `structured_slice`, `structured_delivery` or `block`; record scope reason, evidence and required next gate depth | PRD, SD, TP, implementation, QA, release | none |
@@ -150,8 +193,9 @@ This table is the canonical transition model. Skills may reference it, but must
 | Brownfield Analysis passed for approved TP | `CD+Tests` | implement approved TP tasks and run tests | QA pass, UAT, release | none |
 | `CD+Tests` done for approved TP, CR missing | `CR` | run mandatory Code Review and resolve blocking findings | QA pass, UAT, release | none |
 | `CR` done, QA not approved | `QA` | run QA gate, persist/refine QA report, request `Approval: QA` | UAT, release | `Approval: QA` |
-| `QA` approved but QA report missing or not pass | `QA` | persist/link QA report with `pass` decision or revise/block evidence | UAT, release | none |
-| QA approved and QA report is `pass` or `passed`, UAT not approved | `UAT` | request `Approval: UAT`, prepare non-operative delivery summary | release and automatic VCS actions | `Approval: UAT` |
+| `QA` approved but QA report missing or not pass, without a current exact deviation-acceptance receipt | `QA` | persist/link QA report with `pass` decision or revise/block evidence | UAT, release | none |
+| QA report is `revise` with an eligible explicit evidence-only deviation proposal and no QA acceptance | `QA` | present the exact scope, risks, consequences and follow-up; request contextual acceptance under quality.md | UAT, release and treating missing tests as passed | `Approval: QA` |
+| QA approved with report `pass`/`passed` or a current exact human deviation-acceptance receipt, UAT not approved | `UAT` | request `Approval: UAT`, carry accepted deviations and original QA result into the non-operative summary | release and automatic VCS actions | `Approval: UAT` |
 | UAT approved | `OR` | produce OR or delivery closeout; prepare VCS handoff only when requested | automatic commit, push, PR or release | none |