create-agdf 0.14.5 → 0.20.0

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

@@ -0,0 +1,135 @@
+# Brownfield Review: <Title>
+
+Gate: Brownfield Review
+Type: Brownfield Review
+Mode: `post_ur_review`
+Status: `draft | done | not_applicable | superseded`
+
+## Run
+
+- run_id:
+- related_ur:
+- current_gate:
+- reviewer:
+- reviewed_at:
+
+## Objective
+
+What approved UR scope is being sized and routed?
+
+## UI / UX Impact Routing
+
+- delivery_context: `greenfield | brownfield`
+- ui_ux_impact: `none | low | medium | high`
+- ui_ux_impact_reason:
+- ux_intent_definition_required: `yes | no`
+- ux_intent_definition_result: `ready | blocked | not_applicable`
+
+Use the single classification contract in `meta/contracts/gate-transition.md`. A required `blocked`
+result prevents PRD readiness. Greenfield explicitly marks existing-system evidence not applicable;
+Brownfield cites repository evidence.
+
+## Existing-System View
+
+| Area | Existing owner or artefact | Evidence | Impact |
+|---|---|---|---|
+| Product semantics |  |  | `none | low | medium | high` |
+| Source of truth |  |  | `none | low | medium | high` |
+| Runtime path |  |  | `none | low | medium | high` |
+| UI / UX |  |  | `none | low | medium | high` |
+| Persistence / data |  |  | `none | low | medium | high` |
+| 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`
+- required_next_gate: `none | PRD | SD | TP | Brownfield Analysis`
+- scope_reason:
+- evidence:
+- transparency_note:
+
+## Structured Depth Evidence
+
+- depth_policy_version: `1`
+- depth_facts_status: `complete | missing | conflicting | not_applicable`
+- primary_reason_code:
+- decisive_full_depth_triggers:
+- rejected_alternative:
+- missing_or_conflicting_facts:
+- depth_evidence_refs:
+
+Use `not_applicable` only when an unchanged Quick/Compact or Verified Change path is selected before
+Structured Depth. A positive structured decision requires complete facts. Missing or conflicting
+decisive facts without an already-evidenced full-depth trigger persist `decision: block` and name
+the evidence owner and precise Brownfield/Mode-Slice re-evaluation action.
+
+| check_id | result | evidence |
+|---|---|---|
+| coherent_outcome | `pass | fail | unknown | not_applicable` |  |
+| authority_boundary | `pass | fail | unknown | not_applicable` |  |
+| owner_consumer_coordination | `pass | fail | unknown | not_applicable` |  |
+| full_depth_impacts_absent | `pass | fail | unknown | not_applicable` |  |
+| migration_propagation_bounded | `pass | fail | unknown | not_applicable` |  |
+| failure_recovery_local | `pass | fail | unknown | not_applicable` |  |
+| independently_acceptable | `pass | fail | unknown | not_applicable` |  |
+
+## PRD / SD Open Questions
+
+| Question | Required gate | Impact |
+|---|---|---|
+|  | `none | PRD | SD | TP` | `warn | revise | block` |
+
+## Context Graph Impact
+
+- context_graph_impact: `none | link_only | update_existing_node | new_node_required | sot_drift`
+- context_graph_refs:
+- context_graph_required_action: `none | link | update | create | resolve_drift`
+- context_graph_gate_effect: `none | warning | revise | block`
+- context_graph_evidence:
+
+## Next Permissible Step
+
+- next_allowed_action:
+- forbidden_until_then:
+
+## Quality Outlook
+
+- quality_outlook:

package/generated/plugins/copilot/agdf/control/templates/artefacts/OR.md

@@ -0,0 +1,125 @@
+# OR: <Title>
+
+Gate: OR
+Type: Orchestration Report
+Report mode: `OR-lite | OR-full`
+Status: `draft | done | superseded`
+
+## Run
+
+- run_id:
+- related_ur:
+- related_prd:
+- related_sd:
+- related_tp:
+- related_qa_report:
+- mode_slice_decision:
+- current_gate:
+- decision: `pass | revise | block | in_progress`
+
+## Gate State
+
+| Gate or step | Status | Evidence |
+|---|---|---|
+| UR |  |  |
+| Brownfield Review |  |  |
+| Mode/Slice Decision |  |  |
+| PRD |  |  |
+| SD |  |  |
+| TP |  |  |
+| Brownfield Analysis |  |  |
+| CD+Tests |  |  |
+| CR |  |  |
+| QA |  |  |
+| UAT |  |  |
+
+## Run Status Card
+
+This is a compact projection of the control state. It does not replace gate-check, QA, OR or approvals.
+
+| Run status | Value |
+|---|---|
+| Status |  |
+| Current gate |  |
+| Allowed now |  |
+| Blocked by |  |
+| Missing approval |  |
+| Next step |  |
+| Quality outlook |  |
+
+## Delivered
+
+| Item | Evidence |
+|---|---|
+|  |  |
+
+## Not Delivered / Intentionally Deferred
+
+| Item | Reason | Next owner or gate |
+|---|---|---|
+|  |  |  |
+
+## Evidence
+
+| Evidence | Source | Covers | Strength |
+|---|---|---|---|
+|  |  |  | `direct | indirect | weak` |
+
+## Missing Evidence
+
+| Missing evidence | Impact | Required next step |
+|---|---|---|
+|  | `warn | revise | block` |  |
+
+## Risks And Open Items
+
+| Risk or open item | Impact | Owner or mitigation |
+|---|---|---|
+|  | `warn | revise | block` |  |
+
+## Parent Reconciliation Handoff
+
+Optional evaluated projection. Keep Child delivery status separate.
+
+- outcome: `resolved | not_applicable | open`
+- target_run_id:
+- disposition: `not_applicable | action_required | accepted_open`
+- evidence:
+- missing_evidence: `none` or concrete missing proof
+- next_action: `none` or exactly one action
+
+## Programme Aggregation Readiness
+
+Optional Parent/programme projection. It is evidence, not approval.
+
+- startable: `true | false`
+- final_ready: `true | false`
+- acceptance_ref:
+- evidence:
+- missing_evidence:
+- next_action:
+
+## Context Graph Impact
+
+- 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:
+
+## Knowledge Persistence Decision
+
+- memory_target: `context_graph | sot_registry | scope_artifact | open_questions | none`
+- memory_reason:
+- memory_refs:
+
+## Next Permissible Step
+
+- next_allowed_action:
+- required_approval:
+- forbidden_until_then:
+
+## Approval
+
+OR does not approve later gates. It records the next permissible step.

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

@@ -0,0 +1,113 @@
+# PRD: <Title>
+
+Status: draft
+Gate: PRD
+Gate approval: open
+Based on: UR
+Date:
+Owner:
+Traceability contract: criteria-chain-v1
+
+## 1. Product Scope
+
+What exactly must be delivered?
+
+## 2. UX Intent And Success
+
+- ui_ux_impact: none | low | medium | high
+- ux_intent_definition: <ready analysis reference | directly defined low-impact semantics | justified not_applicable>
+- primary_user_intent:
+- success_signal:
+- primary_decision_or_action:
+
+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:
+
+| working_mode | effective_state | visible_state_types | effective_state_authority | primary_state_presentation_owner |
+|---|---|---|---|---|
+|  |  |  |  |  |
+
+Product/system authority decides what is effectively true. Presentation ownership identifies the
+primary surface that communicates state and next action. Technical storage, derivation and component
+ownership remain Solution Design concerns.
+
+## 4. Activation, Blockers, Recovery And Transitions
+
+- activation_and_deactivation:
+- blockers_and_visible_next_actions:
+- recovery_paths: <include visible retry for recoverable transient failure>
+- relevant_state_transitions: <trigger, source, target, visible feedback, next action, failure/rollback>
+
+## 5. Acceptance Criteria
+
+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
+
+What remains out of scope?
+
+## 7. Users And Roles
+
+Who is affected and who decides?
+
+## 8. Constraints
+
+Which business, operational, legal, security or compatibility constraints apply?
+
+## 9. Evidence Requirements
+
+Which evidence must later support QA?
+
+## 10. Risks And Open Questions
+
+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
+
+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/plugins/copilot/agdf/control/templates/artefacts/QA_REPORT.md

@@ -0,0 +1,44 @@
+# QA Report: <Title>
+
+Status: draft
+Gate: QA
+Gate approval: open
+Based on: TP, implementation evidence, task-plan review
+Date:
+Owner:
+
+## 1. QA Decision
+
+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
+
+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
+
+What is the next permitted action?
+
+## 7. Gate Approval
+
+Approve this QA decision only with:
+
+`Approval: QA`

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

@@ -0,0 +1,70 @@
+# SD: <Title>
+
+Status: draft
+Gate: SD
+Gate approval: open
+Based on: PRD
+Date:
+Owner:
+Traceability contract: criteria-chain-v1
+Design Decisions contract: sd-decisions-v1
+
+## 1. Solution Overview
+
+How will the approved PRD be solved?
+
+## 2. Ownership And Source Of Truth
+
+Which existing modules, documents, services or owners remain authoritative?
+
+## 3. Architecture Decisions
+
+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
+
+Which APIs, data flows, UI surfaces, jobs, queues or external systems are affected?
+
+## 5. Constraints And Compatibility
+
+Which constraints must implementation preserve?
+
+## 6. Test And Evidence Strategy
+
+Which evidence must TP and QA later collect?
+
+## 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?
+
+## 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:
+
+`Approval: SD`

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

@@ -0,0 +1,71 @@
+# TP: <Title>
+
+Status: draft
+Gate: TP
+Gate approval: open
+Based on: SD
+Date:
+Owner:
+Traceability contract: criteria-chain-v1
+Planning Decisions contract: tp-decisions-v1
+
+## 1. Task List
+
+Use a stable task ID for each implementation or preparation task.
+
+| task_id | Task | Owner | Dependencies |
+|---|---|---|---|
+| 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.
+
+| Decision | Source | Status | Resolution | Owner |
+|---|---|---|---|---|
+| <planning decision> | TP | open | <answer or concrete blocking context> | <named owner> |
+
+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.
+
+## 4. Brownfield Scope
+
+Which existing owners, modules or artefacts must be inspected before implementation?
+
+## 5. Out Of Scope
+
+Which implementation work is explicitly not part of this TP?
+
+## 6. Risks And Blockers
+
+Which risks must block, revise or warn later QA?
+
+## 7. Next Step
+
+Review this task and test plan and approve only with:
+
+`Approval: TP`

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

@@ -0,0 +1,58 @@
+# UR: <Title>
+
+Status: draft
+Gate: UR
+Gate approval: open
+Requirements clarification: open
+Preview requirement: none
+Date:
+Owner:
+
+## 1. Problem
+
+What user, business or operational problem should be solved?
+
+## 2. Goal
+
+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?
+
+## 5. Acceptance Signals
+
+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?
+
+## 7. Risks And Unknowns
+
+Which questions must Brownfield Review, PRD, SD or later implementation-preparation Brownfield Analysis clarify?
+
+## 8. Next Step
+
+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/plugins/copilot/agdf/control/templates/artefacts/UX_INTENT_DEFINITION.md

@@ -0,0 +1,61 @@
+# UX Intent Definition: <Title>
+
+Status: draft | ready | blocked | not_applicable
+Decision: ready | blocked | not_applicable
+Based on: approved UR and post-UR routing evidence
+Date:
+Owner:
+
+This is non-authorizing analytical input. It is not a user-gate artefact, carries no approval and
+grants no implementation permission. After PRD approval, the PRD is the sole product authority.
+
+## 1. Routing Evidence
+
+- delivery_context: greenfield | brownfield
+- ui_ux_impact: none | low | medium | high
+- ui_ux_impact_reason:
+- ux_intent_definition_required: yes | no
+
+## 2. Intent And Success
+
+- primary_user_intent:
+- success_signal:
+- primary_decision_or_action:
+
+## 3. Working Modes And State
+
+- working_modes:
+- effective_state_by_mode:
+- visible_state_types:
+- effective_state_authority_by_mode:
+- primary_state_presentation_owner_by_mode:
+
+## 4. Activation, Blockers, Recovery And Transitions
+
+- activation_paths:
+- blockers:
+- recovery_paths:
+- relevant_state_transitions:
+
+## 5. Proposed PRD Acceptance Criteria
+
+- proposed_prd_acceptance_criteria:
+
+## 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:
+- evidence:
+- missing_evidence:
+- required_next_step: