create-agdf 0.8.7 → 0.9.0

package/bin/create-agdf.js

@@ -91,6 +91,15 @@ const codexSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefini
 const copilotSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.copilot.skillPrefix}${skill.slug}`);
 const openCodeSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.opencode.skillPrefix}${skill.slug}`);
 const globalOpenCodeSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.opencode.globalSkillPrefix}${skill.slug}`);
+const contractModules = [
+  "gate-transition.md",
+  "interaction.md",
+  "modes.md",
+  "quality.md",
+  "context-graph.md",
+  "control-scaffold.md",
+  "closeout.md",
+];
 const globalOpenCodeSkillOwnershipMarker = "<!-- AGDF-GLOBAL-SKILL: ";
 const globalOpenCodeInstructionsOwnershipMarker = "<!-- AGDF-GLOBAL-INSTRUCTIONS -->";
 const globalOpenCodeRuntimeContractOwnershipMarker = "<!-- AGDF-GLOBAL-RUNTIME-CONTRACT -->";
@@ -119,6 +128,7 @@ const codexPluginFiles = [
   join("plugins", "agdf", "meta", "agdf-plugin.definition.json"),
   join("plugins", "agdf", "meta", "agdf-runtime-contract.md"),
   join("plugins", "agdf", "meta", "agdf-tenets.md"),
+  ...contractModules.map((moduleName) => join("plugins", "agdf", "meta", "contracts", moduleName)),
   ...codexSkillNames.map((skillName) => join("plugins", "agdf", "skills", skillName, "SKILL.md")),
 ];
 const controlFiles = [
@@ -184,12 +194,14 @@ const copilotInstructionFiles = [
 const copilotSkillFiles = [
   join(".github", "skills", "README.md"),
   join(".github", "skills", pluginDefinition.copilot.runtimeContractFileName),
+  ...contractModules.map((moduleName) => join(".github", "skills", "contracts", moduleName)),
   ...copilotSkillNames.map((skillName) => join(".github", "skills", skillName, "SKILL.md")),
 ];
 const openCodeFiles = [
   join(".opencode", pluginDefinition.opencode.instructionsFileName),
   join(".opencode", "README.md"),
   join(".opencode", pluginDefinition.opencode.runtimeContractFileName),
+  ...contractModules.map((moduleName) => join(".opencode", "contracts", moduleName)),
   ...openCodeSkillNames.map((skillName) => join(".opencode", "skills", skillName, "SKILL.md")),
 ];
 
@@ -582,6 +594,7 @@ function globalOpenCodeConfigPaths(configDir) {
   return {
     instructions: join(configDir, pluginDefinition.opencode.instructionsFileName),
     runtimeContract: join(configDir, pluginDefinition.opencode.runtimeContractFileName),
+    contracts: join(configDir, "contracts"),
     skills: join(configDir, "skills"),
   };
 }
@@ -605,6 +618,13 @@ function assertGlobalOpenCodeSurfaceWritable(configDir) {
   const paths = globalOpenCodeConfigPaths(configDir);
   assertGlobalOpenCodeFileWritable(paths.instructions, globalOpenCodeInstructionsOwnershipMarker, "first-line");
   assertGlobalOpenCodeFileWritable(paths.runtimeContract, globalOpenCodeRuntimeContractOwnershipMarker, "first-line");
+  for (const moduleName of contractModules) {
+    assertGlobalOpenCodeFileWritable(
+      join(paths.contracts, moduleName),
+      globalOpenCodeRuntimeContractOwnershipMarker,
+      "first-line",
+    );
+  }
   for (const skillName of globalOpenCodeSkillNames) {
     assertGlobalOpenCodeFileWritable(
       join(paths.skills, skillName, "SKILL.md"),
@@ -664,6 +684,15 @@ function installOpenCodeGlobalSurface(configDir) {
 
   writeOwnedGlobalOpenCodeFile(paths.instructions, globalInstructions, globalOpenCodeInstructionsOwnershipMarker, "first-line");
   writeOwnedGlobalOpenCodeFile(paths.runtimeContract, globalRuntimeContract, globalOpenCodeRuntimeContractOwnershipMarker, "first-line");
+  for (const moduleName of contractModules) {
+    const generatedModule = readFileSync(join(generatedOpenCodeRoot, "contracts", moduleName), "utf8");
+    writeOwnedGlobalOpenCodeFile(
+      join(paths.contracts, moduleName),
+      `${globalOpenCodeRuntimeContractOwnershipMarker}\n${generatedModule}`,
+      globalOpenCodeRuntimeContractOwnershipMarker,
+      "first-line",
+    );
+  }
 
   for (let index = 0; index < openCodeSkillNames.length; index += 1) {
     const sourceName = openCodeSkillNames[index];
@@ -678,6 +707,7 @@ function installOpenCodeGlobalSurface(configDir) {
   return {
     instructions: paths.instructions,
     runtimeContract: paths.runtimeContract,
+    contracts: paths.contracts,
     skills: paths.skills,
   };
 }
@@ -760,14 +790,21 @@ function openCodePackageTransition(previousPackage, installedPackage) {
 function evaluateGlobalOpenCodeSurface(configDir) {
   const paths = globalOpenCodeConfigPaths(configDir);
   const skillCount = globalOpenCodeSkillNames.filter((skillName) => existsSync(join(paths.skills, skillName, "SKILL.md"))).length;
+  const contractCount = contractModules.filter((moduleName) => existsSync(join(paths.contracts, moduleName))).length;
   return {
     path: paths.skills,
     instructions: paths.instructions,
     runtime_contract: paths.runtimeContract,
+    contracts: paths.contracts,
     expected_skill_count: globalOpenCodeSkillNames.length,
     skill_count: skillCount,
+    expected_contract_count: contractModules.length,
+    contract_count: contractCount,
     present: existsSync(paths.skills),
-    complete: existsSync(paths.instructions) && existsSync(paths.runtimeContract) && skillCount === openCodeSkillNames.length,
+    complete: existsSync(paths.instructions)
+      && existsSync(paths.runtimeContract)
+      && contractCount === contractModules.length
+      && skillCount === openCodeSkillNames.length,
   };
 }
 
@@ -795,7 +832,11 @@ function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(
   if (!packageState.loadable) findings.push(`${pluginDefinition.opencode.npmPackage} is not loadable from the OpenCode config directory.`);
   if (packageVersionStatus === "outdated") findings.push(`${pluginDefinition.opencode.npmPackage} version ${packageState.installed_version} is outdated; expected ${pluginDefinition.version}.`);
   if (packageVersionStatus === "unknown" && packageState.loadable) findings.push(`${pluginDefinition.opencode.npmPackage} is loadable but its installed version is unknown.`);
-  if (!globalNativeSurface.complete) findings.push(`Global OpenCode native skill surface is incomplete (${globalNativeSurface.skill_count}/${globalNativeSurface.expected_skill_count} skills).`);
+  if (!globalNativeSurface.complete) {
+    findings.push(
+      `Global OpenCode native surface is incomplete (${globalNativeSurface.skill_count}/${globalNativeSurface.expected_skill_count} skills; ${globalNativeSurface.contract_count}/${globalNativeSurface.expected_contract_count} contract modules).`,
+    );
+  }
   if (!sessionSignals.active) findings.push("No active AGDF OpenCode session signal is visible in this process.");
   if (!repositorySurface) findings.push("Current repository does not contain the AGDF OpenCode surface.");
 
@@ -1531,6 +1572,13 @@ function filled(value) {
   return Boolean(value && !isPlaceholderValue(value) && value.trim() !== "");
 }
 
+function runSelectionRecovery(target) {
+  const directSelection = "Pass --run <run_id> or set AGDF_RUN_ID to select the intended run";
+  return ["doctor", "delivery-map"].includes(target)
+    ? `${directSelection}, or use --all-active to evaluate every active run independently.`
+    : `${directSelection}.`;
+}
+
 function parseQualityContracts(content) {
   const parsed = JSON.parse(content);
   if (!Array.isArray(parsed.contracts) || parsed.contracts.length === 0) {
@@ -1627,7 +1675,7 @@ function evaluateDoctor(targetDir, selection = {}) {
         selectedRunState.resolution_error.split(":")[0] || "AGDF_ACTIVE_RUN_UNRESOLVED",
         `Run selection failed: ${selectedRunState.resolution_error}`,
         runPath,
-        "Pass --run <run_id> or set AGDF_RUN_ID to select the intended run, or use --all-active to evaluate every active run independently.",
+        runSelectionRecovery(selection.target),
       );
     } else {
       const currentGateLine = run.match(/^- current_gate:[^\S\r\n]*(.*)$/m)?.[1]?.trim() ?? "";
@@ -2344,6 +2392,12 @@ const BREADCRUMB_PATH_TEMPLATES = {
 
 const BREADCRUMB_STANDARD_GATES = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
 
+function isReadyUserGateApproval({ status, currentGate, missingApproval }) {
+  return status === "open"
+    && BREADCRUMB_STANDARD_GATES.includes(currentGate)
+    && missingApproval === `Approval: ${currentGate}`;
+}
+
 function buildBreadcrumbPath(modeSliceDecision, currentGate, runState) {
   const gates = BREADCRUMB_PATH_TEMPLATES[modeSliceDecision] ?? ["UR"];
   return gates.map((gate) => {
@@ -2381,7 +2435,7 @@ function buildStatusCard({
 }) {
   const qualityOutlook = deriveQualityOutlook(runState, findings);
   const postApproval = postApprovalTransition(missingApproval);
-  const isUserGateApproval = missingApproval !== "none";
+  const isUserGateApproval = isReadyUserGateApproval({ status, currentGate, missingApproval });
   const lifecycle = extractField(runState.content ?? "", "lifecycle") || "unknown";
   const nativeAttemptRequired = false;
   const interactionKind = status === "open" && isUserGateApproval ? "gate_approval" : status === "blocked" ? "blocked" : "status";
@@ -2529,9 +2583,9 @@ function transitionDecisionForRunState(runState, verifiedChange = null) {
 
   if (!isGateSatisfied(runState, "UR")) {
     return {
-      status: "blocked",
+      status: "open",
       current_gate: "UR",
-      blocking_reason: "missing_exact_approval",
+      blocking_reason: "none",
       missing_approval: "Approval: UR",
       allowed: ["clarify user need", "formulate and persist UR", "record evidence", "request exact UR approval"],
       forbidden: ["create PRD", "create SD", "create TP", "run Brownfield Analysis", "implement code", "claim QA or release readiness"],
@@ -2847,7 +2901,7 @@ function evaluateGateCheck(targetDir, selection = {}) {
     enumerable: false,
   });
   attachApprovalOrientationSnapshot(statusCard, {
-    ready: status === "open" && missingApproval === `Approval: ${currentGate}`,
+    ready: isReadyUserGateApproval({ status, currentGate, missingApproval }),
     humanPresentation,
     revisionId: extractField(runState.content ?? "", "revision_id"),
     registry: interactionLocales,
@@ -3280,4 +3334,9 @@ async function main() {
   printNextSteps(options.target, options.dir, files, wroteAgentsFragment, wroteOpenCodeConfigFragment, removedOpenCodeAgents);
 }
 
-await main();
+try {
+  await main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/generated/.github/skills/agdf-brownfield-analysis/SKILL.md

@@ -19,7 +19,11 @@ The skill answers:
 - whether Context Graph impact exists without automatically creating a node
 
 ## Runtime Contract
-Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+Use these focused runtime-contract modules:
+
+- `../contracts/gate-transition.md`
+- `../contracts/context-graph.md`
+- `../contracts/quality.md`
 
 Brownfield-specific output must make evidence, missing existing-system view, parallel-structure risk, reuse strategy, and the minimal next step visible.
 When `.agdf/control/` is present, persist or link `post_ur_review` output under `.agdf/control/artefacts/<key>/BROWNFIELD_REVIEW.md`.
@@ -96,7 +100,7 @@ When used as Brownfield Review after `Approval: UR`, do not recommend PRD, SD, T
 7. Check SoT/runtime/product-semantics drift.
 8. Check primary visible ownership for UI/status/recovery paths.
 9. Check UI monolith risk for large surfaces or central hooks.
-10. Check Context Graph impact according to `../agdf-runtime-contract.md`.
+10. Check Context Graph impact according to `../contracts/context-graph.md`.
 11. Recommend the minimal clean implementation path.
 
 ## Output

package/generated/.github/skills/agdf-clean-implementation-review/SKILL.md

@@ -18,7 +18,10 @@ This skill answers:
 - is it maintainable or workaround-heavy
 
 ## Runtime Contract
-Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+Use these focused runtime-contract modules:
+
+- `../contracts/quality.md`
+- `../contracts/context-graph.md`
 
 Clean-review-specific output must make the primary solution, fallbacks, workarounds, parallel structures, exit criteria, and next cleanup/review step visible.
 
@@ -91,6 +94,11 @@ Use this compact structure:
 - `revise`: solution works but contains avoidable fallback, unclear ownership, or missing evidence.
 - `block`: solution creates a second SoT, a second owner, unbounded fallback, or masks unresolved product semantics.
 
+### Compact Chat Output
+
+At `pass`: one line — `Clean Review: pass — <one-line summary>`.
+At `revise`/`block`: show the specific fallback/workaround/parallel-structure risk with file references.
+
 ## Forbidden
 This skill must not:
 

package/generated/.github/skills/agdf-code-review/SKILL.md

@@ -17,7 +17,10 @@ It answers:
 - whether Brownfield, TP, or clean-review follow-up remains open
 
 ## Runtime Contract
-Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+Use these focused runtime-contract modules:
+
+- `../contracts/quality.md`
+- `../contracts/context-graph.md`
 
 Code-review-specific output must make actual findings, missing review scope, evidence strength, and the next required step visible.
 
@@ -84,6 +87,11 @@ Use this compact structure:
 - `block`: a hard defect, security risk, data-integrity risk, or unresolved critical uncertainty remains.
 - `not_applicable`: no code changes were present for review.
 
+### Compact Chat Output
+
+At `pass`: one line — `Code Review: pass — <one-line summary>`.
+At `revise`/`block`: show blocking findings with file references. Full report remains in durable file or inline evidence as specified.
+
 ## Forbidden
 This skill must not:
 

package/generated/.github/skills/agdf-delivery-closeout/SKILL.md

@@ -20,7 +20,11 @@ It answers:
 This skill does not replace `agdf-qa-gate`, `agdf-release-or`, user approvals, or gate decisions.
 
 ## Runtime Contract
-Use `../agdf-runtime-contract.md` for closeout discipline, gate terms, Context Graph fields, and non-duplication rules.
+Use these focused runtime-contract modules:
+
+- `../contracts/closeout.md`
+- `../contracts/context-graph.md`
+- `../contracts/gate-transition.md`
 
 ## Rules
 1. Delivery follows gate clarity.

package/generated/.github/skills/agdf-delivery-path-search/SKILL.md

@@ -13,7 +13,11 @@ The search is advisory and read-only. Canonical AGDF `agdf-gate-check` remains t
 
 ## Runtime Contract
 
-Use `../agdf-runtime-contract.md` for canonical gate state, output discipline and Delivery Path Search boundaries. This skill must not maintain a second gate or scoring model.
+Use these focused runtime-contract modules:
+
+- `../contracts/control-scaffold.md`
+- `../contracts/gate-transition.md`
+- `../contracts/quality.md`
 
 ## Trigger
 

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

@@ -18,8 +18,14 @@ Determine the earliest blocking user approval gate and derive:
 This skill must not create later artefacts such as PRD, SD, TP, CD, CR, QA, or UAT when the gate does not allow them.
 
 ## Runtime Contract
-Use `../agdf-runtime-contract.md` for gate terms, closeout discipline, and non-duplication rules.
-The canonical gate order and transition model live only in the Runtime Contract. This skill evaluates the current state against that model; it must not maintain a second complete gate table.
+Use these focused runtime-contract modules:
+
+- `../contracts/gate-transition.md`
+- `../contracts/interaction.md`
+- `../contracts/control-scaffold.md`
+- `../contracts/modes.md`
+- `../contracts/quality.md`
+The canonical gate order and transition model live only in `../contracts/gate-transition.md`. This skill evaluates the current state against that model; it must not maintain a second complete gate table.
 
 ## Agent-Native Control Path
 
@@ -69,7 +75,7 @@ For a ready `gate_approval`:
 7. Distinguish internal process steps from user decisions in natural language. For example, after `Approval: TP`, say that pre-implementation Brownfield Analysis runs next and that no further user action is required now; do not expose `next_user_gate: none` or `user_action_required: no`, and do not ask for a second approval for Brownfield Analysis.
 8. Ask exactly one question that names the selected `run_id` and `current_gate`.
 9. Offer options in stable order: exact `Approval: <GateName>`, localized revise and localized decline. Add explicit cancel only where supported after decline; otherwise host dismissal maps to cancel. Never preselect, skip, auto-submit or reorder an option.
-10. 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.
+10. Use the surface adapter declared in the canonical plugin definition only when it can wait for deliberate input without auto-resolution and can transport `exact_option_value` or `separate_label_and_value`; never invoke a `decorated_label_only` adapter. Otherwise request the same exact approval in concise text.
 11. Render both cards once in that single complete assistant message. Never merge, reverse, omit or duplicate them; the action heading does not replace either card. If the native attempt is unavailable or not applied, continue to exact text without repeating either card.
 12. Re-run gate evaluation for the same run and expected gate after the response and immediately before persistence.
 13. 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.
@@ -88,7 +94,7 @@ For the transition card, use the complete resolved locale pack. The initial Germ
 
 The primary option is derived exactly as `Approval: <GateName>` from the evaluated current gate; only explanatory copy and non-authoritative outcome labels are localized. Concrete localized copy belongs to the user-facing interaction layer or the approved delivery artefact, not to English runtime rules.
 
-Make exactly one native-attempt for the ready gate. If the host does not render,
+Make exactly one native-attempt for the eligible ready gate. If the host does not render,
 apply or safely return the native question on that attempt, switch immediately
 to the exact textual approval. Do not ask the user to request the buttons again
 and do not create a retry loop or simulated control.
@@ -102,7 +108,7 @@ only after fresh run/gate/artefact revalidation; never retry automatically.
 
 Surface behavior:
 
-- Codex: invoke the native short-question/request-user-input control on the first eligible attempt when callable, ask one gate question and omit auto-resolution; if it is not rendered or applied, use exact text immediately.
+- Codex: invoke the native short-question/request-user-input control only when preflight proves `exact_option_value` or `separate_label_and_value`, and omit auto-resolution. The canonical `decorated_label_only` capability must use exact text without invoking the adapter. `Approval: <GateName> (Recommended)` is never a valid option or approval.
 - Claude Code: invoke `AskUserQuestion` on the first eligible attempt only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; if it is not rendered or applied, use exact text immediately. 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.
@@ -232,6 +238,7 @@ from the same snapshot and are shown exactly once.
 
 If this skill creates or updates control artefacts, do not paste full file bodies into the chat.
 List paths, summarize the decision, name the blocker or approval needed, and keep the durable content in the files.
+See the Runtime Contract §Chat and Tool-Call Discipline for tool-call batching and skill output compaction rules.
 
 ## Forbidden
 This skill must not:

package/generated/.github/skills/agdf-qa-gate/SKILL.md

@@ -22,7 +22,11 @@ It answers:
 - whether blockers, critical risks, or missing evidence remain
 
 ## Runtime Contract
-Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+Use these focused runtime-contract modules:
+
+- `../contracts/quality.md`
+- `../contracts/context-graph.md`
+- `../contracts/gate-transition.md`
 
 QA-specific `decision` is exactly `pass | revise | block`.
 `pass` is allowed only when TP coverage, Brownfield fit, solution integrity, and relevant documentation/Context Graph impact are sufficiently evidenced.
@@ -100,7 +104,13 @@ Use this shape:
 - impact_codes:
 ```
 
