create-agdf 0.2.5 → 0.2.6

package/README.md

@@ -17,6 +17,9 @@ Optional flags:
 
 - `--dir <path>` write into a specific directory
 - `--force` overwrite existing generated files
+- `--language <de|en>` or `--lang <de|en>` persist the preferred AGDF artefact and chat language
+
+If no language is provided, `create-agdf` derives the preference from the local system locale (`LC_ALL`, `LC_MESSAGES`, `LANG`, `LANGUAGE` or the Node.js runtime locale) and falls back to `en`.
 
 ## Targets and existing AGENTS.md
 
@@ -51,6 +54,7 @@ This writes:
 
 - `.agdf/control/AGDF_RUN.md`
 - `.agdf/control/MASTER_BACKLOG.md`
+- `.agdf/control/config.json`
 - `.agdf/control/templates/artefacts/UR.md`
 - `.agdf/control/templates/artefacts/PRD.md`
 - `.agdf/control/templates/artefacts/SD.md`
@@ -60,6 +64,8 @@ This writes:
 - `.agdf/control/CONTEXT_GRAPH.md`
 - `.agdf/control/AGENT_QUALITY_CONTRACTS.json`
 
+`config.json` stores `artifact_language` and `chat_language` for governed work in the target repository. Runtime rules stay English so all AGDF surfaces share the same control contract.
+
 Use `doctor` to check whether the live control state is actionable:
 
 ```bash

package/bin/create-agdf.js

@@ -128,17 +128,72 @@ Usage:
 Options:
   --dir <path>   Write files into a specific directory
   --force        Overwrite existing generated files
+  --language <de|en>
+                 Set AGDF chat and artefact language. Defaults to detected system locale.
+  --lang <de|en> Alias for --language
   --json         Print doctor, gate-check or delivery-map output as JSON
   --help         Show this help
 `);
 }
 
