create-agdf 0.14.4 → 0.20.0

package/generated/plugins/copilot/agdf/skills/agdf-ux-intent-definition/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: agdf-ux-intent-definition
+description: "Use this skill for this scope: approved UR with routed medium/high UX impact or ambiguous low-impact semantics before PRD. Boundary: analytical PRD input only; no intent, gate, design or parallel product authority. The requested effect, not discovery, decides AGDF activation."
+---
+
+# ux-intent-definition
+
+## Purpose
+
+Create structured, testable UX intent input before PRD approval so implementation reviews verify an
+approved product promise instead of inventing requirements after code exists.
+
+## Runtime Contract
+
+Use `continuation.runtime_contracts` after `skill_continuation`. If absent: listed MCP `agdf_inspect` (`operation: contract`, `module: <name>`); else supplied schema-2 executable/argv_prefix[0] `contract --module <name>`; else bundled files below. MCP reads need no hook or shell. Missing module: stop; never infer/search for runtime.
+
+- `../contracts/gate-transition.md` for impact routing, authority and revision behavior;
+- `../contracts/quality.md` for evidence and fail-closed output discipline.
+
+`instruction_only`: first load `../contracts/task-target-resolution.md` and `../contracts/interaction.md`.
+
+<!-- AGDF-REQUEST-ACTIVATION-GUARD:START -->
+## Request Activation
+
+- `owner`: `request_activation_contract`
+- `path`: `meta/contracts/request-activation.md`
+- `policy_version`: `1`
+- `guard_fingerprint`: `sha256:af2f01f9e18a3ba1c520faf0691aa1cd4a4299bdfa027cf83651c5d14319bfdc`
+
+Decide effect from loaded instructions before AGDF action.
+
+Abstain silently (no AGDF call) for assessment/explanation/comparison/recommendation/review/diagnosis/advice; hypothetical/example/error/code/quoted/negated delivery language; AGDF as subject; or a read-only constraint absent other delivery. Ambiguity is read-only: answer or ask one neutral question.
+
+Activate for any requested file/code change however small, a binding gate artefact, explicit AGDF/control-lifecycle operation or unambiguous active-run action; delivery wins mixed intent.
+
+Invocation proof: explicit user text/trusted ephemeral action, not discovery/selection, skill load, hooks, cwd, repo/control or prior runs.
+
+Then pick one catalog route; non-authorizing, downstream checks remain.
+<!-- AGDF-REQUEST-ACTIVATION-GUARD:END -->
+
+## Executable Dispatch
+
+Use listed MCP `agdf_dispatch` (load deferred; host prefix allowed): `skill_id` `ux-intent-definition`, `presentation_language`, `working_directory`, and only bound `target_source`/`primary_target` and `run_id`. Never search unlisted tools.
+If absent/failing: supplied schema-2 executable, child-only environment, immutable argv_prefix, declared arguments; `--skill ux-intent-definition`, language and working directory.
+For `--language`: Required presentation language for the latest natural-language user request as one well-formed BCP 47 tag. If the request explicitly asks for a response language, use that tag; otherwise use the dominant request language. Use en when mixed or ambiguous. A valid unsupported tag renders through the complete English pack. Missing or invalid input fails before governance evaluation.
+`target_source`: `explicit_target` if request names `primary_target`; `continued_target` if it unambiguously continues confirmed target; `current_repository` if request names this/current repo with one matching repo active. Otherwise omit the pair; cwd has no target authority.
+Quote shell values as data.
+For a result with `terminal: true`, the entire assistant response must consist only of host_action.text, copied verbatim. Add no question, explanation, heading, citation, link or other surrounding text; do not translate or reformat it; invoke no later tool and stop.
+On skill_continuation use only its target/control. Without that tool and a valid binding: `dispatcher_unavailable`; no runtime search, environment repair
+or help retries. Dispatch never authorizes.
+
+## Authority
+
+This is an internal analytical skill, not a user gate. It cannot approve artefacts, grant
+implementation permission, change approved UR/PRD intent, prescribe technical design or become a
+parallel product source of truth. Proposed criteria become authoritative only when incorporated into
+and approved as PRD content. Technical storage, derivation and component ownership remain SD concerns.
+
+## Inputs
+
+- approved UR and its intent, success signal, primary action and persona/context;
+- requested clarification deliverables, preview scenarios, interaction needs and timing in UR scope;
+- post-UR `delivery_context`, `ui_ux_impact`, reason and required flag;
+- existing behavior/ownership evidence for Brownfield work;
+- known working modes, state semantics, activation, blockers, recovery and transitions.
+
+## Workflow
+
+1. Confirm the approved UR and routing evidence. If required evidence is absent or conflicts, block.
+2. Identify the primary user intent, observable success and primary decision/action.
+3. For every relevant working mode, define effective state and visible state types.
+4. Separate `effective_state_authority_by_mode` from
+   `primary_state_presentation_owner_by_mode`; do not turn either into technical ownership.
+5. Define activation/deactivation, blockers with visible next actions, actionable recovery (including
+   visible retry for recoverable transient failure) and relevant state transitions.
+6. Use UI previews as described below when seeing or trying the proposed behavior materially helps
+   resolve a product question. Propose observable PRD acceptance criteria and identify open questions.
+7. Return exactly one decision: `ready | blocked | not_applicable`.
+
+### UI previews for clarification
+
+Use a focused preview during UX intent clarification and reuse its findings during PRD alignment.
+Start with the user's task and unresolved decision, not a decorative dashboard. Show the relevant
+starting state, primary action, visible outcome and, where relevant, a blocker or recovery path.
+For example: can the user find what was checked, identify an open risk and decide whether to approve?
+Match known product context; identify illustrative data and unconfirmed assumptions explicitly.
+
+First preserve any preview explicitly required by approved UR scope, including its interaction,
+format and timing. Use an available visualization capability such as `visualize` when suitable.
+For an optional aid, a wireframe or written scenario walkthrough may answer the same question.
+For an explicitly requested interactive preview, unavailable tooling requires concrete recovery or
+an explicit scope revision; do not silently downgrade it or report the obligation fulfilled.
+Do not invent a preview requirement for already clear semantics, add a gate or install a dependency.
+Keep prototype interactions local; they cannot submit real approvals, modify delivery state or start
+implementation. A requested change to the actual product still follows its existing delivery path.
+
+#### Retain a run-bound preview
+
+For a preview used in this bound analysis, save a durable, reopenable copy under
+`.agdf/control/artefacts/<run_id>/previews/<short-name>-v<N>/index.html`, relative to the supplied
+governance target. Derive the run from the valid assignment, not cwd, recency or another run.
+Resolve containment and reject symlink escapes before writing; never put preview content in
+`runs/<run_id>/RUN_STATE.md`. Use a new unused version for revisions and preserve reviewed versions.
+Store a standalone document, preferably self-contained; bundle any local assets with relative
+references. For an inline visualization, keep its editable source in the host's permitted location
+and export a standalone copy to the run directory using that capability's supported flow. Remove
+host-only dependencies from the durable copy. Reopen it from its saved location and exercise the
+relevant interaction before claiming portability; an export or screenshot alone is insufficient.
+For required interactive PRD review, make that durable copy offline with local classic scripts,
+styles and images, without modules, remote resources or host calls. The PRD author owns the
+`Preview Review` descriptor and final criterion mapping; UX supplies the exact files and findings.
+
+Record the target run, source UR revision/digest, preview version, relative entry path, SHA-256 of
+the saved file (and local assets), covered scenarios and actual validation limits in the existing
+analysis `evidence` field. Keep observations tied to that version; a changed preview needs fresh
+inspection and affected user feedback. The UX report and PRD link the same evidence, not divergent
+copies. Use existing canonical recording/revision owners for their updates; preview bytes are
+supporting evidence, not a new approval authority or an automatically sealed artefact type.
+An unbound conversation preview remains advisory; do not create or select a run just to attach it.
+
+For PRD alignment, hand off a concise user review task, the readable versioned preview reference,
+covered scenarios and proposed criterion IDs alongside the observations. The existing presentation
+owner uses this material under interaction.md PRD Preview Review At Approval. Distinguish the
+proposed experience from delivered functionality and record any unavailable review access explicitly.
+
+Walk through the concrete task with the user and record observed behavior, feedback, unresolved
+assumptions and resulting proposed criteria in the existing `evidence`, `open_product_questions`
+and `proposed_prd_acceptance_criteria` fields. Distinguish agent inspection from user observation;
+check rendering and the relevant interaction before claiming they work. If no inspection or user
+observation occurred, say so. Retain the scenario and findings as well as the durable preview
+reference; chat-only or missing preview evidence cannot fulfill an explicit preview requirement.
+Preview feedback is analytical
+input, not PRD approval, implementation evidence or host qualification. Layout and component choices
+remain illustrative; only explicitly adopted product behavior becomes approved PRD content.
+
+## Decision Rules
+
+- `ready`: every required output is reliable enough for PRD drafting, including a requested preview
+  at the agreed fidelity, its durable evidence and resolution of material product questions.
+- `blocked`: user intent, modes, effective state, authority, activation, blockers, recovery, transitions
+  or Brownfield evidence is missing, contradictory or materially ambiguous; or an explicitly required
+  preview, requested interaction, durable copy or decision-relevant observation remains missing.
+- `not_applicable`: routing proves that no relevant user-facing intent, state or recovery behavior changes.
+
+A conflict with approved UR routes to UR revision. A material product change discovered after PRD
+approval routes to PRD revision, or UR revision when intent/scope changes. Never resolve the conflict
+silently. A required blocked result prevents PRD readiness.
+
+## Output
+
+Populate each field or use an explicit, justified `not_applicable`:
+
+```text
+- decision: ready | blocked | not_applicable
+- blocking_reason:
+- primary_user_intent:
+- success_signal:
+- primary_decision_or_action:
+- working_modes:
+- effective_state_by_mode:
+- visible_state_types:
+- effective_state_authority_by_mode:
+- primary_state_presentation_owner_by_mode:
+- activation_paths:
+- blockers:
+- recovery_paths:
+- relevant_state_transitions:
+- proposed_prd_acceptance_criteria:
+- open_product_questions:
+- affected_outputs:
+- evidence:
+- missing_evidence:
+- required_next_step:
+```
+
+For `blocked`, `blocking_reason`, `open_product_questions`, `affected_outputs`, `evidence`,
+`missing_evidence` and `required_next_step` are mandatory. When durable control state exists, write
+the result to `.agdf/control/artefacts/<run_id>/UX_INTENT_DEFINITION.md` without a Gate or approval field.
+
+## Forbidden
+
+- invent product intent or silently choose between conflicting modes/state authorities;
+- bypass UR/PRD revision or claim PRD readiness from a blocked result;
+- add a gate, approval value or implementation permission;
+- prescribe components, persistence, endpoints, styles or other technical design;
+- treat supporting analysis as authoritative beside the approved PRD.
+
+Apply interaction.md Bounded internal recovery and prepared observation for eligible bound follow-up. It adds no gate or approval authority.

