create-agdf 0.11.4 → 0.13.0

package/generated/submissions/openai/agdf/meta/contracts/control-scaffold.md

@@ -0,0 +1,115 @@
+# AGDF Runtime Contract — Control Scaffold
+
+## Delivery Path Search
+
+Delivery Path Search is an optional read-only planning step for high-impact decisions with several materially different next actions.
+
+- It consumes current AGDF state and must reject gate-illegal candidates before model evaluation.
+- It returns one advisory recommendation or `no_safe_recommendation`.
+- It must report budgets, stopping reason and `full | tool_enforced | instruction_only` enforcement.
+- Model scores are judgements, not measurements.
+- Search output is evidence only. Canonical `gate-check` independently decides what may proceed.
+- The bounded first-release algorithm must not be labelled MCTS.
+- Surface adapters may translate transport and presentation, but must not fork scoring, search or gate semantics.
+- Optional AI-native candidate generation supplements the deterministic candidate baseline; it never replaces it.
+- Generated proposals are untrusted. The core must validate schema, exact canonical gate action, scope, duplicates and material diversity before evaluation.
+- Generation is opt-in and bounded to one call, five proposals, 30 seconds and five abstract cost units by default, within whole-run budgets.
+- External generation receives only bounded normalized control summaries and references, never secrets, full artefacts, raw prompts, hidden reasoning or source snapshots.
+- Generator status, provenance, accepted/rejected counts, separate budget use and typed failure must remain visible. Failure retains the deterministic baseline; automatic provider fallback is forbidden.
+- Codex and Claude Code may provide tool-enforced generator transports. Copilot, OpenCode and generic surfaces remain instruction-only without conforming evidence.
+- OpenCode may provide a tool-enforced evaluator only for an invocation whose capability preflight proves `opencode run --pure --agent`, the owned evaluator agent and effective executable-tool denies. Preflight or transport failure must return `evaluator_unavailable` with `instruction_only` enforcement and point to the existing instruction-only workflow; it must not continue through a weaker subprocess.
+- OpenCode candidate generation remains unavailable.
+
+The field names above are the stable machine-readable contract used by JSON
+reports and automation. Human-facing Markdown must present the same projection
+with readable labels such as `Current gate`, `Allowed now`, `Blocked by`,
+`Next step` and `Quality outlook`; do not expose snake_case keys as the visible
+Run Status Card. Keep that card compact: show `Status`, `Current gate`,
+`Allowed now`, `Blocked by`, `Missing approval`, `Next gate after approval`
+and `Allowed after approval` when a missing approval exists, `Next step` and
+`Quality outlook`. Keep mode, forbidden actions, evidence and next-skill detail
+in the surrounding control artefact when they are relevant.
+
+
+## Control Scaffold
+
+### Run-Scoped Control State
+
+Canonical mutable run state lives at `.agdf/control/runs/<run_id>/RUN_STATE.md`, one file per run.
+Repository-level discovery is derived; do not maintain a writable active-run dashboard. Select with
+`--run`, then `AGDF_RUN_ID`, or automatically only when exactly one run is active. Ambiguity fails
+closed. Legacy `AGDF_RUN.md` is migration input or an explicitly rendered non-authoritative projection,
+never a second writable owner. Read-only commands must not migrate state.
+
+When a repository needs durable AGDF state, use the plugin-local `control/` scaffold as the starting point.
+
+- `config.json` stores project language preferences. Use `artifact_language` for generated AGDF artefacts and `chat_language` for user-facing responses unless the user explicitly asks otherwise. Runtime rules remain English.
+- `.agdf/control/runs/<run_id>/RUN_STATE.md` is the canonical current-run dashboard; legacy `AGDF_RUN.md` is migration input or an explicit non-authoritative projection.
+- `MASTER_BACKLOG.md` is the living pointer for active delivery work.
+- `BROWNFIELD_REVIEW.md` records the post-UR existing-system view and Mode/Slice Decision before PRD depth or Quick Task execution is chosen.
+- `SOT_REGISTRY.md` prevents parallel sources of truth.
+- `CONTEXT_GRAPH.md` stores durable Brownfield findings, decisions, risks, evidence and exit criteria.
+- `AGENT_QUALITY_CONTRACTS.json` stores reusable block, revise and warning conditions.
+- `memory_target`, `multi_scope_state` and branch/workspace evidence fields make ambiguity and persistence decisions visible without turning chat history into the source of truth.
+- OR reports live under `.agdf/control/artefacts/<key>/OR.md` when a run closeout is steering-relevant or should be auditable beyond the chat.
+
+### Human-readable Master Backlog
+
+The Markdown backlog is a human steering view; CLI reports are its normalized
+machine projection.
+
+- Use readable status labels such as `In progress`, `Awaiting UAT` and
+  `Completed` in Markdown.
+- Use links relative to `MASTER_BACKLOG.md`, such as
+  `[UR](artefacts/<key>/UR.md)`, instead of exposing long raw paths.
+- Keep `Priority`, `Key`, `Work item`, `Status`, `Artefacts`, `Current spec`
+  and `Next step` visible for active and planned work.
+- Keep one canonical template. Generated surface copies remain derived output.
+- Normalize human labels and link targets only at the CLI parser boundary.
+- Existing wide rows, raw paths and snake_case statuses remain supported for
+  backward compatibility.
+
+The scaffold is not a second documentation site. Link to authoritative artefacts instead of copying them.
+
+## Agent-Native Runtime And CLI Verification
+
+AGDF is agent-native first and CLI-verifiable by design.
+
+The primary operating path is the active skill plus the live `.agdf/control/` artefacts.
+Agents should read the repository state, apply this Runtime Contract, create or update only the currently allowed artefact, and make the next permissible step explicit.
+When control state is missing for a fresh request, keep the first step lightweight: draft the minimal UR in the response and request `Approval: UR`.
+Initialize a control scaffold only when durable AGDF control state is explicitly requested, already used by the repository, or required by a deterministic CLI/CI setup path.
+
+Helper commands are deterministic proof and automation interfaces, not the normal-work ritual:
+
+- `init` creates the machine-readable control scaffold.
+- `doctor --json` checks whether `.agdf/control/` is consistent and actionable; it is not the reviewer.
+- `gate-check --json` reports reproducible gate state; it does not replace the gate-check skill judgement.
+- `gate-check --approval-envelope` prints the canonical ready-gate cards and exact-text request from the same evaluation; it does not grant approval or replace the chat workflow.
+- `delivery-map --json` reports the delivery picture for CI, PRs, regression checks and audit trails.
+
+Machine-readable outputs should stay agent-friendly: stable decisions, blocking gate or current gate, missing approval, allowed outputs, forbidden outputs, next step, evidence and findings.
+They make the repository state checkable, but they do not replace the native skill workflow or the durable control artefacts.
+
+### Repository Activation Diagnosis Boundary
+
+`doctor --json` on the resolved surface-local validator is the sole canonical, code-owned, tool-shell-safe activation probe. Plugin `AGDF_*` environment variables set by the OpenCode `shell.env` hook are an internal plugin status channel consumed by `opencode-status`, not an agent-facing diagnosis proof; host shell-env propagation to spawned tool shells is not guaranteed and is OpenCode-owned. A relative glob or `grep` for `.agdf/control/config.json` must not be used as proof of presence or absence of `.agdf/control/config.json`; an absolute `read` or the canonical CLI probe is required.
+
+## Delivery Map
+
+`delivery-map --json` is the machine-readable delivery picture for the selected canonical control state.
+It derives, but does not replace, the selected `RUN_STATE.md` and `MASTER_BACKLOG.md` state.
+
+It must expose:
+
+- approved or active artefacts and approvals
+- `UR -> PRD -> SD -> TP -> QA_REPORT` relationships
+- evidence refs, missing evidence and declared risks
+- multi-scope ambiguity and branch/workspace evidence limits when present
+- memory persistence target, reason and references when present
+- Context Graph impact and gate effect
+- the Run Status Card as a compact projection of current gate, next step and quality outlook
+- findings that explain why the delivery picture is `pass | warn | revise | block`
+
+Missing relationship evidence in the Artefact Chain is at least `revise` once the related gate artefact is approved or passed.
+Declared missing evidence, declared risk or Context Graph gate effect may escalate the delivery map to `warn`, `revise` or `block`.

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

@@ -0,0 +1,165 @@
+# 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.
+- 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.
+- `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.
+- `Approval: SD` permits Task/Test Plan drafting, not implementation.
+- `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.
+
+
+## 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.
+
+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.
+
+`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
+`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 |
+|---|---|---|---|---|
+| 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 | `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` |
+| 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.