create-agdf 0.14.5 → 0.20.0

package/generated/.agdf/control/README.md

@@ -77,10 +77,28 @@ agdf gate-check --json
 ## Operating Rules
 
 - Canonical mutable state is isolated per run at `runs/<run_id>/RUN_STATE.md`. Run discovery is
-  derived; do not maintain a writable active-run index. Select explicitly with `--run` or
-  `AGDF_RUN_ID` when more than one run is active.
+  derived; do not maintain a writable active-run index. When several runs are active, discovery
+  presents the most recently updated run first and lists the others, but requires an explicit run
+  selection for read-only status or explicit run-selection requests. Implementation intake first
+  provides canonical UR evidence to the coding agent for scope assignment, even with one active
+  run: resume one same-scope continuation, start a new UR run for an independent scope, or clarify
+  genuinely overlapping work. If no active run exists during a status request, ask whether to start
+  one or do something else. Status never creates a run. `updated_at` is recorded with
+  every canonical run write; older runs use file modification time until their next recorded update.
 - Migrate legacy state explicitly with `run-migrate`; read-only commands never migrate. A retained
   `AGDF_RUN.md` is migration input or a non-authoritative projection, not a second writable owner.
+- A run created by `run-create` is sealed. Record every change to it or to a listed artefact with
+  `run-update`, and record exact gate replies only with `run-approve`; an unrecorded edit blocks
+  `doctor` and `gate-check` until it is recorded.
+  If a run lists its own `RUN_STATE.md`, the seal covers its body directly and uses a self-reference
+  marker for that artefact entry. This avoids circular on-disk hashing; references to other runs
+  remain fully hashed. Old self-reference failures require a verified restoration, never a blind re-seal.
+- Record the standard small-path steps with one `run-step` call each instead of editing the run state
+  and `MASTER_BACKLOG.md` by hand: `--step ur --title` after writing `artefacts/<run_id>/UR.md`;
+  `--step route --route <mode> --reason --evidence` after writing `BROWNFIELD_REVIEW.md`;
+  `--step evidence` for test or check results; `--step review --decision --evidence` for Code Review;
+  and `--step closeout --result --evidence --risk --next` to close a `quick_task` with OR-lite. Each
+  call maintains the tables, the backlog pointer and the next allowed action and prints the next step.
 
 - The selected `runs/<run_id>/RUN_STATE.md` is the current run dashboard.
 - `config.json` stores the project preference for artefact and chat language; runtime rules stay English.
@@ -96,3 +114,12 @@ agdf gate-check --json
   merge or pull, rerun `doctor` and `gate-check` for the selected run.
 
 Do not duplicate full product documentation in this scaffold. Link to the authoritative artefact instead.
+
+## Planned outputs during recovery
+
+A missing file explicitly declared `missing` or `pending` under the selected run's own
+`.agdf/control/artefacts/<run_id>/` directory is a planned output, not lost completed evidence.
+Recovery retains its path and absence in the integrity snapshot and leaves its status pending.
+It does not create evidence or approve a gate. Completed or ready evidence, unsafe paths and
+descriptive placeholders still require repair. Creating a planned file after a recovery preview
+invalidates that preview; creating it after recovery changes the seal until a canonical update.

package/generated/.agdf/control/templates/MASTER_BACKLOG.md

@@ -15,12 +15,14 @@ This file is the living control pointer for active AGDF delivery work. Detailed
 9. Historical artefacts remain linkable but do not override the current pointer.
 10. If an item is superseded, mark the replacement.
 11. If active work grows beyond roughly ten items, triage the backlog.