package/generated/plugins/copilot/agdf/skills/contracts/closeout.md

@@ -0,0 +1,82 @@
+# AGDF Runtime Contract — Closeout
+
+## Support Answer Bridge
+
+When the user asks about a concrete ticket, issue, incident or support question, end with exactly one smallest useful next step.
+Do not treat that next step as approval.
+When the next step is gated, name the required approval or AGDF skill instead of implying work may proceed.
+
+
+## Relevant Run
+
+When `release-or` authors the Orchestration Report, it uses only the bound absolute plugin-owned
+`template_path` for `OR.md`. Repository scaffold copies never override it. Missing or unsafe plugin
+content blocks OR authoring without mutation or fallback and remains an explicit closeout gap.
+
+A relevant run is any run that changes durable state, creates or updates an AGDF artefact, changes code or runtime behaviour, performs a gate decision, blocks on a governance condition, produces QA/UAT/release evidence, or closes a delivery slice.
+
+OR is not mandatory for a pure explanation, read-only inspection, small review, or local debugging step that produces no durable state change and no gate consequence.
+When in doubt, use a short OR-lite only if it clarifies gate state, evidence, risk, or the next permissible step.
+
+A `quick_task` fully inside the Non-Normative Trivial Change Boundary above stays exempt from the full
+selected-run ceremony even when it is otherwise a relevant run. If a selected canonical
+`RUN_STATE.md` currently reflects another scope, append exactly one line to that run's
+`Prior Run Pointers` section noting what changed and that it is unrelated; do not edit any other
+section or any other existing line.
+
+
+## Parent Reconciliation Handoff
+
+Parent reconciliation is an optional closeout coordination projection. It never grants, revokes or
+blocks Child gates, QA, UAT, OR completion or an otherwise valid delivery handoff.
+
+It activates only when the Child `Artefact Chain` contains exactly one evidenced row with:
+
+- `From`: `OR`
+- `Relationship`: `reconciles_with`
+- `To`: `parent_run:<run_id>` using the canonical run-id grammar
+
+Names, directories, branches, backlog proximity, chat history and evidence prose do not establish
+Parentage. Delivery Map is the single deterministic evaluator. It compares the Child row with one
+evidenced reciprocal Parent row `Aggregate | includes | child_run:<run_id>` and returns exactly one
+outcome:
+
+- `resolved`: the named Parent has exactly one evidenced reciprocal Child relationship;
+- `not_applicable`: the Child declares no qualifying Parent relationship; or
+- `open`: the explicit relationship is invalid, ambiguous, unavailable, stale or lacks reciprocal
+  evidence.
+
+An open outcome contains concrete evidence or missing evidence and exactly one next action. Optional
+Child handling input is limited to `action_required | accepted_open`. `accepted_open` keeps the
+outcome open and visible while allowing independently valid Child delivery to continue; it never
+asserts Parent reconciliation. Evaluation is read-only and must never mutate a Parent.
+
+`release-or` reports the evaluated result in the Child OR. `delivery-closeout` consumes that OR
+projection only; it must not search sibling runs, infer a relationship, reevaluate evidence or repair
+a Parent. Unresolved explicit reconciliation is warning-level coordination evidence, not a Child
+gate failure. Legacy runs without the optional relationship remain unchanged and add no routine
+visible ceremony.
+
+
+## Programme Aggregation Readiness
+
+An explicit Parent/programme run may project two independent evidence values:
+
+- `startable: true` requires at least one evidenced `Aggregate | includes | child_run:<run_id>` row
+  whose Child has a completed OR;
+- `final_ready: true` additionally requires one valid declared acceptance artefact beneath
+  `.agdf/control/artefacts/`, concrete aggregation evidence and
+  `programme_aggregation_missing_evidence: none`.
+
+`final_ready: true` always implies `startable: true`. Failed prerequisites stay false with explicit
+missing evidence and one next action; they are never silently promoted. These values are evidence
+projections only. They do not approve QA/UAT, create a gate or define the programme-specific
+acceptance criteria, which remain owned by the referenced programme artefact.
+
+
+## Do Not Duplicate
+
+The explanatory framework lives in `docs/`.
+The operating philosophy lives in `plugins/agdf/meta/agdf-constitution.md`.
+The principles live in `plugins/agdf/meta/agdf-tenets.md`.
+This contract is only the compact runtime interface for skills.

