@aifabrix/builder 2.60.0 → 2.61.2

package/lib/utils/system-secret-mapping.js

@@ -0,0 +1,125 @@
+/**
+ * Map an application's `.env` variables onto Miso catalog keys.
+ *
+ * The `.env` is keyed by environment variable (`MORI_POLICY_PRIVATE_KEY`) while the system
+ * secrets API is keyed by catalog key (`secrets-policyPrivateKeyVault`). The mapping is not
+ * invented here: it is read from the application's own `env.template`, because the
+ * `NAME=kv://<catalogKey>` line is already the declaration that decides where the value is
+ * read from at runtime. A second table in the CLI would be free to drift from it.
+ *
+ * A variable whose template line is not a `kv://` reference is ordinary configuration, not a
+ * secret, and is skipped rather than pushed.
+ *
+ * Note this is the flat `kv://<catalogKey>` form used by the Controller's system secrets.
+ * The Dataplane's credential store uses `kv://<systemKey>/<path>`; see
+ * `credential-secrets-env-kv.js` for that one. They are not interchangeable.
+ *
+ * @fileoverview env.template kv:// declarations → catalog keys
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** `NAME=value`, ignoring blank lines, comments and `export ` prefixes. */
+const ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/;
+
+/**
+ * Strip surrounding quotes and trailing whitespace from an env value.
+ * @param {string} raw - Raw right-hand side
+ * @returns {string} Cleaned value
+ */
+function cleanValue(raw) {
+  const trimmed = String(raw === undefined || raw === null ? '' : raw).trim();
+  if (trimmed.length >= 2) {
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    if ((first === '"' && last === '"') || (first === '\'' && last === '\'')) {
+      return trimmed.slice(1, -1);
+    }
+  }
+  return trimmed;
+}
+
+/**
+ * Parse `NAME=value` lines into a Map, last assignment winning.
+ * @param {string} content - File content
+ * @returns {Map<string, string>} Variable name → value
+ */
+function parseEnvAssignments(content) {
+  const out = new Map();
+  for (const line of String(content || '').split(/\r?\n/)) {
+    if (!line || /^\s*#/.test(line)) {
+      continue;
+    }
+    const match = line.match(ASSIGNMENT);
+    if (match) {
+      out.set(match[1], cleanValue(match[2]));
+    }
+  }
+  return out;
+}
+
+/**
+ * Catalog keys declared by an `env.template`, keyed by environment variable name.
+ * Only `kv://` lines are secrets; everything else is skipped.
+ * @param {string} templateContent - env.template content
+ * @returns {Map<string, string>} Variable name → catalog key
+ */
+function catalogKeysFromTemplate(templateContent) {
+  const out = new Map();
+  for (const [name, value] of parseEnvAssignments(templateContent)) {
+    if (!value.startsWith('kv://')) {
+      continue;
+    }
+    const catalogKey = value.slice('kv://'.length).trim();
+    if (catalogKey && !catalogKey.includes('/')) {
+      out.set(name, catalogKey);
+    }
+  }
+  return out;
+}
+
+/**
+ * Pair the values in a `.env` with the catalog keys its `env.template` declares.
+ *
+ * Skipped rows are returned rather than dropped, so the command can say why a variable was
+ * not pushed instead of silently ignoring it.
+ *
+ * @param {string} envContent - Operator's .env content
+ * @param {string} templateContent - The application's env.template content
+ * @param {Object} [options] - `only` restricts to one variable name
+ * @returns {{ pushable: Array<Object>, skipped: Array<Object> }} Rows carrying value and catalog key
+ */
+function mapEnvToCatalogKeys(envContent, templateContent, options = {}) {
+  const declared = catalogKeysFromTemplate(templateContent);
+  const values = parseEnvAssignments(envContent);
+  const only = options.only ? String(options.only).trim() : '';
+  const pushable = [];
+  const skipped = [];
+  for (const [name, value] of values) {
+    if (only && name !== only) {
+      continue;
+    }
+    const catalogKey = declared.get(name);
+    if (!catalogKey) {
+      skipped.push({ name, reason: 'not a kv:// reference in env.template' });
+      continue;
+    }
+    if (!value) {
+      skipped.push({ name, catalogKey, reason: 'no value in the env file' });
+      continue;
+    }
+    pushable.push({ name, catalogKey, value });
+  }
+  if (only && pushable.length === 0 && skipped.length === 0) {
+    skipped.push({ name: only, reason: 'not present in the env file' });
+  }
+  return { pushable, skipped };
+}
+
+module.exports = {
+  parseEnvAssignments,
+  catalogKeysFromTemplate,
+  mapEnvToCatalogKeys
+};