-12. `Status` must be one of the human-readable labels normalized by `create-agdf/lib/control-evaluation/shared.js`: Needs UR, Awaiting Brownfield Review, Awaiting PRD, Awaiting PRD Approval, Awaiting SD, Awaiting SD Approval, Awaiting TP, Awaiting TP Approval, In Progress, Blocked, Awaiting QA, Awaiting UAT, Awaiting OR, Completed, Superseded, Abandoned. The parser module is authoritative; this list only mirrors it for readability.
+12. `Status` must be one of the human-readable labels normalized by `packages/core/lib/control-evaluation/shared.js`: Needs UR, Awaiting Brownfield Review, Awaiting PRD, Awaiting PRD Approval, Awaiting SD, Awaiting SD Approval, Awaiting TP, Awaiting TP Approval, In Progress, Blocked, Awaiting QA, Awaiting UAT, Awaiting OR, Completed, Superseded, Abandoned. Generated observations also use Work pending, Approval pending, QA report pending, QA evidence open, QA correction open, QA source decision required, QA blocked, Source unconfirmed, Closeout pending, Unconfirmed, and phase-specific Brownfield Analysis/CD+Tests/CR/Quick Task Execution/Verified Change Execution/Mode/Slice Decision work pending. The parser module is authoritative; this list only mirrors it for readability.
 13. `Artefacts` link labels must be one of the labels normalized by the same parser module: `ur`, `brownfield`, `prd`, `sd`, `tp`, `qa`, `or` (case-insensitive). Do not invent other labels such as a raw artefact filename.
 14. After writing or updating this file, run `doctor --json` (or the locally available equivalent) and resolve any `AGDF_BACKLOG_STATUS_UNKNOWN` or `AGDF_BACKLOG_ARTEFACT_LABEL_UNKNOWN` finding before treating the edit as done.
-15. A `Work item` cell may optionally start with a bracketed scope tag, one of `[framework-maintenance]` or `[external-delivery]`, so the split between AGDF's own maintenance work and external product delivery stays visible at a glance. The tag is never required retroactively on `Completed / Superseded Pointers` rows. `create-agdf/lib/control-evaluation/shared.js` is authoritative for the accepted values.
+15. A `Work item` cell may optionally start with a bracketed scope tag, one of `[framework-maintenance]` or `[external-delivery]`, so the split between AGDF's own maintenance work and external product delivery stays visible at a glance. The tag is never required retroactively on `Completed / Superseded Pointers` rows. `packages/core/lib/control-evaluation/shared.js` is authoritative for the accepted values.
 16. After writing or updating this file, also resolve any `AGDF_BACKLOG_SCOPE_LABEL_UNKNOWN` finding, which fires only for a present-but-unrecognized bracketed tag, never for an absent one.
 
+17. Core writers may place a bounded `agdf-backlog-summary-v1` comment after a complete table, separated by a blank line. It records the addressed row, target, actual Run revision, observation time and consumed source digests; it never authorizes. Preserve it with its row. Older rows remain readable without it. Invalid/foreign/ambiguous observations remain visibly unconfirmed; reading does not synchronize or scan all Runs.
+
 ## Active Backlog
 
 | Priority | Key | Work item | Status | Artefacts | Current spec | Next step |

package/generated/.agdf/control/templates/RUN_STATE.md

@@ -7,6 +7,7 @@
 - lifecycle: active
 - revision: 1
 - revision_id:
+- updated_at:
 - mode: structured_delivery
 - current_gate: UR
 - decision: in_progress

package/generated/.agdf/control/templates/artefacts/BROWNFIELD_REVIEW.md

@@ -41,12 +41,43 @@ Brownfield cites repository evidence.
 | Tests / QA |  |  | `none | low | medium | high` |
 | Release / operations |  |  | `none | low | medium | high` |
 
+## Architecture Impact
+
+- architecture_relevance: `relevant | architecture-not-applicable`
+- architecture_impact: `none | low | medium | high`
+- architecture_reason:
+- architecture_evidence:
+- architecture_missing_evidence: `none | <fact and evidence owner>`
+- architecture_next_owner_and_action:
+
+Assess only affected module/owner, external interface, data/SoT, compatibility/migration,
+runtime/host, or security/policy boundaries. An unresolved effect is relevant until its evidence
+owner resolves it. For `architecture-not-applicable`, cite the affected code and owner and explain
+why no material boundary or unresolved question remains. Do not add an exhaustive checklist.
+
 ## Reuse And Parallel-Structure Risk
 
 | Finding | Evidence | Risk | Required action |
 |---|---|---|---|
 |  |  | `none | warn | revise | block` |  |
 
+For a relevant architecture finding, prefix the existing Finding cell with `problem`,
+`trade-off` or `unresolved`; cite its boundary in Evidence and put the existing owner and route
+in Required action. A deliberate trade-off that retains or adds debt uses the same finding label
+in the detail below. An incomplete detail remains unresolved and cannot be called accepted debt.
+Keep the review decision at least `revise` until every debt-acceptance field is evidenced;
+use `block` if the missing decision prevents a safe Mode/Slice route.
+Add a focused diagram link only if it answers a named ownership or dependency question that
+textual evidence cannot settle.
+
+### Retained Debt Detail (only when applicable)
+
+- finding: <same label as the Reuse And Parallel-Structure Risk row>
+- rationale:
+- accountable_owner:
+- mitigation:
+- review_date_or_exit_condition:
+
 ## Mode / Slice Decision
 
 - decision: `quick_task | verified_change | structured_slice | structured_delivery | block`