package/generated/plugins/copilot/agdf/skills/contracts/context-graph.md

@@ -0,0 +1,48 @@
+# AGDF Runtime Contract — Context Graph
+
+## Knowledge Persistence Decision
+
+Every relevant run should decide what happens to new durable knowledge.
+The decision is not a memory dump; it routes only reusable, evidenced information to the right owner.
+
+Use:
+
+- `memory_target: context_graph | sot_registry | scope_artifact | open_questions | none`
+- `memory_reason`: short reason for the target
+- `memory_refs`: paths or nodes affected
+
+Guidance:
+
+- Use `context_graph` for reusable Brownfield findings, decisions, risks, invariants and exit criteria.
+- Use `sot_registry` when source-of-truth ownership changes or drift is found.
+- Use `scope_artifact` for run-specific evidence, ticket details, screenshots, logs or local reproduction data.
+- Use `open_questions` when a durable question should survive the run but no answer is evidenced yet.
+- Use `none` for one-off observations without future decision value.
+
+
+## Context Graph Output
+
+When a run affects project memory or a Context Graph, use:
+
+- `Situation:` short plain-language summary when the impact is non-trivial
+- `context_graph_impact`: `none | link_only | update_existing_node | new_node_required | sot_drift`
+- `context_graph_refs`
+- `context_graph_reconciliation`: `resolved | not_applicable | open_gap`
+- `context_graph_required_action`: `none | link | update | create | resolve_drift`
+- `context_graph_gate_effect`: `none | warning | revise | block`
+- `context_graph_evidence`
+
+Do not create a new node for a mere version, a general chat summary, or a local observation without a concrete next clean step.
+`sot_drift` must not pass silently as a warning.
+
+### Context Graph Reconciliation
+
+Relevant-run closeout must reconcile Context Graph impact before presenting a clean delivery handoff.
+
+- Use `not_applicable` only when `context_graph_impact: none` and no durable graph knowledge is claimed.
+- Use `resolved` when required graph work is complete and concrete refs are present.
+- Use `open_gap` when graph work remains pending, refs are missing, or a node/update must still be curated.
+- `link`, `update`, `create` and `resolve_drift` require either `resolved` evidence or an explicit `open_gap`.
+- Resolved `link_only`, `update_existing_node` and `new_node_required` states require concrete `context_graph_refs`; `none`, empty refs or vague future-action language are not enough.
+- OR and delivery-closeout must not present commit-ready, release-ready or otherwise clean handoff while `context_graph_reconciliation: open_gap` remains.
+

