@aifabrix/builder 2.60.0 → 2.62.0

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/utils/token-manager.js

@@ -10,7 +10,6 @@
  */
 
 const config = require('../core/config');
-const logger = require('./logger');
 const { maskSensitiveData } = require('./log-redaction');
 const {
   refreshClientToken,
@@ -205,12 +204,17 @@ async function tryClientTokenAuth(environment, appName, controllerUrl) {
   return null;
 }
 
-function throwNoDeploymentAuth(credentialApp) {
-  const err = new Error(
-    `No authentication method available. For CI: set AIFABRIX_DEPLOYMENT_AUTH=client-credentials and MISO_CLIENTID/MISO_CLIENTSECRET in .env or '${credentialApp}-client-idKeyVault' in secrets.local.yaml. For interactive use: aifabrix login`
-  );
+// Two causes reach here: no credentials at all, or credentials the controller rejected.
+// Saying "put it in secrets.local.yaml" for the second sends the reader after a key that is
+// already present and simply not valid, so name the rejection instead.
+function throwNoDeploymentAuth(credentialApp, exchangeError) {
+  const err = new Error(exchangeError
+    ? `Client credentials for '${credentialApp}' were rejected by the controller: ${exchangeError.message}. ` +
+      `Re-issue them with: aifabrix login && aifabrix app rotate-secret ${credentialApp}`
+    : `No authentication method available. For CI: set AIFABRIX_DEPLOYMENT_AUTH=client-credentials and MISO_CLIENTID/MISO_CLIENTSECRET in .env or '${credentialApp}-client-idKeyVault' in secrets.local.yaml. For interactive use: aifabrix login`);
   err.statusCode = 401;
   err.authFailure = true;
+  if (exchangeError) err.cause = exchangeError;
   throw err;
 }
 
@@ -262,8 +266,10 @@ async function getDeploymentAuth(controllerUrl, environment, appName, options =
           controller: controllerUrl
         };
       }
-    } catch {
-      // Refresh failed; fall through to throw below
+    } catch (err) {
+      // Keep it: credentials existed and the controller turned them down, which is a
+      // different problem from having none, and the only place that fact is observable.
+      throwNoDeploymentAuth(credentialApp, err);
     }
   }
 
@@ -341,7 +347,7 @@ async function forceRefreshDeviceToken(controllerUrl) {
 
   // Must have refresh token to force refresh
   if (!tokenInfo.refreshToken) {
-    logger.warn('Cannot refresh: no refresh token available. Please login again using: aifabrix login');
+    warnRefreshFailureOnce(controllerUrl, 'Cannot refresh: no refresh token available. Please login again using: aifabrix login');
     return null;
   }
 

package/lib/utils/url-public-path-prefix.js

@@ -1,18 +1,20 @@
 /**
- * Plan 117 URL path prefix for url://public (dev/tst only when gated).
+ * Plan 117 URL path prefix for url://public (scoped environments only when gated).
  *
- * @fileoverview baseEffective ∧ derived envKey ∈ {dev,tst}. Caller must pass prefix only when `traefik` is on (see url-declarative-resolve).
+ * @fileoverview baseEffective ∧ derived envKey ∈ SCOPED_RUN_ENVIRONMENTS. Caller must pass prefix only when `traefik` is on (see url-declarative-resolve).
  * @author AI Fabrix Team
  * @version 1.0.0
  */
 
 'use strict';
 
+const { isScopedRunEnvironmentKey } = require('./environment-scoped-resources');
+
 /**
  * @param {boolean} useEnvironmentScopedResources - config gate
  * @param {boolean} appEnvironmentScopedResources - application.yaml
  * @param {string} derivedEnvKey - from client id (dev|tst|pro|miso)
- * @returns {string} '' | '/dev' | '/tst'
+ * @returns {string} '' | '/dev' | '/tst' | '/pro'
  */
 function computePublicUrlPathPrefix(useEnvironmentScopedResources, appEnvironmentScopedResources, derivedEnvKey) {
   const baseEffective = Boolean(useEnvironmentScopedResources) && Boolean(appEnvironmentScopedResources);
@@ -20,13 +22,7 @@ function computePublicUrlPathPrefix(useEnvironmentScopedResources, appEnvironmen
     return '';
   }
   const k = String(derivedEnvKey || '').toLowerCase();
-  if (k === 'dev') {
-    return '/dev';
-  }
-  if (k === 'tst') {
-    return '/tst';
-  }
-  return '';
+  return isScopedRunEnvironmentKey(k) ? `/${k}` : '';
 }
 
 module.exports = {

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.62.0",
   "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",
@@ -34,11 +35,12 @@
     "lint:fix": "eslint . --ext .js --fix",
     "test": "node tests/scripts/test-wrapper.js",
     "build": "npm run lint && npm run test",
-    "build:ci": "npm run lint && npm run check:schema-sync && npm run check:flags && npm run check:cli-help && npm run test:ci",
+    "build:ci": "npm run lint && npm run check:schema-sync && npm run check:flags && npm run check:cli-help && npm run check:mirrored-templates && npm run test:ci",
     "test:ci": "bash tests/scripts/ci-simulate.sh",
     "check:schema-sync": "node scripts/check-datasource-test-run-schema-sync.js",
     "check:flags": "jest tests/lib/schema/flag-map-validation-run.test.js --runInBand --config jest.config.default.js",
     "check:cli-help": "node scripts/check-cli-help-examples.js",
+    "check:mirrored-templates": "node scripts/check-mirrored-templates.js",
     "test:manual": "jest --config jest.config.manual.js --runInBand",
     "test:integration": "jest --config jest.config.integration.js --runInBand",
     "test:integration:fixtures": "jest --config jest.config.integration.fixtures.js --runInBand",
@@ -131,7 +133,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.