create-agdf 0.7.0 → 0.7.2

package/generated/plugins/agdf/meta/agdf-plugin.definition.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "Arndt Gold",
   "description": "Codex-first operating system for governed AI-assisted delivery.",
@@ -35,7 +35,7 @@
       "Write"
     ],
     "defaultPrompt": [
-      "Evaluate whether AGDF is appropriate for this repository and request. Explain its purpose, practical value, governance overhead, and fit for the project's risk level. Recommend the smallest suitable AGDF path before proposing implementation.",
+      "Assess whether AGDF is proportionate for this repository and request before proposing any implementation. Explain AGDF's purpose and practical benefits, weigh governance overhead against the project's delivery risk, and recommend the lightest suitable path — or explicitly advise against AGDF where it would add more process than value.",
       "Start this request under AGDF governance.",
       "Create durable AGDF control state for this repository.",
       "Close this delivery run with an auditable AGDF report."
@@ -57,6 +57,7 @@
     "instructionsFileName": "AGDF.md",
     "npmPackage": "create-agdf",
     "permissions": {
+      "question": "allow",
       "edit": "ask",
       "bash": "ask",
       "skill": {
@@ -64,6 +65,35 @@
       }
     }
   },
+  "interactions": {
+    "fallback": "exact_text",
+    "surfaces": {
+      "codex": {
+        "questionAdapter": "request_user_input",
+        "availability": "when_callable",
+        "gateSafety": "omit_auto_resolution",
+        "technicalPermissionOwner": "codex_host"
+      },
+      "claude": {
+        "questionAdapter": "AskUserQuestion",
+        "availability": "when_no_auto_continue_timeout",
+        "gateSafety": "no_timeout_or_hook_supplied_answer",
+        "technicalPermissionOwner": "claude_host"
+      },
+      "opencode": {
+        "questionAdapter": "question",
+        "availability": "when_permission_question_allows",
+        "gateSafety": "preserve_explicit_deny",
+        "technicalPermissionOwner": "opencode_host"
+      },
+      "fallback": {
+        "questionAdapter": "exact_text",
+        "availability": "always",
+        "gateSafety": "wait_for_deliberate_user_input",
+        "technicalPermissionOwner": "host_specific"
+      }
+    }
+  },
   "skillSet": [
     {
       "slug": "delivery-path-search",

package/generated/plugins/agdf/meta/agdf-runtime-contract.md

@@ -27,6 +27,20 @@ Use this compact output shape when no formal gate artefact is required:
 
 Do not add a separate `Quality outlook` line for pure Quick Tasks unless the task became a relevant run.
 
+### Verified Change
+
+`verified_change` is a compact, fail-closed path for a bounded user-visible change with one canonical owner and deterministic proof. It is neither a prose exception nor a new user approval gate.
+
+After `Approval: UR`, Brownfield Review may select `verified_change` only when a durable `VERIFIED_CHANGE.md` record can prove all of the following before implementation:
+
+1. exactly one repository-relative canonical owner and bounded source/derived paths;
+2. no gate, permission, security, persistence, architecture, external API, CLI or release behavior impact;
+3. deterministic propagation when derived paths exist, plus at least one deterministic validation command;
+4. tracked and untracked worktree baseline paths captured before eligibility, with no candidate path already dirty; and
+5. an explicit `structured_slice` or `structured_delivery` escalation target.
+
+The record is the compact eligibility, execution and mini-closeout artefact. A missing, failed, unknown or ambiguous field/check must fail closed: mark the record `escalated` and continue at its declared structured target. Unrelated paths already dirty at baseline remain isolated; newly introduced unlisted paths invalidate the compact path. An executed record requires passing validation evidence and, where applicable, passing propagation evidence.
+
 ### Non-Normative Trivial Change Boundary
 
 A `quick_task` whose entire diff stays fully outside all of the following paths may close using only
@@ -68,10 +82,10 @@ the full existing ceremony unchanged:
 When a run needs an operational status view, use the Run Status Card as a compact projection of existing control state.
 It must not introduce a second gate model or override `gate-check`, `delivery-map`, QA, OR, or user approvals.
 
-- `mode`: `quick_task | structured_delivery | unknown`
+- `mode`: `quick_task | verified_change | structured_delivery | unknown`
 - `status`: `open | blocked | pass | warn | revise | block | in_progress`
 - `current_gate`: current user gate or internal step
-- `mode_slice_decision`: `undecided | quick_task | structured_slice | structured_delivery | block`
+- `mode_slice_decision`: `undecided | quick_task | verified_change | structured_slice | structured_delivery | block`
 - `allowed_now`: outputs or actions currently permitted
 - `forbidden_now`: outputs or actions currently forbidden
 - `blocking_condition`: current blocker or `none`
@@ -232,7 +246,7 @@ section or any other existing line.
 ## Gate Rules
 
 - User gates: `UR -> PRD -> SD -> TP -> QA -> UAT`
-- Internal mandatory steps: `Brownfield Review -> Mode/Slice Decision -> Brownfield Analysis -> CD+Tests -> CR -> OR`
+- Internal mandatory steps: `Brownfield Review -> Mode/Slice Decision -> Verified Change Execution | Brownfield Analysis -> CD+Tests -> CR -> OR`
 - On the approved-TP path, `CD+Tests` and `CR` are satisfied only by `done`; `not_applicable` may satisfy Brownfield Review or Brownfield Analysis, but it must not bypass implementation/test evidence or mandatory Code Review.
 - Exact approval formula: `Approval: <GateName>`
 - Legacy alias: `Freigabe: <GateName>` may be accepted when reviewing older German runs, but all new outputs must use `Approval: <GateName>`.
@@ -254,6 +268,58 @@ section or any other existing line.
 - `release-or` reports the run, but does not replace QA or produce the operative commit/PR handoff.
 - `delivery-closeout` owns the operative Git handoff text when QA/OR/UAT state allows it.
 
+## Native Interaction Contract
+
+Native host controls improve how a decision is presented; they do not create a second approval model or authority source.
+
+Every AGDF interaction belongs to exactly one semantic kind:
+
+- `clarification`: asks for missing intent or a choice that does not itself authorize a gated transition.
+- `tool_permission`: requests host-owned authority for a command, file change, network access, external path, app action or comparable technical side effect.
+- `gate_approval`: requests deliberate user input for the one current AGDF user gate after its durable artefact and selected run are ready.
+
+The semantic interaction envelope is:
+
+```text
+interaction_kind: clarification | tool_permission | gate_approval
+surface: codex | claude | opencode | fallback
+run_id: required for gate_approval
+current_gate: required for gate_approval
+prompt: required
+options: required for a structured question
+effects: required when the interaction can cause side effects
+required_evidence: required for gate_approval
+auto_resolution: forbidden for gate_approval
+response_origin: deliberate_user_input for gate_approval
+```
+
+This envelope is not a new persisted record. The selected canonical `RUN_STATE.md` and existing artefact chain remain the durable authority.
+
+Before presenting `gate_approval`, the agent must:
+
+1. resolve exactly one selected run;
+2. run the canonical gate evaluation and confirm that the current gate's durable artefact is present and ready;
+3. ask exactly one gate question that identifies `run_id` and `current_gate` and offers the exact approving value `Approval: <GateName>` plus bounded revise and cancel/decline outcomes;
+4. wait for deliberate user input without a timeout, default, preselection, hook-supplied answer or agent-to-agent substitute;
+5. re-run canonical gate evaluation against the same `run_id` and expected gate immediately before persistence;
+6. reject missing evidence, ambiguous or wrong run, wrong gate, stale state and any response that is no longer valid;
+7. persist an accepted approval only through the existing control-state workflow.
+
+A free-form native response is valid only when the existing exact-approval validator accepts it for the current gate after revalidation. Revise, decline and cancel outcomes never advance a gate.
+
+Surface adapter rules:
+
+| Surface | Native question adapter | Gate-safe use | Technical permission boundary |
+|---|---|---|---|
+| Codex | native `request_user_input` or equivalent short-question control when callable | one gate question; omit auto-resolution; otherwise use exact text | Codex command, edit, network, external-directory and app-action approvals remain host-owned `tool_permission`. |
+| Claude Code | `AskUserQuestion` | use only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; otherwise use exact text | Claude permissions and `ExitPlanMode` are not AGDF approval. |
+| OpenCode | built-in `question` | use with exact approval/revise/cancel options when `permission.question` permits it; explicit user deny selects exact-text fallback | `once`, `always`, `reject`, permission suggestions and auto mode are technical outcomes only. |
+| Fallback or non-interactive | concise exact text | wait for a new explicit user response; never synthesize or auto-resolve one | Host-specific technical permission remains separate. |
+
+Native structured questions are for real decision points. Prefer repository inspection over clarification and do not show them for status reporting, discoverable facts, routine read-only work or repeated non-ready gate prompts.
+
+Exact textual approvals remain canonical and fully supported on every surface. If native capability availability or safety is unknown, use the textual fallback. Host permission, plan approval, native question presentation, timeout/default behavior, hook output and agent messages never carry AGDF gate authority by themselves.
+
 ## Brownfield Review After G-00
 
 After an approved and durable UR, perform a lightweight `Brownfield Review` before PRD when Brownfield, UI, UX, admin, runtime, policy, persistence, architecture, ownership or source-of-truth impact is possible.
@@ -264,7 +330,7 @@ It is the sizing and routing step that decides how much later gate discipline is
 Its output is limited to:
 
 - workstream or follow-up-slice classification
-- `Mode/Slice Decision`: `quick_task | structured_slice | structured_delivery | block`
+- `Mode/Slice Decision`: `quick_task | verified_change | structured_slice | structured_delivery | block`
 - affected existing owners, source-of-truth artefacts, contracts, policies, runtime paths or tests
 - reuse-before-create risks and parallel-structure risks
 - open questions that PRD or SD must resolve
@@ -273,6 +339,7 @@ Its output is limited to:
 Mode/Slice Decision rules:
 
 - `quick_task`: use only when Brownfield Review shows a narrow local change, no new product semantics beyond the approved UR, no architecture/policy/persistence/contract expansion, and evidence is sufficient to proceed with a small implementation plus relevant checks.
+- `verified_change`: use only when the compact record can prove one canonical owner, bounded clean-at-baseline paths, no prohibited impact, deterministic propagation/validation and a structured escalation target. It skips later approvals only after every condition is evidenced and machine-validated.
 - `structured_slice`: use when some formal artefacts are needed, but they can stay intentionally small and scoped to the approved slice.
 - `structured_delivery`: use when the change has broad product, architecture, runtime, policy, persistence, release or cross-owner impact.
 - `block`: use when ownership, SoT, impact, evidence or product direction is not clear enough to choose a safe path.
@@ -287,8 +354,12 @@ This table is the canonical transition model. Skills may reference it, but must
 |---|---|---|---|---|
 | No approved UR | `UR` | clarify user need, formulate and persist UR, request `Approval: UR` | PRD, SD, TP, Brownfield Analysis, implementation, QA, release | `Approval: UR` |
 | `UR` approved and UR artefact persisted or linked, Brownfield Review missing | `Brownfield Review` | classify workstream, existing owners, SoT, reuse risks, change size and PRD/SD open questions; mark review done or not_applicable | PRD, SD, TP, implementation, QA, release | none |
-| Brownfield Review done or not_applicable, Mode/Slice Decision missing or incomplete | `Mode/Slice Decision` | decide `quick_task`, `structured_slice`, `structured_delivery` or `block`; record scope reason, evidence and required next gate depth | PRD, SD, TP, implementation, QA, release | none |
+| Brownfield Review done or not_applicable, Mode/Slice Decision missing or incomplete | `Mode/Slice Decision` | decide `quick_task`, `verified_change`, `structured_slice`, `structured_delivery` or `block`; record scope reason, evidence and required next gate depth | PRD, SD, TP, implementation, QA, release | none |
 | Mode/Slice Decision is `quick_task` | `Quick Task Execution` | implement only the narrow approved UR scope, run relevant checks, record evidence and OR-lite when the run is relevant | broad PRD/SD/TP by ritual, scope expansion, QA or release claims without evidence | none |
+| Mode/Slice Decision is `verified_change`, record missing/draft/invalid | `Verified Change Execution` | create or repair compact record, capture baseline and prove eligibility with doctor/gate-check | implementation, QA, UAT, release | none |
+| Verified Change record is `eligible` | `Verified Change Execution` | implement only declared paths, run declared propagation/validation, record mini-closeout | unlisted paths, prohibited impacts, QA/UAT/release claims | none |
+| Verified Change record is `executed` | `OR` | use mini-closeout and offer delivery closeout when requested | PRD/SD/TP/QA/UAT by ritual; automatic VCS actions | none |
+| Verified Change record is `escalated` | `PRD` | draft the PRD for declared `structured_slice` or `structured_delivery` escalation target | implementation through Verified Change | `Approval: PRD` |
 | Mode/Slice Decision is `structured_slice` or `structured_delivery`, PRD missing or draft | `PRD` | draft/refine PRD at the smallest justified depth, define scope, acceptance criteria and non-goals, persist/link PRD, request `Approval: PRD` | SD, TP, implementation-preparation Brownfield Analysis, implementation, QA, release | `Approval: PRD` |
 | `PRD` approved and PRD artefact persisted or linked, SD missing or draft | `SD` | draft/refine Solution Design, ownership and architecture, persist/link SD, request `Approval: SD` | TP, implementation, QA, release | `Approval: SD` |
 | `SD` approved and SD artefact persisted or linked, TP missing or draft | `TP` | draft/refine Task/Test Plan, task IDs, evidence plan, persist/link TP, request `Approval: TP` | implementation, QA, release | `Approval: TP` |

package/generated/plugins/agdf/meta/agdf-tenets.md

@@ -23,6 +23,11 @@ you *MUST* honor the following **GENERIC TENETS**:
     and tooling maintenance when no new product meaning, user capability,
     architecture, policy or persistence decision is introduced.
 
+    Verified Change may handle a bounded user-visible canonical metadata or
+    copy change only after approved UR and Brownfield Review when the Runtime
+    Contract record proves one owner, clean-at-baseline paths, no prohibited
+    impact and deterministic validation; every uncertainty escalates.
+
 -   **Fail Closed**:
     When a necessary approval, input, or quality statement is missing,
     the process must stop or demand revision.

package/generated/plugins/agdf/skills/gate-check/SKILL.md

@@ -52,6 +52,32 @@ npx --yes @agdf/cli@latest delivery-map --json
 
 The CLI reports are validators and JSON evidence, not the primary user experience, not a required ritual for normal work and not a second rule system. If a report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
 
+## Native Interaction Path
+
+Use the Runtime Contract's Native Interaction Contract to classify every candidate interaction as `clarification`, `tool_permission` or `gate_approval` before selecting a host control.
+
+Prefer inspection over asking. Do not invoke a structured question for status reporting, facts available in the repository, routine read-only work or a gate that is not ready. Do not repeatedly prompt for the same non-ready gate.
+
+For a ready `gate_approval`:
+
+1. Resolve exactly one selected run and evaluate the current gate.
+2. Confirm the required durable artefact is present and ready before presenting a question.
+3. Ask exactly one question that names the selected `run_id` and `current_gate`.
+4. Offer the exact approving option `Approval: <GateName>` plus bounded revise and cancel/decline outcomes.
+5. Use the surface adapter declared in the canonical plugin definition only when it can wait for deliberate input without auto-resolution; otherwise request the same exact approval in concise text.
+6. Re-run gate evaluation for the same run and expected gate after the response and immediately before persistence.
+7. Reject a missing artefact, ambiguous or wrong run, wrong gate, stale expected gate, timeout/default, hook-supplied answer, agent message, technical permission outcome or plan approval.
+8. Persist accepted input only through the existing control-state workflow.
+
+Surface behavior:
+
+- Codex: use the native short-question/request-user-input control when callable, ask one gate question and omit auto-resolution.
+- Claude Code: use `AskUserQuestion` only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; otherwise use exact text. Claude permissions and `ExitPlanMode` remain separate.
+- OpenCode: use built-in `question` when permitted. Preserve explicit `permission.question` denial and use exact text in that case. `once`, `always`, `reject` and auto mode never become gate input.
+- Other, unavailable or non-interactive surfaces: use exact textual approval and wait for a new explicit user response.
+
+A free-form response must still exactly match the current gate's approval formula after revalidation. Revise, decline and cancel never advance the gate. Native presentation, host permission and plan approval are inputs or separate authority domains, never durable AGDF authority.
+
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.
 2. The earliest blocking gate wins.
@@ -72,6 +98,7 @@ The CLI reports are validators and JSON evidence, not the primary user experienc
 17. If multiple active scopes are plausible, list the evidenced competing lines and keep the current step at scope clarification or the earliest common safe gate.
 18. When maintaining `MASTER_BACKLOG.md`, use its canonical compact columns, readable status labels and document-relative Markdown links. Do not expose raw long paths or internal snake_case statuses in the human-facing table. The canonical status/artefact label vocabulary is defined in the AGDF control scaffold's `MASTER_BACKLOG.md` template Rules section; do not invent other labels.
 19. Preserve legacy backlog compatibility through the CLI parser; do not create a second surface-specific backlog format.
+20. Native interaction must follow the Runtime Contract's interaction envelope, readiness check, deliberate-user-input requirement and post-response revalidation boundary.
 
 ## Gate Evaluation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [
@@ -25,9 +25,11 @@
     "test:delivery-path-search-unit": "node ./scripts/delivery-path-search-unit-test.js",
     "test:delivery-path-search-generator": "node ./scripts/delivery-path-search-generator-test.js",
     "test:control-state": "node ./scripts/control-state-test.js",
+    "test:verified-change": "node ./scripts/verified-change-test.js",
+    "test:runtime-integrity-negative": "node ./scripts/runtime-integrity-negative-test.js",
     "test:release-bootstrap": "node ./scripts/release-bootstrap-smoke-test.js",
     "test:routing": "npm run sync-package-assets && node ./scripts/test-routing.js",
-    "smoke-test": "npm run sync-package-assets && npm run test:control-state && npm run test:delivery-path-search && npm run test:delivery-path-search-unit && npm run test:delivery-path-search-generator && node ./scripts/smoke-test.js && node ./scripts/test-routing.js",
+    "smoke-test": "npm run sync-package-assets && npm run test:control-state && npm run test:verified-change && npm run test:runtime-integrity-negative && npm run test:delivery-path-search && npm run test:delivery-path-search-unit && npm run test:delivery-path-search-generator && node ./scripts/smoke-test.js && node ./scripts/test-routing.js",
     "prepack": "npm run sync-package-assets"
   },
   "keywords": [