-If Context Graph impact is relevant, include the fields from `../agdf-runtime-contract.md`.
+If Context Graph impact is relevant, include the fields from `../contracts/context-graph.md`.
+
+### Compact Chat Output
+
+At `pass`: one line — `QA: pass — <one-line summary>`. Reference the durable QA report
+path. Do not show the Quality Readiness projection or evidence inventory in chat.
+At `revise`/`block`: show the decisive dimension, reason and next action.
 
 ## Decision Guidance
 - `pass`: required TP tasks are done, evidence is strong, no blocking Brownfield or solution-integrity risk remains.

package/generated/.github/skills/agdf-release-or/SKILL.md

@@ -25,7 +25,12 @@ It reports:
 - whether further quality follow-up or a separate delivery closeout is useful
 
 ## Runtime Contract
-Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+Use these focused runtime-contract modules:
+
+- `../contracts/closeout.md`
+- `../contracts/quality.md`
+- `../contracts/context-graph.md`
+- `../contracts/control-scaffold.md`
 
 OR-specific output must make gate status, delivered and intentionally not delivered content, missing approvals, missing evidence, risks, retained fallbacks, and the next permissible step visible.
 When `.agdf/control/` is present, persist or link the OR under `.agdf/control/artefacts/<key>/OR.md` and reference it from the selected canonical `RUN_STATE.md` or `MASTER_BACKLOG.md` when it is steering-relevant.
@@ -118,7 +123,7 @@ Use a compact structure:
 - quality_outlook:
 ```
 
-When Context Graph impact is relevant, include the fields from `../agdf-runtime-contract.md`.
+When Context Graph impact is relevant, include the fields from `../contracts/context-graph.md`.
 Include `context_graph_reconciliation` whenever Context Graph impact is present. If the value is `open_gap`, required next step must resolve or explicitly retain that gap before commit-ready or release-ready handoff.
 
 ## Forbidden