package/generated/plugins/copilot/agdf/skills/contracts/control-scaffold.md

@@ -0,0 +1,145 @@
+# 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 the canonical selected-run `gate-check` evaluation for run, revision, current gate and
+  legal actions. Persisted presentation Markdown such as the Run Status Card is never policy input.
+- It binds the selected `scope_key`, `scope_revision` and objective to one control snapshot. A stale
+  or incomplete snapshot fails before candidate generation or evaluation.
+- It reports the phase that actually ran: `input | candidate | evaluation | search`. A phase that
+  did not run cannot produce a later-phase conclusion.
+- Terminal status is `input_unavailable | no_legal_candidates | evaluator_unavailable |
+  evaluator_error | recommendation | no_safe_recommendation`. Recommendation-facing statuses
+  require at least one contract-valid evaluation. `candidate_queue_exhausted` is a stopping reason,
+  not recommendation evidence.
+- It reports baseline/generated/legal/rejected candidate counts and attempted/valid/invalid
+  evaluation counts. Zero valid evaluations must never be presented or persisted as an evaluated
+  recommendation conclusion.
+- 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.
+- Search applies only to the selected run objective. An unrelated decision needs the correct
+  governed scope; Delivery Path Search is not a second task-target resolver.
+- 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.
+- Persistence accepts only contract-valid `recommendation` or `no_safe_recommendation` results with
+  at least one valid evaluation. Input, candidate and evaluator failure results remain transient.
+
+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.
+
+`run-create` writes a sealed run. The seal covers the run state and every file listed under
+Artefacts; an unrecorded edit blocks `doctor` and `gate-check` with `AGDF_RUN_SEAL_MISMATCH`. After
+changing either, call `run-update --run <run_id> --revision <revision_id>` before `gate-check`; it
+advances the revision and refuses Approvals changes. Only `run-approve` records an approval. Both run
+on the surface-local validator. The seal detects unrecorded edits; it is not a signature.
+Keep one `Artefacts` row per type: update the existing placeholder row instead of appending another.
+`run-update` and all run writers reject duplicate rows without advancing the revision. Remove the
+extra row and retry `run-update` to record the correction. Duplicate rows in older sealed runs also
+block `doctor` and gate presentation.
+
+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. `chat_language` is the direct-command presentation default; dispatcher calls supply `presentation_language` under their current-request language contract. This presentation override never changes `artifact_language`. Runtime rules remain English. Authoring continuations supply the resolved languages and any required localized approval-summary heading before drafting.
+- `.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, follow the existing setup/link boundary before run creation.
+After a concrete run is bound, dispatch delegates requirement drafting to `ur-definition`.
+Only fresh canonical readiness and a run-present binding may request `Approval: UR`.
+This branch is unreachable for `target_unresolved`.
+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. On a host that lists the AGDF MCP server, the read-only tool `agdf_inspect` (`operation: doctor | gate-check | delivery-map | contract`) returns the same `--json` object and canonical Markdown without a shell; the shell binding stays the fallback. It never writes control state or prepares an approval binding.
+- `gate-check --json` reports reproducible gate state; it does not replace the gate-check skill judgement.
+- `gate-check --approval-envelope` prints a read-only summary and link to the current artefact. The agent uses `run-present` before asking for an exact gate approval.
+- `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
+- optional evaluated Parent reconciliation and programme aggregation readiness from the Closeout
+  Contract, without changing Child gate authority
+- 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/plugins/copilot/agdf/skills/contracts/gate-artifact-preparation.md