+function normalizeLanguage(value) {
+  const normalized = String(value ?? "").trim().toLowerCase().replace("_", "-");
+  if (!normalized) return "";
+  if (normalized.startsWith("de")) return "de";
+  if (normalized.startsWith("en")) return "en";
+  return "";
+}
+
+function detectSystemLocale() {
+  const envLocale = process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || process.env.LANGUAGE || "";
+  if (envLocale) return envLocale;
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().locale || "";
+  } catch {
+    return "";
+  }
+}
+
+function resolveLanguagePreference(explicitLanguage) {
+  const explicit = normalizeLanguage(explicitLanguage);
+  if (explicit) {
+    return {
+      artifact_language: explicit,
+      chat_language: explicit,
+      runtime_language: "en",
+      source: "parameter",
+      detected_locale: detectSystemLocale() || "unknown",
+    };
+  }
+
+  const detectedLocale = detectSystemLocale();
+  const detected = normalizeLanguage(detectedLocale) || "en";
+  return {
+    artifact_language: detected,
+    chat_language: detected,
+    runtime_language: "en",
+    source: detectedLocale ? "system_locale" : "default",
+    detected_locale: detectedLocale || "unknown",
+  };
+}
+
+function languageConfigContent(languagePreference) {
+  return `${JSON.stringify({
+    artifact_language: languagePreference.artifact_language,
+    chat_language: languagePreference.chat_language,
+    runtime_language: languagePreference.runtime_language,
+    source: languagePreference.source,
+    detected_locale: languagePreference.detected_locale,
+  }, null, 2)}\n`;
+}
+
 function parseArgs(argv) {
   const args = [...argv];
   let target;
   let dir = ".";
   let force = false;
   let json = false;
+  let language;
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -159,6 +214,22 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--language" || arg === "--lang") {
+      const next = args[i + 1];
+      if (!next) {
+        console.error(`Missing value for ${arg}`);
+        process.exit(1);
+      }
+      const normalized = normalizeLanguage(next);
+      if (!normalized) {
+        console.error("Unsupported language. Use --language de or --language en.");
+        process.exit(1);
+      }
+      language = normalized;
+      i += 1;
+      continue;
+    }
+
     if (arg === "--dir") {
       const next = args[i + 1];
       if (!next) {
@@ -201,6 +272,7 @@ function parseArgs(argv) {
     dir: resolve(process.cwd(), dir),
     force,
     json,
+    language: resolveLanguagePreference(language),
   };
 }
 
@@ -219,10 +291,18 @@ function writeGeneratedFile(targetDir, relativePath, content, force) {
   writeFileSync(outputPath, content, "utf8");
 }
 
-function generatedFilesForTarget(target, targetDir, force) {
+function addLanguageConfig(files, languagePreference) {
+  files.push({
+    path: join(".agdf", "control", "config.json"),
+    content: languageConfigContent(languagePreference),
+  });
+}
+
+function generatedFilesForTarget(target, targetDir, force, languagePreference) {
   const files = [];
 
   if (target === "init") {
+    addLanguageConfig(files, languagePreference);
     files.push({
       path: join(".agdf", "control", "README.md"),
       content: loadAsset(join(".agdf", "control", "README.md")),
@@ -246,6 +326,7 @@ function generatedFilesForTarget(target, targetDir, force) {
   }
 
   if (target === "codex" || target === "both") {
+    addLanguageConfig(files, languagePreference);
     for (const codexPath of codexPluginFiles) {
       files.push({
         path: codexPath,
@@ -255,6 +336,7 @@ function generatedFilesForTarget(target, targetDir, force) {
   }
 
   if (target === "copilot" || target === "both") {
+    if (target !== "both") addLanguageConfig(files, languagePreference);
     const agentsTargetPath = existsSync(join(targetDir, "AGENTS.md")) && !force ? agdfFragmentPath : "AGENTS.md";
     files.push({
       path: agentsTargetPath,
@@ -297,6 +379,11 @@ function printNextSteps(target, destination, files, wroteAgentsFragment) {
 
   console.log("");
   console.log("Next steps:");
+  const languageConfig = files.find((file) => file.path === join(".agdf", "control", "config.json"));
+  if (languageConfig) {
+    const language = JSON.parse(languageConfig.content);
+    console.log(`- AGDF language preference: artefacts=${language.artifact_language}, chat=${language.chat_language}, runtime=${language.runtime_language}.`);
+  }
   if (target === "init") {
     console.log("- Fill .agdf/control/AGDF_RUN.md with the current gate, evidence and next allowed action.");
     console.log("- Run npm create agdf@latest doctor to check the control state before the next agent run.");
@@ -1026,18 +1113,33 @@ function evaluateGateCheck(targetDir) {
     ? transitionDecision.next_allowed_action
     : runState.next_allowed_action;
 
-  if (doctorBlocker) {
+  if (doctorBlocker?.code === "AGDF_CONTROL_FILE_MISSING") {
+    status = "blocked";
+    blockingReason = doctorBlocker.code;
+    currentGate = "UR";
+    missingApproval = "Approval: UR";
+    allowed = [
+      "initialize the AGDF control scaffold with npm create agdf@latest init",
+      "draft and persist the minimal UR for the requested change",
+      "link the UR from AGDF_RUN.md and MASTER_BACKLOG.md",
+      "request exact approval: Approval: UR",
+    ];
+    forbidden = ["create PRD", "create SD", "create TP", "run Brownfield Analysis", "implement code", "claim QA or release readiness"];
+    nextAllowedAction = "Initialize .agdf/control, draft the minimal UR for the request, then ask for exact approval: Approval: UR.";
+  } else if (doctorBlocker) {
     status = "blocked";
     blockingReason = doctorBlocker.code;
-    allowed = ["repair the AGDF control scaffold", "run doctor again"];
-    forbidden = ["continue governed delivery", "create later-gate artefacts", "implement gated work"];
+    allowed = ["repair the AGDF control scaffold", ...transitionDecision.allowed, "run doctor again"];
+    forbidden = ["create later-gate artefacts beyond the current allowed gate", "implement gated work", "claim QA or release readiness"];
     nextAllowedAction = doctorBlocker.next_step;
   } else if (doctorRevise) {
     status = "blocked";
     blockingReason = doctorRevise.code;
-    allowed = [...new Set(["repair the incomplete control state", ...transitionDecision.allowed, "run doctor again"])];
-    forbidden = ["continue governed delivery", "create later-gate artefacts", "implement gated work"];
-    nextAllowedAction = doctorRevise.next_step;
+    allowed = [...new Set(["complete the current control-state fields", ...transitionDecision.allowed, "run doctor again"])];
+    forbidden = ["create later-gate artefacts beyond the current allowed gate", "implement gated work before the gate allows it", "claim QA or release readiness"];
+    nextAllowedAction = transitionDecision.current_gate === "UR"
+      ? "Fill the current UR control state, persist the UR draft, and request exact approval: Approval: UR."
+      : doctorRevise.next_step;
   }
 
   return {
@@ -1183,7 +1285,7 @@ function main() {
     process.exit(report.status === "block" ? 2 : 0);
   }
 
-  const files = generatedFilesForTarget(options.target, options.dir, options.force);
+  const files = generatedFilesForTarget(options.target, options.dir, options.force, options.language);
   const wroteAgentsFragment = files.some(file => file.path === agdfFragmentPath);
 
   try {

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

@@ -8,6 +8,7 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 
 | File | Purpose |
 |---|---|
+| `config.json` | Project language preference for generated AGDF artefacts and user-facing chat |
 | `templates/AGDF_RUN.md` | Template for current run state: mode, gate, approvals, evidence, risks, next allowed action |
 | `templates/MASTER_BACKLOG.md` | Template for the living backlog pointer: active initiatives and current UR/Brownfield/PRD/SD/TP/QA/OR artefacts |
 | `templates/artefacts/UR.md` | Template for the durable user requirement artefact of a work item |
@@ -26,6 +27,7 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 ```text
 .agdf/
   control/
+    config.json
     AGDF_RUN.md
     MASTER_BACKLOG.md
     artefacts/
@@ -64,6 +66,7 @@ npm create agdf@latest gate-check --json
 ## Operating Rules
 
 - `AGDF_RUN.md` is the current run dashboard.
+- `config.json` stores the project preference for artefact and chat language; runtime rules stay English.
 - `MASTER_BACKLOG.md` points to active delivery work; detailed artefacts live beside the work item.
 - Brownfield Review records the post-UR Mode/Slice Decision before PRD depth or Quick Task execution is chosen.
 - UR, PRD, SD, TP and QA decisions require durable artefacts or links to the authoritative repository source of truth before the next gate can open.

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

@@ -61,6 +61,7 @@ The CLI reports are validators and JSON evidence, not the primary user experienc
 12. Approval text and durable artefact presence are separate requirements for UR, PRD, SD, TP and QA report decisions. Approval text without the corresponding persisted or linked artefact keeps the current gate at that gate.
 13. After Brownfield Review, decide the process size before drafting PRD or implementing: `quick_task | structured_slice | structured_delivery | block`.
 14. The Mode/Slice Decision must be visible and evidenced before any Quick Task execution, PRD shortcut or implementation. A decision value without scope reason and evidence is still missing.
+15. Missing or incomplete control state must not push work back to the user. If the next allowed step is an artefact draft, the agent may initialize the scaffold, draft the current allowed artefact, link it, and then request the exact approval. Implementation remains forbidden.
 
 ## Gate Evaluation
 
@@ -107,6 +108,7 @@ If a status is not explicit, do not assume it is satisfied.
 8. Treat a generic "start", "continue" or "leg los" request as a request to perform only the current next allowed action.
 9. After Brownfield Review, choose the smallest safe process path before creating later artefacts.
 10. If the selected path is not visibly recorded with scope reason and evidence, keep the run at `Mode/Slice Decision`.
+11. When `.agdf/control/` is missing or incomplete, make the next allowed artefact action explicit. For a fresh request, that means initialize control state, draft the minimal UR, then request `Approval: UR`.
 
 ## Output
 Keep the result short and operational:

package/generated/.github/skills/agdf-runtime-contract.md

@@ -25,6 +25,8 @@ Use this compact output shape when no formal gate artefact is required:
 - `risk`: remaining risk or `none`
 - `next_step`: the single next useful action or `none`
 
+Do not add a separate `Quality outlook` line for pure Quick Tasks unless the task became a relevant run.
+
 ## Relevant Run
 
 A relevant run is any run that changes durable state, creates or updates an AGDF artefact, changes code or runtime behaviour, performs a gate decision, blocks on a governance condition, produces QA/UAT/release evidence, or closes a delivery slice.
@@ -43,6 +45,7 @@ When in doubt, use a short OR-lite only if it clarifies gate state, evidence, ri
 - For UR, PRD, SD, TP and QA, approval and durable artefact presence are separate requirements. A gate is not satisfied by approval text alone when its artefact is missing from `.agdf/control/` or not linked to the authoritative repository SoT.
 - Approval of one user gate permits work on the next allowed gate artefact or required internal step only. It does not permit implementation unless the approved gate is `TP` and required internal implementation prerequisites are satisfied.
 - Gates must never be skipped or inferred from urgency, tone, chat history, task wording or an instruction to "start". The next allowed action is always the next unsatisfied gate or internal mandatory step.
+- Missing control files or missing current-state fields do not forbid the agent from preparing the current allowed artefact. They forbid later-gate work and implementation. For a fresh request, the allowed work is to initialize `.agdf/control/`, draft the minimal UR, link it, and request `Approval: UR`.
 - `Approval: UR` permits Brownfield Review after G-00 first, then a Mode/Slice Decision. It never permits implementation by itself.
 - PRD, SD and TP depth is chosen after Brownfield Review through the Mode/Slice Decision, not before existing-system impact is understood.
 - The Mode/Slice Decision must be visible before any PRD shortcut, Quick Task execution or implementation: record the decision, required next gate, scope reason and evidence in `AGDF_RUN.md` or an equivalent linked control artefact.
@@ -137,6 +140,7 @@ Do not create a new node for a mere version, a general chat summary, or a local
 
 When a repository needs durable AGDF state, use the plugin-local `control/` scaffold as the starting point.
 
+- `config.json` stores project language preferences. Use `artifact_language` for generated AGDF artefacts and `chat_language` for user-facing responses unless the user explicitly asks otherwise. Runtime rules remain English.
 - `AGDF_RUN.md` is the current run dashboard.
 - `MASTER_BACKLOG.md` is the living pointer for active delivery work.
 - `BROWNFIELD_REVIEW.md` records the post-UR existing-system view and Mode/Slice Decision before PRD depth or Quick Task execution is chosen.

package/generated/AGENTS.md

@@ -76,7 +76,14 @@ AGDF is a native agent workflow first: read the live control state, apply the ac
 Use `doctor`, `gate-check --json` or `delivery-map --json` as validators when a machine-readable proof is useful, not as a substitute for the router or skills.
 
 ## Closeout
-After relevant code, documentation, skill or governance changes:
+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

package/generated/plugins/agdf/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",
   "author": {
     "name": "AI-native Governance & Delivery Framework",

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

@@ -8,6 +8,7 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 
 | File | Purpose |
 |---|---|
+| `config.json` | Project language preference for generated AGDF artefacts and user-facing chat |
 | `templates/AGDF_RUN.md` | Template for current run state: mode, gate, approvals, evidence, risks, next allowed action |
 | `templates/MASTER_BACKLOG.md` | Template for the living backlog pointer: active initiatives and current UR/Brownfield/PRD/SD/TP/QA/OR artefacts |
 | `templates/artefacts/UR.md` | Template for the durable user requirement artefact of a work item |
@@ -26,6 +27,7 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 ```text
 .agdf/
   control/
+    config.json
     AGDF_RUN.md
     MASTER_BACKLOG.md
     artefacts/
@@ -64,6 +66,7 @@ npm create agdf@latest gate-check --json
 ## Operating Rules
 
 - `AGDF_RUN.md` is the current run dashboard.
+- `config.json` stores the project preference for artefact and chat language; runtime rules stay English.
 - `MASTER_BACKLOG.md` points to active delivery work; detailed artefacts live beside the work item.
 - Brownfield Review records the post-UR Mode/Slice Decision before PRD depth or Quick Task execution is chosen.
 - UR, PRD, SD, TP and QA decisions require durable artefacts or links to the authoritative repository source of truth before the next gate can open.

package/generated/plugins/agdf/meta/agdf-agent-router.md

@@ -77,7 +77,14 @@ AGDF is a native agent workflow first: read the live control state, apply the ac
 Use `doctor`, `gate-check --json` or `delivery-map --json` as validators when a machine-readable proof is useful, not as a substitute for the router or skills.
 
 ## Closeout
-After relevant code, documentation, skill or governance changes:
+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

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

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "AI-native Governance & Delivery Framework",
   "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",

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

@@ -25,6 +25,8 @@ Use this compact output shape when no formal gate artefact is required:
 - `risk`: remaining risk or `none`
 - `next_step`: the single next useful action or `none`
 
+Do not add a separate `Quality outlook` line for pure Quick Tasks unless the task became a relevant run.
+
 ## Relevant Run
 
 A relevant run is any run that changes durable state, creates or updates an AGDF artefact, changes code or runtime behaviour, performs a gate decision, blocks on a governance condition, produces QA/UAT/release evidence, or closes a delivery slice.
@@ -43,6 +45,7 @@ When in doubt, use a short OR-lite only if it clarifies gate state, evidence, ri
 - For UR, PRD, SD, TP and QA, approval and durable artefact presence are separate requirements. A gate is not satisfied by approval text alone when its artefact is missing from `.agdf/control/` or not linked to the authoritative repository SoT.
 - Approval of one user gate permits work on the next allowed gate artefact or required internal step only. It does not permit implementation unless the approved gate is `TP` and required internal implementation prerequisites are satisfied.
 - Gates must never be skipped or inferred from urgency, tone, chat history, task wording or an instruction to "start". The next allowed action is always the next unsatisfied gate or internal mandatory step.
+- Missing control files or missing current-state fields do not forbid the agent from preparing the current allowed artefact. They forbid later-gate work and implementation. For a fresh request, the allowed work is to initialize `.agdf/control/`, draft the minimal UR, link it, and request `Approval: UR`.
 - `Approval: UR` permits Brownfield Review after G-00 first, then a Mode/Slice Decision. It never permits implementation by itself.
 - PRD, SD and TP depth is chosen after Brownfield Review through the Mode/Slice Decision, not before existing-system impact is understood.
 - The Mode/Slice Decision must be visible before any PRD shortcut, Quick Task execution or implementation: record the decision, required next gate, scope reason and evidence in `AGDF_RUN.md` or an equivalent linked control artefact.
@@ -137,6 +140,7 @@ Do not create a new node for a mere version, a general chat summary, or a local
 
 When a repository needs durable AGDF state, use the plugin-local `control/` scaffold as the starting point.
 
+- `config.json` stores project language preferences. Use `artifact_language` for generated AGDF artefacts and `chat_language` for user-facing responses unless the user explicitly asks otherwise. Runtime rules remain English.
 - `AGDF_RUN.md` is the current run dashboard.
 - `MASTER_BACKLOG.md` is the living pointer for active delivery work.
 - `BROWNFIELD_REVIEW.md` records the post-UR existing-system view and Mode/Slice Decision before PRD depth or Quick Task execution is chosen.

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

@@ -61,6 +61,7 @@ The CLI reports are validators and JSON evidence, not the primary user experienc
 12. Approval text and durable artefact presence are separate requirements for UR, PRD, SD, TP and QA report decisions. Approval text without the corresponding persisted or linked artefact keeps the current gate at that gate.
 13. After Brownfield Review, decide the process size before drafting PRD or implementing: `quick_task | structured_slice | structured_delivery | block`.
 14. The Mode/Slice Decision must be visible and evidenced before any Quick Task execution, PRD shortcut or implementation. A decision value without scope reason and evidence is still missing.
+15. Missing or incomplete control state must not push work back to the user. If the next allowed step is an artefact draft, the agent may initialize the scaffold, draft the current allowed artefact, link it, and then request the exact approval. Implementation remains forbidden.
 
 ## Gate Evaluation
 
@@ -107,6 +108,7 @@ If a status is not explicit, do not assume it is satisfied.
 8. Treat a generic "start", "continue" or "leg los" request as a request to perform only the current next allowed action.
 9. After Brownfield Review, choose the smallest safe process path before creating later artefacts.
 10. If the selected path is not visibly recorded with scope reason and evidence, keep the run at `Mode/Slice Decision`.
+11. When `.agdf/control/` is missing or incomplete, make the next allowed artefact action explicit. For a fresh request, that means initialize control state, draft the minimal UR, then request `Approval: UR`.
 
 ## Output
 Keep the result short and operational:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [