create-agdf 0.14.5 → 0.20.0

package/generated/plugins/copilot/agdf/skills/contracts/gate-transition.md

@@ -0,0 +1,209 @@
+# AGDF Runtime Contract — Gate Transition
+
+## Source Precedence
+
+Every governed repository should make the normative instruction source visible.
+When several instruction files, generated copies, submodule rules, branch names, worktree diffs or chat summaries point in different directions, fail closed instead of inventing a primary authority.
+
+Default precedence:
+
+1. safety, security and compliance instructions
+2. repository-declared normative agent instructions
+3. live `.agdf/control/` state or a linked authoritative repository SoT
+4. approved gate artefacts
+5. source code and verified runtime evidence
+6. branch names, workspace deltas, chat history and model memory
+
+A branch name or uncommitted workspace delta is never sufficient scope proof by itself.
+It may support a scope only when it does not conflict with durable artefacts, approvals or source-of-truth records.
+
+
+## Workstate And Scope Ambiguity
+
+If a repository contains multiple plausible active work lines, the agent must not silently choose one.
+List the evidenced competing lines with their latest known gate, artefact pointers, approvals and missing evidence.
+The next permissible step is scope clarification or the earliest common safe gate.
+
+Use `multi_scope_state: clear | ambiguous | blocked` when the control state needs to make this visible.
+`ambiguous` is at least a revise condition for delivery-map style reporting.
+`blocked` applies when continuing would produce later-gate artefacts, implementation or release claims for the wrong scope.
+
+
+## Domain Guardrail Packs
+
+Repositories may define domain guardrail packs for recurring high-risk surfaces such as UI, persistence, integration, financial calculations, policy, security, migration or release operations.
+A pack should define:
+
+- trigger patterns
+- required Brownfield touchpoints
+- protected invariants
+- required evidence
+- review or QA escalation conditions
+
+Domain guardrails are project-specific extensions.
+They must not override AGDF gates, approvals or the Runtime Contract.
+
+
+## Gate Rules
+
+- User gates: `UR -> PRD -> SD -> TP -> QA -> UAT`
+- Internal mandatory steps: `Brownfield Review -> Mode/Slice Decision -> Verified Change Execution | Brownfield Analysis -> CD+Tests -> CR -> OR`
+- On the approved-TP path, `CD+Tests` and `CR` are satisfied only by `done`; `not_applicable` may satisfy Brownfield Review or Brownfield Analysis, but it must not bypass implementation/test evidence or mandatory Code Review.
+- Exact approval formula: `Approval: <GateName>`
+- Legacy alias: `Freigabe: <GateName>` may be accepted when reviewing older German runs, but all new outputs must use `Approval: <GateName>`.
+- Implicit consent is not approval. Phrases such as "ok", "go ahead", "do it", "approved", "continue", "leg los" or "looks good" are work intent, not gate approval.
+- The earliest blocking gate wins.
+- 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.
+- 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.
+- `qa-gate` decides final `pass | revise | block`.
+- `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
+
+After an approved and durable UR, perform a lightweight `Brownfield Review` before PRD when Brownfield, UI, UX, admin, runtime, policy, persistence, architecture, ownership or source-of-truth impact is possible.
+
+This review is not a new user approval gate, not PRD, not SD, not TP and not implementation permission.
+It is the sizing and routing step that decides how much later gate discipline is actually needed.
+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:
+
+- workstream or follow-up-slice classification
+- `Mode/Slice Decision`: `quick_task | verified_change | structured_slice | structured_delivery | block`
+- affected existing owners, source-of-truth artefacts, contracts, policies, runtime paths or tests
+- reuse-before-create risks and parallel-structure risks
+- open questions that PRD or SD must resolve
+- whether implementation-preparation Brownfield Analysis will also be needed after TP
+
+Mode/Slice Decision rules:
+
+- `quick_task`: use only when Brownfield Review shows a narrow local change, no new product semantics beyond the approved UR, no architecture/policy/persistence/contract expansion, and evidence is sufficient to proceed with a small implementation plus relevant checks.
+- `verified_change`: use only when the compact record can prove one canonical owner, bounded clean-at-baseline paths, no prohibited impact, deterministic propagation/validation and a structured escalation target. It skips later approvals only after every condition is evidenced and machine-validated.
+- `structured_slice` and `structured_delivery`: apply the sole normative `Structured Depth Decision`
+  in `modes.md`; this contract owns only the operational transition and does not duplicate its
+  trigger or bounded-slice matrix.
+- `block`: use when ownership, SoT, impact, evidence or product direction is not clear enough to
+  choose a safe path. A `depth_unresolved` product result is persisted through this existing value
+  with `depth_facts_missing | depth_facts_conflicting`, a Brownfield Review evidence link and a
+  precise evidence-owner/re-evaluation next action; it never creates a new mode or advances a gate.
+
+A Mode/Slice Decision without scope reason and evidence is not recorded. Treat it as missing and keep the next step at `Mode/Slice Decision`.
+
+### UI/UX Impact And UX Intent Definition
+
+The existing `brownfield-analysis` `post_ur_review` mode is the single proportional routing owner for
+both Greenfield and Brownfield delivery. It records:
+
+- `delivery_context: greenfield | brownfield`
+- `ui_ux_impact: none | low | medium | high`
+- `ui_ux_impact_reason`
+- `ux_intent_definition_required: yes | no`
+
+Classify impact as:
+
+- `none`: no user-facing capability, decision, state, feedback or recovery behavior changes;
+- `low`: a bounded user-facing change preserves unambiguous intent, working modes, effective-state,
+  activation and recovery semantics;
+- `medium`: a bounded capability materially changes its primary action, working mode, effective
+  state, visible state type, blocker, activation or recovery behavior; or
+- `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 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.
+
+
+## Gate Transition Model
+
+This table is the canonical transition model. Skills may reference it, but must not carry a second complete copy.
+
+| 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 |
+| Mode/Slice Decision is `quick_task` | `Quick Task Execution` | implement only the narrow approved UR scope, run relevant checks, record evidence and OR-lite when the run is relevant | broad PRD/SD/TP by ritual, scope expansion, QA or release claims without evidence | none |
+| Mode/Slice Decision is `verified_change`, record missing/draft/invalid | `Verified Change Execution` | create or repair compact record, capture baseline and prove eligibility with doctor/gate-check | implementation, QA, UAT, release | none |
+| Verified Change record is `eligible` | `Verified Change Execution` | implement only declared paths, run declared propagation/validation, record mini-closeout | unlisted paths, prohibited impacts, QA/UAT/release claims | none |
+| Verified Change record is `executed` | `OR` | use mini-closeout and offer delivery closeout when requested | PRD/SD/TP/QA/UAT by ritual; automatic VCS actions | none |
+| Verified Change record is `escalated` | `PRD` | draft the PRD for declared `structured_slice` or `structured_delivery` escalation target | implementation through Verified Change | `Approval: PRD` |
+| Mode/Slice Decision is `structured_slice` or `structured_delivery`, PRD missing or draft | `PRD` | draft/refine PRD at the smallest justified depth, define scope, acceptance criteria and non-goals, persist/link PRD, request `Approval: PRD` | SD, TP, implementation-preparation Brownfield Analysis, implementation, QA, release | `Approval: PRD` |
+| `PRD` approved and PRD artefact persisted or linked, SD missing or draft | `SD` | draft/refine Solution Design, ownership and architecture, persist/link SD, request `Approval: SD` | TP, implementation, QA, release | `Approval: SD` |
+| `SD` approved and SD artefact persisted or linked, TP missing or draft | `TP` | draft/refine Task/Test Plan, task IDs, evidence plan, persist/link TP, request `Approval: TP` | implementation, QA, release | `Approval: TP` |
+| `TP` approved and TP artefact persisted or linked, Brownfield Analysis missing | `Brownfield Analysis` | run Brownfield Analysis for approved TP scope | implementation, QA, release | none |
+| 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, 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 |
+
+
+## Brownfield Modes
+
+The `brownfield-analysis` skill has two explicit modes:
+
+- `post_ur_review`: lightweight sizing and routing after approved durable UR; decides Mode/Slice Decision before PRD depth or implementation is chosen.
+- `pre_implementation_analysis`: implementation-preparation analysis after approved durable TP; verifies reuse path, owners, regression risk and fit before `CD+Tests`.
+
+Do not mix the modes silently. Name the active mode in Brownfield output.