package/generated/.agdf/control/templates/artefacts/PRD.md

@@ -6,6 +6,7 @@ Gate approval: open
 Based on: UR
 Date:
 Owner:
+Traceability contract: criteria-chain-v1
 
 ## 1. Product Scope
 
@@ -22,6 +23,24 @@ What exactly must be delivered?
 Every field must be populated or explicitly justified as `not_applicable`. Medium/high impact requires
 a `ready` UX Intent Definition result before this PRD is ready.
 
+If UI previews or scenario walkthroughs informed clarification, summarize the user task and confirmed
+findings here. Map adopted behavior to criterion IDs in Acceptance Criteria, retain observation limits
+in Evidence Requirements and resolve material choices in Approval Decisions. Keep the PRD sufficient
+to understand the required behavior without opening the preview. Link the same run-local preview
+version, file/asset digests and observations recorded by UX. An explicitly required preview must
+exist at the agreed fidelity before its obligation is closed; a chat rendering alone is insufficient.
+A mockup is supporting input and carries no separate approval or implementation proof.
+
+For a required preview, include a concise review task, readable versioned preview reference and
+covered scenarios with their criterion IDs. State what the reviewer should judge about the proposed
+behavior. The existing presentation owner uses this review material; authoring must not add a second
+approval card. See interaction.md PRD Preview Review At Approval for the integration requirements.
+When the approved UR declares `Preview requirement: before_prd_interactive`, add the exact
+`## Preview Review` JSON section defined by prd-definition.md, binding the approved UR digest,
+versioned run-local files, review task, scenarios, criterion IDs and open questions. Its machine
+format is also available through the existing PRD authoring-format contract. Do not create an empty
+descriptor for an unrelated legacy PRD or turn illustrative unanswered policy into a resolved choice.
+
 ## 3. Working Modes And Effective State
 
 For every user-relevant working mode, define:
@@ -43,9 +62,12 @@ ownership remain Solution Design concerns.
 
 ## 5. Acceptance Criteria
 
-Every applicable UX criterion must include a stable `criterion_id`, `working_mode`, `source_state`,
-trigger/action, expected effective state, visible feedback, blocker/failure behavior, recovery/next
-action, observable success and required evidence. Specify observable behavior, not implementation.
+Give every acceptance criterion a unique, stable `criterion_id` (for example `AC-001`) so SD, TP
+and QA can refer to the same requirement without copying or renaming it. Every applicable UX
+criterion must also include `working_mode`, `source_state`, trigger/action, expected effective state,
+visible feedback, blocker/failure behavior, recovery/next action, observable success and required
+evidence. Specify observable behavior, not implementation. Do not leave the section empty or retain
+placeholders when requesting approval.
 
 ## 6. Non-Goals
 
@@ -65,10 +87,27 @@ Which evidence must later support QA?
 
 ## 10. Risks And Open Questions
 
-Which questions must SD, TP or Brownfield Analysis clarify later?
+Record risks and questions that can be answered later. Move every decision that changes product
+scope, acceptance, accountable ownership or release acceptance into Approval Decisions below.
+
+## Approval Decisions
+
+Before presenting this PRD, collect all `before_prd` answers in one request and record their
+resolution here. Use `later_sd` or `later_tp` only for genuine design or planning decisions;
+name the responsible owner in the final column. Keep at least one explicit row.
+
+| Decision | Timing | Status | Resolution | Owner |
+|---|---|---|---|---|
+| <product decision or none> | before_prd | open | <answer> | <accountable owner> |
 
 ## 11. Next Step
 
-Review this PRD and approve only with:
+Present this PRD only after every `before_prd` row is `resolved` with a concrete answer and
+the named PRD Owner is filled. Then review and approve only with:
 
 `Approval: PRD`
+
+The approval confirms the specified behavior, scope and criteria and permits the existing SD step.
+For a required preview, present its review task and exact applicable version together with the PRD
+through the supported canonical presentation. Opening or liking the preview is no approval. A
+missing required review basis or unsupported binding must remain visible, not silently count as ready.

package/generated/.agdf/control/templates/artefacts/QA_REPORT.md

@@ -13,6 +13,8 @@ Decision: `pass | revise | block`
 
 ## 2. TP Coverage
 
+- delivered_result: <Concrete actual scoped result; not a task count, plan or report title>
+
 Which TP tasks are fully done, partially done or not done?
 
 ## 3. Evidence
@@ -21,10 +23,14 @@ Which tests, logs, diffs, reviews or observations support the decision?
 
 ## 4. Missing Evidence
 
+- qualification_limits: <Concrete unobserved qualification or explicit none>
+
 What remains unverified?
 
 ## 5. Risks
 
+- delivery_risks: <Material current open issues or explicit none>
+
 Which risks remain and what is their impact?
 
 ## 6. Required Next Step

package/generated/.agdf/control/templates/artefacts/SD.md

@@ -6,6 +6,8 @@ Gate approval: open
 Based on: PRD
 Date:
 Owner:
+Traceability contract: criteria-chain-v1
+Design Decisions contract: sd-decisions-v1
 
 ## 1. Solution Overview
 
@@ -17,7 +19,9 @@ Which existing modules, documents, services or owners remain authoritative?
 
 ## 3. Architecture Decisions
 
-Which design decisions are binding for implementation?
+Use one bullet per binding decision in the form `SDD-...: <decision>; rationale: <why>; consequence: <trade-off>`.
+Use stable IDs. If no binding design decision is needed, record one reasoned bullet beginning
+`none —`. The Acceptance Traceability table below must reference every listed ID and no others.
 
 ## 4. Integration Points
 
@@ -31,11 +35,35 @@ Which constraints must implementation preserve?
 
 Which evidence must TP and QA later collect?
 
-## 7. Risks And Open Questions
+## 7. Acceptance Traceability
+
+Copy each approved PRD `criterion_id` exactly once. Keep PRD as the source of product acceptance;
+record only its technical realization here. Point to the existing source of truth and accountable
+owner. Use stable `SDD-001` decision IDs where design decisions are needed; otherwise write
+`none — <why no new design decision is needed>`. Include compatibility, migration and material risk
+or a reasoned `none` for each criterion. Do not restate or silently change acceptance.
+
+| criterion_id | design_response | source_of_truth | design_decision_ids | compatibility_risk |
+|---|---|---|---|---|
+| <AC-001> | <design element> | <existing owner and authoritative module> | <SDD-001 or reasoned none> | <impact/mitigation or reasoned none> |
+
+## 8. Risks And Open Questions
 
 Which risks remain before task planning?
 
-## 8. Next Step
+## Design Decisions
+
+Use one table in this same SD. Every material architecture/design question is before_sd and
+must have status resolved, a concrete Resolution and named Owner before presentation. later_tp
+may defer execution/test/evidence detail with a named owner and concrete reason; it cannot hide
+binding architecture or product choices. With no material unknown, record a resolved applicability
+decision instead of leaving an empty table. Never remove the declaration/table to conceal gaps.
+
+| Decision | Timing | Status | Resolution | Owner |
+|---|---|---|---|---|
+| <unique decision> | before_sd | open | <answer needed or confirmed choice> | <named owner> |
+
+## 9. Next Step
 
 Review this solution design and approve only with:
 

package/generated/.agdf/control/templates/artefacts/TP.md

@@ -6,30 +6,65 @@ Gate approval: open
 Based on: SD
 Date:
 Owner:
+Traceability contract: criteria-chain-v1
+Planning Decisions contract: tp-decisions-v1
 
 ## 1. Task List
 
-| task_id | Task | Acceptance mapping | Evidence required |
+Use a stable task ID for each implementation or preparation task.
+
+| task_id | Task | Owner | Dependencies |
 |---|---|---|---|
-| T1 |  |  |  |
+| T-001 |  |  |  |
+
+## 2. Verification Traceability
+
+Map every approved PRD criterion and every SD design decision to one or more concrete scenarios.
+Reference IDs exactly; do not duplicate acceptance text. Each scenario has one task, a stable
+`SCN-001` ID, an observable expected result and a specific evidence source or artifact. Include
+boundary or failure scenarios where they matter to the criterion.
+
+| criterion_id | design_decision_id | task_id | scenario_id | expected_result | evidence |
+|---|---|---|---|---|---|
+| <AC-001> | <SDD-001 or reasoned none> | <T-001> | <SCN-001> | <observable result> | <test/report/log or manual observation> |
+
+## 3. Test Plan
+
+For each applicable verification scenario name its concrete execution prerequisites and failure action.
+
+| criterion_id | scenario_id | test_route | environment | prerequisites_permissions | owner | expected_evidence | unavailable_action |
+|---|---|---|---|---|---|---|---|
+| <AC-001> | <SCN-001> | <command/check> | <actual environment> | <required access> | <responsible owner> | <output/observation> | <action if unavailable> |
+
+## Planning Decisions
+
+Resolve each approved SD later_tp decision exactly once, using Source `SD: <exact decision label>`.
+Local execution choices use Source `TP`. Open rows block approval. With no material question, record
+one concrete resolved applicability row. Never defer product or design authority as planning detail.
 