@@ -0,0 +1,132 @@
+# AGDF Runtime Contract — Gate Artifact Preparation
+
+This contract guides the `gate-check` skill when canonical gate evaluation returns
+`control.next_operation.type: prepare_gate_artifact`. It is procedural guidance only; canonical
+Run State, gate evaluation and exact approval remain authoritative.
+
+## Common Route
+
+- Use only the supplied `gate`, `artifact_path`, `template_path`, `source_artifacts`, `target`,
+  `run_id` and `revision_id`. `template_path` is the absolute canonical authoring template from the
+  installed, version-matched plugin for PRD, SD, TP or QA Report preparation. Repository scaffold
+  copies are derived references only. Do not rediscover or substitute a run, target, source
+  artifact or template. A missing or unsafe template blocks authoring without fallback or mutation.
+- Prepare only the named current-gate artifact from the supplied approved sources.
+  Record with `run-step --step artefact --gate <PRD|SD|TP|QA>
+  --evidence .agdf/control/artefacts/<run_id>/<input.json> --run <run_id> --revision <revision_id>`.
+  Do not publish a pointer and its required source relationship in separate accepted revisions.
+- After persistence, redispatch `gate-check` for the same target/run and use its fresh revision,
+  gate route and approval presentation. Do not reuse this operation or ask for approval until the
+  fresh dispatcher result supplies a valid presentation.
+- If a source is missing, a prerequisite is unresolved, the state changed, or persistence fails, stop
+  dependent authoring. Use interaction.md Bounded internal recovery only for its dispatched eligible
+  analytical owner; other conditions stay blocked. Never infer approval or create later-gate work.
+
+## Reviewed Recording Input (version 1)
+
+### Language and approval summary preparation
+
+Use the supplied `artifact_language` from `.agdf/control/config.json` for the artefact and
+the resolved `presentation_language` for user-facing text. The configured chat language is
+the direct-command default; dispatcher presentation input follows its current-request contract.
+Neither the request language nor English runtime/template text changes the artefact language.
+When `approval_summary_required` is true, before recording include exactly one
+`## <approval_summary_heading>` section with the supplied heading verbatim and a complete
+summary in the resolved presentation language. Apply the existing interaction contract's
+summary completeness and size limits; use no ellipses or hidden decision-relevant omissions.
+For PRD include user goal, scope, every canonical criterion ID exactly once, and decision context
+when approval decisions exist. Corrections use the existing permitted recording/revision path
+and require a fresh presentation. The summary grants no approval and is not another authority.
+
+Before recording, prefer the existing read-only MCP tool `agdf_inspect` with
+`operation: artifact-readiness`, `presentation_language`, `working_directory`, the resolved
+`primary_target`/`target_source`, and the supplied `run_id`, `gate` and `expected_revision_id`.
+Supported draft gates are `UR | PRD | SD | TP`. The Core derives the contained run-local
+`<gate>.md` path; there is no caller-supplied arbitrary path or implicit Run selection.
+This operation calls the existing summary, product-decision and traceability validators.
+The response has `report.ready`, `checks`, concrete `diagnostics`, `artifact_path`,
+`artifact_digest`, current/expected revision and `next_action`; `authorizes` is always false.
+`ready` covers authoring checks only: it neither records the draft nor establishes semantic
+derivation, source-binding proof, final QA, presentation or approval readiness. Missing source,
+stale revision, approved source or canonical integrity/gate blockers keep it unready. Resolve
+the named issue through its existing owner. No recording or approval follows from this result
+alone. Registration and run-present repeat their own current canonical checks.
+
+Without that MCP capability, use the exact Core function
+`inspectArtifactReadiness(root, { runId, gate, expectedRevisionId, presentationLanguage })`
+in `packages/core/lib/control-inspect/artifact-readiness.js` (packaged as
+`runtime/create-agdf/runtime/core/lib/control-inspect/artifact-readiness.js` in the plugin). Same report; no writes.
+Do not search for internal validator signatures or invent a replacement validator.
+The existing Core `evaluateApprovalSummaryReadiness` remains the summary owner.
+For a German PRD summary use separate `- Ziel:`, `- Umfang:` and, when decisions exist,
+`- Entscheidungen:` lines; English summaries use `- Goal:`, `- Scope:` and `- Decisions:`.
+Each criterion has its own `- AC-...:` line. A combined label such as `Ziel und Umfang:` or
+`Entscheidungskontext:` is not one of these fields. Readiness and presentation share this validator;
+do not accept prose as a substitute or invent another parser. An eligible own unapproved format
+correction stays with the existing authoring continuation, once per diagnosed condition, followed
+by canonical replacement and fresh evaluation. A ready draft still needs actual editing intent;
+status is read-only, protected sources and unrelated blockers remain stopped.
+
+Prepare files under `.agdf/control/artefacts/<run_id>/` before recording. The single shared Core
+relationship registry selects PRD-derived_from-UR, SD-derived_from-PRD, TP-derived_from-SD or
+QA_REPORT-tests-TP. UR-approved_by remains exclusively approval-owned. QA recording copies an
+existing report's explicit Decision/Status value (`pass | revise | block`); it does not decide QA.
+
+The JSON object has exactly these fields:
+
+- `schema_version`: string `1`.
+- `target_id`: existing local command-target identity, SHA-256 of `agdf-command-target/1`, NUL,
+  and the canonical real absolute governance target. This is a binding, not authority.
+- `run_id`, `expected_revision_id`: the supplied selected run and current revision.
+- `destination`: exactly `type`, `path`, `digest`, `status`; logical registry type, canonical
+  run-local `<type>.md`, full canonical SHA-256 and `draft` for PRD/SD/TP, report decision for QA.
+- `source`: exactly `type`, `path`, `digest`; the registry's approved source and canonical digest.
+- `relationship`: exactly `from`, `relationship`, `to`; the explicit registry triple.
+- `review`: exactly `reviewer`, `path`, `digest`; named reviewer, separate contained mapping file
+  and its canonical SHA-256. Do not overwrite an earlier sealed proof file.
+- `update_draft`: boolean; true only for an explicit current-gate draft update.
+
+The mapping file is JSON with exactly `schema_version`, `target_id`, `run_id`, `relationship`,
+`destination`, `source`, `reviewer`, `reviewed`. Identity and source/destination objects match
+the recording input exactly; reviewer matches review.reviewer, and reviewed is boolean true.
+Digests use the existing canonical text/line-ending semantics. This is cooperative review
+attestation, never independent proof of a human review or semantic derivation. QA/review assesses
+the meaning. A prose header or gate order is not machine proof.
+
+The existing operation checks current permission, contained non-symlink files, exact approved
+sources and revision under locks. It appends its sealed Artefact Bindings receipt/history and
+publishes pointer, relationship and audit together. The receipt is writer-owned; do not hand-author
+it. An allowed draft replacement supersedes the prior active binding, retaining history. A changed
+draft is accepted only when its prior binding reconstructs the recorded seal and every other
+bound/approved byte remains unchanged. Otherwise stop with explicit maintenance/revision recovery.
+
+Before presentation/approval, a recorded eligible current artefact must have its evidenced source
+relationship. Missing artefacts remain draftable; a relationship-only blocker must not redraft the
+artefact repeatedly. Only authorized bound continuation can attempt one exact previously sealed
+proof correction before output. The shared Core continuation service coordinates this operation
+and fresh routing; the dispatcher service itself only reads and routes. Explicit status, doctor,
+evaluation and run-present never correct.
+Unknown/malformed/foreign/stale/ambiguous proof, missing full approval integrity or unrelated
+blockers remain blocked; legacy absence grants no correction permission. A successful correction
+creates a new audited revision and fresh evaluation without another approval. Terminal output
+already emitted is never intercepted. Older runtimes have no automatic correction capability.
+
+## Gate-Specific Work
+
+### PRD
+
+Semantic PRD drafting and clarification belongs exclusively to prd-definition under its focused
+contract. This module supplies the shared Reviewed Recording Input procedure only; gate-check
+controls prerequisites, readiness and presentation.
+
+### SD
+
+Semantic SD drafting and clarification belongs exclusively to sd-definition under its focused
+contract. This module supplies the shared Reviewed Recording Input procedure only; gate-check
+controls prerequisites, declared decision readiness, traceability and presentation.
+
+### TP
+
+Semantic TP drafting, clarification and explicit unapproved revision belong exclusively to
+tp-definition under its focused contract. This module supplies shared recording only; gate-check
+retains prerequisite/readiness and presentation authority.