package/lib/utils/test-log-writer.js

@@ -9,6 +9,7 @@
 
 const fs = require('fs').promises;
 const path = require('path');
+const { sanitizeBinaryEvidence } = require('./datasource-binary-evidence');
 
 /**
  * Prepare object for JSON serialization (handles circular refs)
@@ -45,7 +46,7 @@ async function writeTestLog(appKey, data, logType = 'test-integration', integrat
   const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
   const filename = `${logType}-${timestamp}.json`;
   const filePath = path.join(logsDir, filename);
-  const sanitized = sanitizeForLog(data);
+  const sanitized = sanitizeForLog(sanitizeBinaryEvidence(data));
   await fs.writeFile(filePath, JSON.stringify(sanitized, null, 2), 'utf8');
   return filePath;
 }

package/lib/validation/external-manifest-validator.js

@@ -16,6 +16,7 @@ const path = require('path');
 const { formatValidationErrors } = require('../utils/error-formatter');
 const { validateFieldReferences } = require('../datasource/field-reference-validator');
 const { validateAbac } = require('../datasource/abac-validator');
+const { validateBinaryDocumentsContract } = require('../datasource/binary-documents-validator');
 const { validateManifestRuntimeConfiguration } = require('./runtime-configuration-rules');
 const { validateAppContractSurface } = require('./openapi-contract-surface-validator');
 
@@ -147,9 +148,13 @@ function validateDatasources(manifest, ajv, externalDatasourceSchema, errors, wa
         } else {
           const fieldRefErrors = validateFieldReferences(datasource);
           const abacErrors = validateAbac(datasource);
+          const binaryDocuments = validateBinaryDocumentsContract(datasource);
           const prefix = `Datasource ${index + 1} (${datasource.key || 'unknown'}): `;
           fieldRefErrors.forEach(e => errors.push(prefix + e));
           abacErrors.forEach(e => errors.push(prefix + e));
+          // Codes are the dataplane's, so the offline answer matches the upload answer.
+          binaryDocuments.errors.forEach(e => errors.push(`${prefix}${e.code}: ${e.message}`));
+          binaryDocuments.warnings.forEach(w => warnings.push(`${prefix}${w.code}: ${w.message}`));
         }
       });
     }

package/lib/validation/openapi-contract-surface-validator.js

@@ -426,5 +426,7 @@ module.exports = {
   validateDatasourceFileContractSurface,
   validateVendorOperationContract,
   validateServiceContractDatasourceContracts,
-  findVendorOperation
+  findVendorOperation,
+  resolveVendorOpenApiSpec,
+  inferIntegrationContextFromPath
 };

package/lib/validation/validate-external-file.js

@@ -111,11 +111,15 @@ function validateDatasourceFileExtras(parsed, filePath) {
   const { collectExternalDatasourceWarnings } = require('./datasource-warnings');
   const { validateDatasourceFileContractSurface } = require('./openapi-contract-surface-validator');
   const errors = [...validateFieldReferences(parsed), ...validateAbac(parsed)];
+  const { validateBinaryDocumentsContract } = require('../datasource/binary-documents-validator');
+  const binary = validateBinaryDocumentsContract(parsed);
+  errors.push(...binary.errors.map(issue => `${issue.code}: ${issue.message}`));
   const contractSurface = validateDatasourceFileContractSurface(parsed, filePath);
   errors.push(...contractSurface.errors);
   const warnings = [
     ...collectExternalDatasourceWarnings(parsed),
-    ...contractSurface.warnings
+    ...contractSurface.warnings,
+    ...binary.warnings.map(issue => `${issue.code}: ${issue.message}`)
   ];
   return { errors, warnings };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.60.0",
+  "version": "2.61.2",
   "description": "AI Fabrix Builder — CLI and developer scripts (pnpm + af)",
   "main": "lib/index.js",
   "bin": {
@@ -10,6 +10,7 @@
   "files": [
     "bin/aifabrix.js",
     "lib/",
+    "docs/builder-help/",
     "templates/",
     "README.md",
     "LICENSE"
@@ -24,7 +25,7 @@
     "dev-deploy": "node scripts/pnpm/dev-deploy.mjs",
     "af": "node scripts/pnpm/af.mjs",
     "check-quiet": "node scripts/pnpm/check-quiet.mjs",
-    "agent-skills:sync": "node scripts/pnpm/agent-skills-sync.mjs",
+    "agent-skills:sync": "node scripts/pnpm/agent-skills-sync.mjs --codex-home",
     "agent-skills:check": "node scripts/pnpm/agent-skills-sync.mjs --check",
     "agent-skills:sync:codex": "node scripts/pnpm/agent-skills-sync.mjs --codex-home",
     "agent-skills:test": "node --test scripts/pnpm/agent-skills-sync.test.mjs",
@@ -131,7 +132,7 @@
     }
   },
   "dependencies": {
-    "@aifabrix/miso-client": "4.23.1",
+    "@aifabrix/miso-client": "5.0.3",
     "@azure/identity": "4.11.1",
     "adm-zip": "^0.6.1",
     "ajv": "^8.20.0",

package/templates/agent-kit/agent-kit.yaml

@@ -1,5 +1,5 @@
 schemaVersion: "1"
-kitVersion: "1.2.0"
+kitVersion: "1.2.1"
 minimumBuilderVersion: "2.54.2"
 skills:
   - aifabrix-plan

package/templates/agent-kit/skills/aifabrix-connected-system/SKILL.md

@@ -20,7 +20,7 @@ Resolve phase: explicit argument → ask. Package state informs the recommendati
 the action.
 
 Stop at the phase gate. Do not run the next phase without `next-yes`
-([interaction.md](../aifabrix-plan/references/interaction.md)).
+([interaction.md](../shared/interaction.md)).
 
 | Phase | Entry | Success |
 | --- | --- | --- |
@@ -67,6 +67,7 @@ System key: argument → active plan → sole `integration/` folder → ask once
 
 ## References
 
+- [interaction.md](../shared/interaction.md) — native selection controls, routes, and phase gates
 - [status.md](../shared/status.md) — read-only default, route options, status matrix
 - [delivery-gates.md](references/delivery-gates.md) — BID/wizard/repair, upload vs deploy, tests, identity, protection
 - [contract-checklist.md](references/contract-checklist.md) — exposed, FK, viewpoints, RBAC/ABAC

package/templates/agent-kit/skills/aifabrix-connected-system/references/delivery-gates.md

@@ -39,6 +39,21 @@ If `integration/<systemKey>/deploy.js` exists, you may run it as the publish lad
 
 Never mark live E2E pass when it did not run.
 
+## Upsert authoring and warnings
+
+When upsert is explicitly required, first run
+`aifabrix datasource capability upsert <file-or-key> --dry-run --json`. Apply a
+fix automatically only when the finding identifies a deterministic local
+manifest change and the active phase authorizes mutation. Rerun the exact
+failed command before broader validation.
+
+Every open finding must state the observed condition, business consequence,
+safe action, prevention, residual risk, and exact rerun. A source API that
+cannot constrain the complete business identity is not AI-fixable: keep valid
+separate create/update capabilities, report duplicate or wrong-update risk,
+and withhold verified upsert. Never invent a lookup, weaken the two-write
+no-duplicate assertion, or hide the warning behind another passing test.
+
 ## Identity and protection order
 
 1. `aifabrix auth status` — if unauthenticated, [login.md](../../shared/login.md)

package/templates/agent-kit/skills/aifabrix-plan/SKILL.md

@@ -16,7 +16,7 @@ Named with no specification, report what exists and ask; do not start writing a
 an inferred spec ([status.md](../shared/status.md)).
 
 Score completeness with [challenge-checklist.md](references/challenge-checklist.md).
-Next-step interaction: [interaction.md](references/interaction.md).
+Structured choices and phase gates: [interaction.md](../shared/interaction.md).
 Host runtimes (local vs SSH): [hosts.md](../shared/hosts.md).
 CLI login from chat: [login.md](../shared/login.md).
 
@@ -32,7 +32,8 @@ Do not start Connected System validate until **PLAN_READY** and the user picks `
 
 1. Collect the spec the user named. Do not mine platform repos as the spec.
 2. Inventory without adding: purpose, sources, entities, relationships, role labels, operations, Viewpoints, Evidence, identity join. Missing sections → `TBD` plus an Open question.
-3. Challenge required rows. AskQuestion every MISSING required row. Authority and identity cannot be guessed.
+3. Challenge required rows. Use the structured question control for every MISSING required
+   row. Authority and identity cannot be guessed.
 4. Write or update `.cursor/plans/{major}.0-{slug}.plan.md` using the template H2 order. Same capability updates in place.
 5. Report status and path. On PLAN_READY, offer validate — do not run it without `next-yes`.
 

package/templates/agent-kit/skills/aifabrix-prove/SKILL.md

@@ -38,8 +38,10 @@ business-case readiness. None of them, alone or together, makes prove READY.
 
 Every phase **must** update [learning-template.md](references/learning-template.md).
 Evidence rules: [evidence-lifecycle.md](references/evidence-lifecycle.md).
+Role Assistant test execution and diagnosis:
+[testing-playbook.md](../aifabrix-role-assistant/references/testing-playbook.md).
 Demo shape: [demo-template.md](references/demo-template.md).
-Next-step: [interaction.md](../aifabrix-plan/references/interaction.md).
+Structured choices and phase gates: [interaction.md](../shared/interaction.md).
 Host runtimes (local vs SSH): [hosts.md](../shared/hosts.md).
 CLI login from chat: [login.md](../shared/login.md).
 
@@ -60,7 +62,9 @@ Repeatable: demo, Knowledge, candidate Evidence, tests. Do not refuse because va
 
 ## Prove
 
-Run assistant tests. Record observations and gap owner (`none` | `product-gap` | `missing-customer-fact` | `scope-decision`).
+Run assistant tests using the testing playbook. Record the business verdict,
+execution reference, and gap owner (`none` | `product-gap` |
+`missing-customer-fact` | `scope-decision`).
 Happy + safe-stop coverage for authority scenarios.
 Never report candidates as certified.
 

package/templates/agent-kit/skills/aifabrix-prove/references/evidence-lifecycle.md

@@ -49,6 +49,25 @@ Promote candidate → governed Evidence only when:
 3. Contract validation + certification path for Evidence completed (public Evidence Fabrix / operate-first RA docs)
 4. learning.md records promotion date + commit
 
+## Human authority and applied proof
+
+Keep these states distinct:
+
+| State | What it proves |
+| --- | --- |
+| Candidate or proposal | Draft content exists; it is not governed Evidence |
+| Certified | The applicable human governance decision completed |
+| Active | The product may supply the Evidence to execution |
+| Applied | A recorded execution shows the Evidence affected the result |
+
+An agent may prepare candidates, execute authorized source cases, and inspect a
+proposal. It must pause before certifying, activating, rejecting, or
+deactivating Evidence unless the current user explicitly authorizes that action
+and the product workflow permits it. Record the pause as `BLOCKED_BY_HUMAN`, not
+as a failed test. After the human gate, rerun the case and prove Applied Evidence
+from execution evidence; catalog presence is not Applied proof. Follow the
+[Role Assistant testing playbook](../../aifabrix-role-assistant/references/testing-playbook.md).
+
 ## Tests
 
 For each in-scope scenario ID:
@@ -66,3 +85,6 @@ Prefer `role-assistant/ra-<roleKey>/tests/<suiteId>/` in this customer repo (pac
 - Hiding process law in Knowledge
 - Uploading candidates as if certified
 - Skipping safe-stop coverage for authority scenarios
+- Certifying, activating, rejecting, or deactivating Evidence without the
+  current user's explicit authority
+- Reporting catalog presence as proof that Evidence was Applied

package/templates/agent-kit/skills/aifabrix-role-assistant/SKILL.md

@@ -9,8 +9,11 @@ description: >
 # aifabrix-role-assistant
 
 See [package-boundary.md](references/package-boundary.md) and nested `role-assistant/AGENTS.md`.
+For test execution, verdicts, fixtures, and diagnosis, follow
+[testing-playbook.md](references/testing-playbook.md).
 Host runtimes (local vs SSH): [hosts.md](../shared/hosts.md).
 CLI login from chat: [login.md](../shared/login.md).
+Structured choices and phase gates: [interaction.md](../shared/interaction.md).
 
 Named with no task, report status and stop: [status.md](../shared/status.md).
 
@@ -47,7 +50,9 @@ substitutes for it.
 
 1. `aifabrix download <catalogRoleOrRaKey>` before editing an existing assistant.
 2. Author settings, Knowledge, Evidence, tests, and sidecars per current Builder contracts. Read `aifabrix role-assistant --help`.
-3. `aifabrix role-assistant test …` is allowed without local RA publish.
+3. `aifabrix role-assistant test …` is allowed without local RA publish. Apply
+   the testing playbook and inspect hard business assertions before reporting
+   READY or VERIFIED.
 4. Upload/deploy RA only when the user explicitly asks in this turn.
 5. Report results honestly.
 
@@ -62,3 +67,4 @@ substitutes for it.
 ## Trigger examples
 
 - Create or update the Finance Controller Role Assistant
+- Test or diagnose the Finance Controller Role Assistant

package/templates/agent-kit/skills/aifabrix-role-assistant/references/testing-playbook.md

@@ -0,0 +1,117 @@
+# Role Assistant testing and diagnosis
+
+Public concepts: https://docs.aifabrix.ai/docs/role-assistants
+Exact commands, fields, and flags: run `aifabrix role-assistant test --help` with
+the installed Builder version.
+
+Use this playbook for live Role Assistant cases. A successful command is not
+enough: the observed business outcome, authority boundary, capabilities, Work
+Result, and resource changes must match the case.
+
+## Preconditions
+
+- Authenticate to the intended environment and identify the package and cases
+  root before execution.
+- Confirm every required Connected System is published and certified, its
+  required capabilities are available, and worker availability is known.
+- Record the actor and business role, mutation scope, designated test subjects,
+  and cleanup rule before a mutating case.
+- Treat missing auth, worker availability, capability, fixture, or required
+  human action as `BLOCKED` with the exact prerequisite.
+
+## Execution ladder
+
+1. Validate the package and use `--list-cases` to confirm discovery.
+2. Run one focused case with `--case ... --json`.
+3. Inspect lifecycle and final Runtime status, questions or approvals,
+   `expected.capabilities`, Work Result completion, resource changes, and
+   Evidence use. Do not rely on the process exit or wrapper verdict alone.
+4. Correct the owning layer, rerun the exact case, and then run its suite.
+5. Run broader suites only after the focused case is stable.
+6. Record environment, timestamp, package/source revision, command,
+   execution/correlation reference, verdict class, and gap owner in
+   `learning/learning.md` or the plan-defined evidence location.
+
+## Verdict law
+
+| Observation | Verdict |
+| --- | --- |
+| Hard assertions and intended business outcome pass | `PASS` |
+| Intended denial or safe stop occurs with no forbidden mutation | `PASS_EXPECTED_STOP` |
+| `expected.soft: true` turns a mismatch into a warning | `GAP`; never `VERIFIED` |
+| A prerequisite or required human action is absent | `BLOCKED` with the missing row |
+| Runtime or CLI is defective and the run is reproducible | `PRODUCT_GAP` |
+| Role Assistant, Knowledge, or Evidence content is wrong while the product behaves correctly | `PACKAGE_GAP` |
+
+An exit code `0`, CLI `PASS`, lifecycle smoke, or certification level cannot
+replace the applicable business verdict. An expected safe stop is not ordinary
+success: name the denied or waiting state and prove that no forbidden mutation
+occurred.
+
+## Assertion quality
+
+- Release and prove cases use hard lifecycle and Result assertions. Soft cases
+  are exploratory and cannot establish READY or VERIFIED.
+- Mutation cases assert the exact required and forbidden capabilities,
+  `expected.honesty.requireWorkResult`, completion, and a meaningful
+  `expected.honesty.minResourceChanges` value.
+- Read-only cases forbid mutation capabilities. Authority cases assert the
+  intended denial, question, approval wait, or safe stop.
+- Do not weaken an assertion to accommodate a failure. Classify the gap and
+  repair its owner.
+
+## Fixtures, identity, and cleanup
+
+- Stable shared identities are read-only unless the integration README names
+  them as approved mutable subjects.
+- Give mutable cases collision-safe explicit values. Generate and write those
+  values into the case through normal repository editing before the run; do not
+  claim that an interpolation token exists unless current CLI help, schema,
+  source, and tests establish it.
+- Share an identity across cases only for a documented suite dependency.
+- Never inject a hidden primary key, actor, business role, API key, or
+  authorization dimension to make a case pass.
+- Cleanup must be explicit, bounded to the designated subject, and separately
+  authorized when destructive.
+
+## ABAC and replay
+
+Every authority-sensitive scenario needs an allowed case and an outside-scope
+or denied case. Nested calls must preserve the same actor and business-role
+context. Ambiguous identity must ask or stop safely, never select a convenient
+record. Retry and replay cases must prove there is no duplicate resource and no
+double-counted Evidence.
+
+## Human Evidence boundary
+
+Agents may author candidates, run source executions, and inspect proposals when
+authorized. They must not certify, activate, reject, or deactivate Evidence for
+a human unless the current user explicitly authorizes that product action and
+the product workflow permits it. A run paused at certification or activation is
+`BLOCKED_BY_HUMAN`, not failed. Later proof must show Evidence was actually
+Applied in execution; catalog presence alone is insufficient. See
+[Evidence lifecycle](../../aifabrix-prove/references/evidence-lifecycle.md).
+
+## Root-cause routing
+
+| Finding | Owner / next action |
+| --- | --- |
+| Auth, environment, or worker unavailable | Report the exact prerequisite |
+| Duplicate or stale test data | Fixture owner; preserve the trail and repair safely |
+| Soft or incomplete expectation | Case author; strengthen without changing product behavior |
+| Missing operation, certification, or capability | Connected System package |
+| Runtime loop, wrong identity binding, or false success | Product gap with execution evidence |
+| Wrong prompt, Knowledge, or Evidence definition | Role Assistant package |
+| Evidence certification or activation required | Human governance gate |
+
+Do not conceal a lower-layer gap in Knowledge or build a Role Assistant-local
+imitation of a missing Connected System capability.
+
+For an upsert finding, route local manifest repair to Connected System
+ownership and rerun the exact failed proof. If the external source cannot
+support exact business-identity lookup or uniqueness, state what happened,
+what cannot be repaired by AI, the duplicate or wrong-record-update risk, the
+safe alternative, and how future connectors should prevent it. Keep readiness
+blocked or qualified as reported by validation; never substitute create,
+weaken the no-duplicate assertion, or clear the warning because an unrelated
+case passed.

package/templates/agent-kit/skills/shared/interaction.md

@@ -0,0 +1,83 @@
+# Structured choices and phase gates
+
+This file owns interactive choices for every Agent Kit skill. Use the same behavior in
+Cursor, Claude, and Codex; host-specific tool names do not change the workflow.
+
+## Show choices in the host control
+
+When the user must choose between discrete actions, invoke the host's native structured
+question control instead of printing a `Choose:` block in chat:
+
+| Host | Native control |
+| --- | --- |
+| Cursor | `AskQuestion` |
+| Claude | `AskUserQuestion` |
+| Codex | `request_user_input` |
+
+Give the control a short header, one direct question, and mutually exclusive options.
+Put the recommended option first, label it `(Recommended)`, and add one short description
+of its effect. Keep the stable option ids below as the workflow result even when a host
+returns a label rather than an id.
+
+If the host supplies its own free-form **Other** choice, map that response to the matching
+`*-other` id. Otherwise include an explicit **Something else** option. If no structured
+question control is available, show the same choices as a numbered list and wait for one
+answer. Never continue merely because an option was recommended.
+
+Do not open a control when the user already made an unambiguous choice in the current
+turn. Treat that choice exactly like the corresponding control result.
+
+## Bare-invocation routes
+
+Ask once and proceed only on an explicit choice.
+
+| Option id | Control label | Means |
+| --- | --- | --- |
+| `route-normal` | Run normal path (Recommended) | Run the normal path for this skill through to its gate, stopping at each phase gate |
+| `route-check` | Inspect and test only | Run validation, checks, and status with no publish or promotion |
+| `route-other` | Something else | Collect the action in the control's free-form response |
+| `next-stop` | Stop here | End without further action |
+
+`route-normal` still stops at every phase gate and still needs `next-yes` to continue. It
+is a route, not permission to run the whole lifecycle unattended.
+
+## After success
+
+Offer the next eligible phase with the structured question control. Proceed only on
+`next-yes`.
+
+Shared option ids: `next-yes` · `next-no` · `next-stop`.
+
+| Completed | Next offer |
+| --- | --- |
+| aifabrix-plan PLAN_READY | connected-system validate |
+| connected-system READY | connected-system build |
+| connected-system BUILT | connected-system publish |
+| connected-system PASS or PASS_WITH_SKIPS | archive (separate) and/or prove validate |
+| prove READY / BUILT / UPDATED | prove next phase |
+| prove PASS or PASS_WITH_SKIPS | iterate validate/build |
+
+Archive is a distinct user decision (`archive-yes` / `archive-no`). Never archive as a
+side effect of PASS.
+
+## On gaps
+
+- NEEDS_DECISIONS: ask about every challenge row with the structured control. No
+  `cust-next`.
+- BLOCKED / FAIL / NEEDS_FIXES / ABORTED: do not offer the next phase as if success.
+
+A phase gate is per-gate, not overall. Offer the next phase only when the **Delivery** row
+supports it; a passing package gate beside `Delivery: NEEDS_FIXES` is not success and the
+offer must name what is still open.
+
+## Phase detection (connected-system and prove)
+
+1. Explicit phase from the user
+2. Ask with the structured control, offering the bare-invocation routes above
+
+There is no third step. Package and plan state decide what you *recommend*, never what you
+run: a bare invocation reports status and stops ([status.md](status.md)). Inferring "the
+safe next eligible phase" is what makes a skill start working before the user has said
+what they want.
+
+Never silently run the following phase after success.

package/templates/agent-kit/skills/shared/status.md

@@ -25,18 +25,9 @@ they cannot see coming.
 
 ## Offer the route, do not choose it
 
-Ask once, with these options. Proceed only on an explicit choice.
-
-| Option id | Means |
-| --- | --- |
-| `route-normal` | Run the normal path for this skill through to its gate, stopping at each phase gate |
-| `route-check` | Inspect and test only — validation, checks and status, no publish or promotion |
-| `route-other` | Something else; ask what |
-| `next-stop` | Stop here |
-
-`route-normal` still stops at every phase gate and still needs `next-yes` to continue
-([interaction.md](../aifabrix-plan/references/interaction.md)). It is a route, not a
-licence to run the whole lifecycle unattended.
+Use the host's native selection control and the canonical route options in
+[interaction.md](interaction.md). Proceed only on an explicit choice. Do not print a
+`Choose:` block when a structured question control is available.
 
 ## Always report the combined matrix
 

package/templates/applications/builder-api/application.yaml

@@ -5,7 +5,7 @@ app:
   description: 'Business Transformation services — HTTP orchestration for connected-system workspace lifecycle via Dataplane Enterprise MCP and governance APIs.'
   type: webapp
   language: typescript
-  version: 2.60.0
+  version: 2.61.2
 
 # Image Configuration
 image:

package/templates/applications/builder-api/env.template

@@ -23,11 +23,15 @@ MAX_UPLOAD_TIMEOUT_MS=300000
 # =============================================================================
 # url:// resolves after kv:// at resolve time (see docs/configuration/resolve-running-urls.md)
 
+# Governed configuration uses per-application client credentials by default. The SDK loads
+# its bootstrap snapshot and refreshes it automatically within two minutes; consumers decide
+# whether a changed key also requires an internal client or resource to be recreated.
+MISO_AUTH_MODE=client-credentials
 # Registered OAuth client (populated by aifabrix app register / bootstrap — same as dataplane)
 MISO_CLIENTID=kv://builder-api-client-idKeyVault
 MISO_CLIENTSECRET=kv://builder-api-client-secretKeyVault
 
-# Internal: controller API for token validation (supports all miso-controller auth modes)
+# Private service-to-service controller origin. Public or remote controller origins require HTTPS.
 MISO_CONTROLLER_URL=url://miso-controller-internal
 # Public: OAuth profile and remaining-step links shown to vendors (not Docker DNS)
 MISO_CONTROLLER_PUBLIC_URL=url://miso-controller-public

package/templates/applications/dataplane/application.yaml

@@ -5,7 +5,7 @@ app:
   description: "AI Fabrix Dataplane is a secure, in-tenant integration and automation layer that supplies governed, normalized, and explainable enterprise data to AI agents. Using CIP as a declarative standard, it enforces RBAC and ABAC, executes integrations, and exposes trusted data via MCP and OpenAPI."
   type: webapp
   language: python # Explicitly specify Python language
-  version: 2.0.74
+  version: 2.0.79
 # Image Configuration
 # Set tag to match your build (example: aifabrix build dataplane -t 1.0.0).
 # Registry is required so the controller can pull the image (avoids docker-not-found on the controller host).