-## 2. Test Plan
+| Decision | Source | Status | Resolution | Owner |
+|---|---|---|---|---|
+| <planning decision> | TP | open | <answer or concrete blocking context> | <named owner> |
 
-Which automated, manual or inspection checks must run?
+For a material question add `## Clarification Requests` with the existing quality.md normalized
+finding columns, and `## Clarification Details` with finding_id, planning_decision, question,
+blocking_reason, required_answer, owner, source_ref, resolution_evidence. Use the focused
+TP contract for exact source/evidence references, responsible-owner handoff and protected-source
+revision. Omit both clarification sections when no material finding exists.
 
-## 3. Brownfield Scope
+## 4. Brownfield Scope
 
 Which existing owners, modules or artefacts must be inspected before implementation?
 
-## 4. Out Of Scope
+## 5. Out Of Scope
 
 Which implementation work is explicitly not part of this TP?
 
-## 5. Risks And Blockers
+## 6. Risks And Blockers
 
 Which risks must block, revise or warn later QA?
 
-## 6. Next Step
+## 7. Next Step
 
 Review this task and test plan and approve only with:
 

package/generated/.agdf/control/templates/artefacts/UR.md

@@ -3,6 +3,8 @@
 Status: draft
 Gate: UR
 Gate approval: open
+Requirements clarification: open
+Preview requirement: none
 Date:
 Owner:
 
@@ -14,10 +16,19 @@ What user, business or operational problem should be solved?
 
 What outcome should become possible?
 
+## Affected Users
+
+Which people or roles experience the problem and benefit from the outcome?
+
 ## 3. Scope
 
 What is included in this first slice?
 
+Preserve explicitly requested clarification deliverables such as a UI preview: purpose, user task,
+relevant scenarios, required interaction/format and timing. Distinguish a required deliverable from
+an optional aid; do not invent a preview requirement. The later UX step retains a run-bound preview
+under `.agdf/control/artefacts/<run_id>/previews/`; UR authoring records the need only.
+
 ## 4. Non-Goals
 
 What is explicitly not part of this UR?
@@ -26,6 +37,9 @@ What is explicitly not part of this UR?
 
 How will we know the need is clear enough for PRD?
 
+For a requested preview, state what the user must be able to inspect or try and which questions
+it should clarify. These are planned review signals, not a claim that the preview already exists.
+
 ## 6. Existing Source Of Truth
 
 Which existing repository artefacts, docs, code paths or decisions must be respected?
@@ -39,3 +53,6 @@ Which questions must Brownfield Review, PRD, SD or later implementation-preparat
 Review this UR and approve only with:
 
 `Approval: UR`
+
+When a preview is required before PRD approval, name the later UX clarification step that must
+create, retain and review it. This does not authorize product implementation or approve the preview.

package/generated/.agdf/control/templates/artefacts/UX_INTENT_DEFINITION.md

@@ -43,6 +43,16 @@ grants no implementation permission. After PRD approval, the PRD is the sole pro
 
 ## 6. Decision Evidence
 
+When a UI preview or scenario walkthrough helps clarify behavior, retain the user task, relevant
+states, illustrative assumptions, actual observations and feedback in the fields below. Derive
+proposed PRD criteria from confirmed findings. Distinguish agent inspection from user observation
+and record untested interactions explicitly. Preserve any explicit UR preview requirement, including
+interaction and timing; an optional aid and a required deliverable have different completion needs.
+Record the run-local versioned preview path, source binding, file/asset digests, covered scenarios
+and validation limits in `evidence`. See `ux-intent-definition` for the canonical retention workflow.
+Missing required preview evidence keeps this analysis blocked. A preview grants no approval and
+proves no implementation or host behavior.
+
 - blocking_reason:
 - open_product_questions:
 - affected_outputs:

package/generated/.opencode/AGDF.md

@@ -1,130 +1,26 @@
-# AGDF OpenCode instructions
+# AGDF OpenCode bootstrap
 
-## Role
-You are operating in an OpenCode project configured with AGDF.
+<!-- AGDF-REQUEST-ACTIVATION-GUARD:START -->
+## Request Activation
 
-Use the native AGDF skills as workflow controls, not as documentation shortcuts.
-Your goal is trustworthy progress: reduce uncertainty, establish evidence, preserve artefacts, verify outcomes and make the next allowed step explicit.
+- `owner`: `request_activation_contract`
+- `path`: `meta/contracts/request-activation.md`
+- `policy_version`: `1`
+- `guard_fingerprint`: `sha256:af2f01f9e18a3ba1c520faf0691aa1cd4a4299bdfa027cf83651c5d14319bfdc`
 
-## Surface Convention
-OpenCode project skills do not have a plugin namespace.
+Decide effect from loaded instructions before AGDF action.
 
-Therefore generated OpenCode skill names use the AGDF prefix:
+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.
 
-- `agdf-delivery-path-search`
-- `agdf-brownfield-analysis`
-- `agdf-ux-intent-definition`
-- `agdf-clean-implementation-review`
-- `agdf-code-review`
-- `agdf-delivery-closeout`
-- `agdf-gate-check`
-- `agdf-qa-gate`
-- `agdf-release-or`
-- `agdf-task-plan-review`
+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.
 
-Do not remove that prefix in OpenCode-facing repository skills.
-Codex and Claude Code plugin surfaces use unprefixed skill names because their plugin namespace already carries `agdf`.
-## Mode Selection
-Default entry rule: a new user intent to build, add, change, extend, refactor or otherwise deliver something starts with `agdf-gate-check` unless it is clearly only a question, explanation, local inspection, or explicitly scoped review.
+Invocation proof: explicit user text/trusted ephemeral action, not discovery/selection, skill load, hooks, cwd, repo/control or prior runs.
 
-Use Quick Task Mode for questions, small reviews, local debugging and narrow fixes without new product semantics. Use Verified Change only after approved UR and Brownfield Review when the Runtime Contract's compact record can prove bounded ownership, clean-at-baseline paths, prohibited-impact absence and deterministic validation.
+Then pick one catalog route; non-authorizing, downstream checks remain.
+<!-- AGDF-REQUEST-ACTIVATION-GUARD:END -->
 
-Use Structured Delivery Mode for new capabilities, architecture, policy, persistence, release-critical work, formal artefacts or explicit approvals.
+## On-demand resources
 
-Any new product semantics, functional change or user-visible behaviour change requires a durable UR first.
-Persist it in `.agdf/control/` or link it from there to the target repository's authoritative source of truth before PRD, SD, TP, Brownfield Analysis or implementation.
-Treat approval text and durable artefact presence as separate checks for UR, PRD, SD, TP and QA report decisions.
-Do not infer approval from "ok", "go ahead", "do it", "approved", "continue", "leg los" or similar wording.
-Those phrases may express intent to proceed, but they do not unlock a gate unless the exact gate formula is present.
-Do not infer active scope from branch names, uncommitted workspace deltas, chat history or generated summaries when durable artefacts point elsewhere.
-If multiple active scopes are plausible, list the evidenced lines and route to `agdf-gate-check` or workstate clarification instead of choosing silently.
-After `Approval: UR`, run lightweight Brownfield Review before PRD when Brownfield, ownership, runtime, policy, persistence, architecture, UI or UX impact is possible.
-Brownfield Review must produce a Mode/Slice Decision: `quick_task`, `verified_change`, `structured_slice`, `structured_delivery` or `block`.
-That same review records the shared UI/UX impact classification. Run `agdf-ux-intent-definition` before
-PRD readiness for medium/high impact and for low impact with ambiguous mandatory PRD semantics. It is
-an internal analytical step, not a gate or product authority; a required blocked result keeps PRD
-readiness closed.
-Make that decision visible before coding or drafting later artefacts: state the selected path, scope reason, evidence and next required gate in the live control state or linked artefact.
-Do not assume the full PRD/SD/TP chain before that decision; use only as much gate depth as the reviewed change size justifies. A user-visible change is not automatically Verified Change eligible; any missing or ambiguous record condition escalates to the declared structured target before implementation.
-
-Quick Task Mode must still use the Runtime Contract mini-output: `result`, `evidence`, `risk`, `next_step`.
-Narrow defect work may use the Runtime Contract's Bug Lightweight Track only when a durable bug artefact or linked authoritative issue carries reproduction, actual behavior, expected behavior, fix boundary and evidence plan.
-Structured Delivery Mode must respect gates, reviews and closeout discipline.
-
-## Skill Routing
-| Skill | Use For | Boundary |
-|---|---|---|
-| `agdf-delivery-path-search` | high-impact planning decisions with several plausible next delivery steps before implementation | read-only advisory search; never grants gate permission or replaces gate-check |
-| `agdf-brownfield-analysis` | after gate-check permits Brownfield Review or implementation preparation, before non-trivial changes in existing systems | clarifies reuse, owners, risks and Mode/Slice Decision; never bypasses gate-check; Brownfield Review is not implementation permission |
-| `agdf-ux-intent-definition` | after approved UR and post-UR routing for medium/high UI/UX impact or ambiguous low-impact product semantics before PRD readiness | non-authorizing analytical PRD input; never creates product intent, gate permission, technical design or a parallel product source of truth |
-| `agdf-clean-implementation-review` | evidence dimension: inspect whether the solution is structurally clean | supports Quality Readiness; not a TP or QA substitute |
-| `agdf-code-review` | evidence dimension: review the actual diff for defects, regression and security findings | supports Quality Readiness; does not replace QA |
-| `agdf-delivery-closeout` | commit/PR-near handoff after QA/OR/UAT | never performs VCS actions automatically |
-| `agdf-gate-check` | new build/change intent, unclear approval, Structured Delivery, later-gate artefact requested | does not create later artefacts or skip Mode/Slice Decision after Brownfield Review |
-| `agdf-qa-gate` | sole final Quality Readiness decision | only instance for `pass | revise | block` |
-| `agdf-release-or` | auditable closeout for every relevant run | not a QA substitute |
-| `agdf-task-plan-review` | evidence dimension: verify whether the approved Task Plan was fulfilled | supports Quality Readiness; no final QA decision |
-
-Select exactly one primary skill first.
-Add more only when they cover a distinct concrete risk dimension.
-Do not choose `agdf-brownfield-analysis` as the first primary skill for a fresh "I want to build/change X" prompt unless `agdf-gate-check` or existing live AGDF control state already makes implementation preparation the next allowed action.
-Never jump directly from `Approval: UR`, implicit consent, or a generic "start" request to implementation. Route to Brownfield Review, then a visible Mode/Slice Decision with evidence, then the smallest safe next gate or Quick Task execution.
-
-## Runtime Contract
-For repeated output, gate, Quality Contract and Context Graph rules, use:
-
-- `contracts/task-target-resolution.md` for primary target authority before repository activation
-- `contracts/gate-transition.md` for gate terms, Brownfield routing and transition rules
-- `contracts/interaction.md` for status cards, approval orientation and native interaction
-- `contracts/modes.md` for delivery-mode boundaries
-- `contracts/quality.md` for quality and output discipline
-- `contracts/context-graph.md` for persistence and reconciliation
-- `contracts/control-scaffold.md` for run state, CLI verification and Delivery Map
-- `contracts/closeout.md` for relevant-run and closeout boundaries
-
-`agdf-runtime-contract.md` remains the compatibility manifest for these modules.
-
-Skills may include short reminders, but they must not carry a second complete rule or code table.
-
-## Durable Control State
-When the target repository uses the AGDF control scaffold, keep live control files under `.agdf/control/`.
-Use templates as starting points only.
-
-Do not let chat history become the source of truth for gate state, approvals, evidence, backlog status or durable Brownfield knowledge.
-
-AGDF is agent-native first and CLI-verifiable by design: read the live control state, apply the active skill and make the next allowed step explicit.
-Use `init` only when durable control state is explicitly requested, the repository already uses `.agdf/control/` as its live AGDF working state, or a deterministic CLI/CI setup path is being executed.
-Use `doctor --json`, `gate-check --json` or `delivery-map --json` as deterministic validators for CI, PR evidence, regression checks or audit trails, not as a substitute for the router or skills.
-At run closeout, route new durable knowledge explicitly as `context_graph`, `sot_registry`, `scope_artifact`, `open_questions` or `none`.
-
-## Closeout
-For Quick Task Mode, close with the Runtime Contract mini-output only:
-
-- `result`
-- `evidence`
-- `risk`
-- `next_step`
-
-For relevant runs that change durable state, code, artefacts or gate status:
-
-- run relevant checks or state the test gap
-- never commit, push or open a PR automatically
-- include exactly one `Next step:`
-- include exactly one `Quality outlook:`
-
-
-## OpenCode Files
-
-- OpenCode loads this file through `opencode.json` `instructions`.
-- AGDF for OpenCode has a global npm/native-skill discoverability layer and this repository-local governance surface.
-- The global plugin and skills do not replace this file, `.opencode/skills/` or `.agdf/control/`; repository files remain the AGDF source of truth.
-- Native OpenCode skills live under `.opencode/skills/` and use the `agdf-` prefix.
-- The generated AGDF skills are loaded on demand through OpenCode's native `skill` tool; they are not parallel subagents or primary menu agents.
-- For new build/change intent or unclear approval, load the `agdf-gate-check` skill before later artefacts or implementation.
-- The AGDF OpenCode plugin is loaded from npm through `opencode.json` `plugin: ["create-agdf"]`.
-- Use `npx --yes @agdf/cli@latest opencode-status --json` to verify global config, package loadability, global native-skill completeness, active session signals and repository surface presence separately.
-- OpenCode permissions allow the built-in `question` tool, keep `edit` and `bash` on explicit approval and allow the generated `agdf-*` skills explicitly; global adapters use the `agdf-global-*` namespace.
-- An explicit user `permission.question: deny` remains authoritative and selects the exact-text AGDF fallback; never convert an OpenCode permission outcome or auto mode into gate approval.
-- Shared output and gate rules live in `.opencode/agdf-runtime-contract.md`.
-- Do not paste full control files, templates or artefact bodies into chat unless the user explicitly asks for the full content; summarize and link paths instead.
-- OpenCode plugin hooks (`tool.execute.before`) do not intercept tool calls from subagents spawned via the `task` tool (issue #5894, PR #36238 open). AGDF enforcement through plugin hooks applies to primary-agent tool calls only; in the subagent path, AGDF governance is auditing-only. Do not route work to a subagent to bypass a primary-agent gate; verify subagent results through the canonical validator after the subagent returns.
+- After positive Request Activation, load the selected native AGDF skill; governed delivery starts with `agdf-gate-check`.
+- Load the full router from the sibling `agdf-agent-router.md` only when routing detail is needed.
+- Focused contracts and the runtime contract remain available from the sibling `contracts/` directory and `agdf-runtime-contract.md`.

package/generated/.opencode/README.md

@@ -5,10 +5,11 @@ These files were generated from the AGDF source repository for OpenCode.
 - The globally installed npm plugin `create-agdf` owns the shared OpenCode runtime surface.
 - A repository is AGDF-active when `.agdf/control/config.json` is valid; this activation does not copy `.opencode/` assets.
 - Global adapters use `agdf-global-*` to avoid same-name masking by supported legacy local `agdf-*` skills.
+- The eager `AGDF.md` is a micro-bootstrap; `agdf-agent-router.md` retains the full on-demand router.
 - Preserve an explicit user `permission.question: deny`; AGDF then uses exact textual approval and never interprets OpenCode permission outcomes or auto mode as gate authority.
-- For new build/change intent or unclear approval, load `agdf-global-gate-check` through OpenCode's native `skill` tool.
+- After positive Request Activation selects actual delivery work, load `agdf-global-gate-check` through OpenCode's native `skill` tool. Unclear approval alone never activates AGDF.
 - Use `npx --yes @agdf/cli@latest opencode-status --json` to distinguish global hook/native-skill configuration, package loadability, durable activation, legacy compatibility and session activity.
-- For deterministic ready-gate rendering, prefer an installed `agdf gate-check --approval-envelope`; reserve `agdf gate-check --json` for native-adapter input, automation or audit evidence and use `npx ...@latest` only for bootstrap, refresh or a missing local executable.
+- For a read-only ready-gate preview, use installed `agdf gate-check --approval-envelope`; prepare the actual approval with `run-present` before asking the user. Reserve `agdf gate-check --json` for native-adapter input, automation or audit evidence and use `npx ...@latest` only for bootstrap, refresh or a missing local executable.
 - The globally installed runtime contract is the shared gate and output contract.
 
 ## Skills
@@ -19,7 +20,11 @@ These files were generated from the AGDF source repository for OpenCode.
 - `agdf-delivery-closeout`
 - `agdf-delivery-path-search`
 - `agdf-gate-check`
+- `agdf-prd-definition`
 - `agdf-qa-gate`
 - `agdf-release-or`
+- `agdf-sd-definition`
 - `agdf-task-plan-review`
+- `agdf-tp-definition`
+- `agdf-ur-definition`
 - `agdf-ux-intent-definition`