@aifabrix/builder 2.59.0 → 2.61.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.59.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,9 +132,9 @@
     }
   },
   "dependencies": {
-    "@aifabrix/miso-client": "4.23.1",
+    "@aifabrix/miso-client": "5.0.3",
     "@azure/identity": "4.11.1",
-    "adm-zip": "^0.6.0",
+    "adm-zip": "^0.6.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "axios": "^1.18.1",

package/templates/README.md

@@ -23,9 +23,10 @@ Application templates are folder-based and located under `templates/applications
 | `aifabrix-miso/builder/miso-controller/` (`env.template`, `rbac.yaml`, `application.yaml`) | `templates/applications/miso-controller/` |
 | `aifabrix-miso/builder/keycloak/` (`env.template`, `application.yaml`, `Dockerfile`, `cimd-lenient-parse/`) | `templates/applications/keycloak/` |
 | `aifabrix-miso/infrastructure/marketplace/` (`main.json`, `createUiDefinition.json`) | `templates/marketplace/` |
+| `aifabrix-miso/packages/miso-controller/configs/infra.parameter.yaml` | `lib/schema/infra.parameter.yaml` |
 | `aifabrix-dataplane/builder/dataplane/` (`env.template`, `rbac.yaml`, `application.yaml`) | `templates/applications/dataplane/` |
 
-**Schema master (dataplane):** Also copies dataplane `app/schemas/json/` core integration schemas + `type/*` and `configs/deployment-rules.yaml` into `lib/schema/` (same contract as dataplane `make sync-json`). Do not hand-edit those mirrors — edit dataplane SSOT, then sync. Builder-owned schemas in `lib/schema/` (wizard, infra, etc.) are left alone.
+**Schema master (dataplane):** Also copies dataplane `app/schemas/json/` core integration schemas + `type/*` and `configs/deployment-rules.yaml` into `lib/schema/` (same contract as dataplane `make sync-json`). Do not hand-edit those mirrors — edit dataplane SSOT, then sync. `lib/schema/infra.parameter.yaml` is the Miso catalog mirror above; other Builder-owned schemas in `lib/schema/` (wizard and the rest) are left alone.
 
 Overrides: `AIFABRIX_MISO_SRC`, `AIFABRIX_DATAPLANE_SRC` / `AIFABRIX_DATAPLANE_ROOT` (repo roots). Install with `aifabrix up-platform` / `up-builder-api` — do not hand-edit the template copies as primary.
 

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

@@ -1,5 +1,5 @@
 schemaVersion: "1"
-kitVersion: "1.1.2"
+kitVersion: "1.2.1"
 minimumBuilderVersion: "2.54.2"
 skills:
   - aifabrix-plan
@@ -26,6 +26,9 @@ managed:
   - source: workspace/README.md
     target: README.md
     mode: if-missing
+  - source: workspace/BUILDER_IMPROVEMENT_FINDINGS.md
+    target: BUILDER_IMPROVEMENT_FINDINGS.md
+    mode: if-missing
 optional:
   - source: adapters/cursor/commands
     target: .cursor/commands

package/templates/agent-kit/instructions/AGENTKIT.md

@@ -97,7 +97,7 @@ mobile app (Code). That is not `claude --cloud` (a separate cloud VM). Claude
 aifabrix agent-kit start claude
 ```
 
-tmux session name defaults to this folder. Remote Control name is `hostname-user-folder` (for example `builder01-dev03-aifabrix-docs`). Override with `--name`; opt out with `--no-remote-control` and/or `--skip-approve-all`. Detach: `Ctrl-b` then `d`. Reattach: `tmux attach -t <folder>`. Use `aifabrix agent-kit list` and `agent-kit kill <folder>` to manage sessions. Same account on phone and PC (`claude auth login`, Pro/Max/Team — not an API key). On the phone: Claude app → **Code**. Skills: `/aifabrix-plan` (and the other `/aifabrix-*` names). First `claude` must run inside this workspace, not your home directory. Full notes: `.agents/skills/shared/hosts.md`.
+tmux session name defaults to this folder. Remote Control name is `hostname-user-folder` (for example `devhost-alice-acme-workspace`). Override with `--name`; opt out with `--no-remote-control` and/or `--skip-approve-all`. Detach: `Ctrl-b` then `d`. Reattach: `tmux attach -t <folder>`. Use `aifabrix agent-kit list` and `agent-kit kill <folder>` to manage sessions. Same account on phone and PC (`claude auth login`, Pro/Max/Team — not an API key). On the phone: Claude app → **Code**. Skills: `/aifabrix-plan` (and the other `/aifabrix-*` names). First `claude` must run inside this workspace, not your home directory. Full notes: `.agents/skills/shared/hosts.md`.
 {{/if}}
 {{#if codex}}
 

package/templates/agent-kit/instructions/root.AGENTS.md

@@ -14,6 +14,8 @@ Do not edit platform product source (`aifabrix-dataplane`, `aifabrix-miso`, `aif
 
 Vendor limits, tenant ids, credentials, PII stance, partitions, and the designated mutation subject live only in `integration/<systemKey>/README.md`.
 
+`agent-kit update` rewrites `.agents/skills/**`, `AGENTKIT.md`, and managed sections; `--force` discards local edits. Do not edit them: file gaps in `BUILDER_IMPROVEMENT_FINDINGS.md`, sanitized. Never weaken a gate to clear one. Routing: `.agents/skills/shared/feedback.md`.
+
 ## First greeting
 
 On a first “Hi”, start with the business problem in plain language. Explain

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

@@ -10,10 +10,17 @@ description: >
 # aifabrix-connected-system
 
 Phases: `plan` | `validate` | `build` | `publish`.
-Resolve phase: explicit argument → plan/package state → safe next → ask once.
+
+**No phase argument means report only.** Inspect, print the combined status matrix,
+recommend one next phase, and stop. Do not upload, deploy, advance a plan task, create
+proof assets, run cases, or mutate anything until the user names a phase or picks a route:
+[status.md](../shared/status.md).
+
+Resolve phase: explicit argument → ask. Package state informs the recommendation, never
+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 |
 | --- | --- | --- |
@@ -22,6 +29,28 @@ Stop at the phase gate. Do not run the next phase without `next-yes`
 | build | READY | BUILT |
 | publish | package exists and local validate passes | PASS or PASS_WITH_SKIPS |
 
+READY and BUILT are **package** gates: they describe files on disk, not a working or
+published system. Report them qualified, beside the Delivery row
+([status.md](../shared/status.md)).
+
+## Publish and certification verdicts
+
+Compute the verdict with
+[scripts/delivery-verdict.js](scripts/delivery-verdict.js) from what you observed; do not
+choose it by narrative.
+
+| Observation | Verdict |
+| --- | --- |
+| Online state Draft | publish incomplete; prove BLOCKED; Delivery NEEDS_FIXES |
+| Operations FAILED | NEEDS_FIXES |
+| Known ABAC, persistence, capability, or live-evidence failure | NEEDS_FIXES while open |
+| Bronze or TECHNICALLY_READY alone | not PASS |
+| Online Published **and** acceptable Operations, Trust, Governance and live evidence | PASS |
+| The above with only explicitly allowed skips | PASS_WITH_SKIPS |
+
+`PASS_WITH_SKIPS` covers skips the user allowed by name. It may never cover a known
+failure, an unrun gate, or a gate whose result you did not see.
+
 Read current CLI help before composing commands. You own orchestration, not CLI implementation.
 Host runtimes (local vs SSH): [hosts.md](../shared/hosts.md).
 CLI login from chat: [login.md](../shared/login.md).
@@ -38,6 +67,8 @@ 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
 - [production-safety.md](references/production-safety.md) — designated subject, credential-deferred E2E
@@ -52,6 +83,8 @@ System key: argument → active plan → sole `integration/` folder → ask once
 - Upload without deploy is not published and not PASS
 - No system-level sync of views
 - No publish continuation after an unresolved hard failure
+- A known failure stays open until that same concern is rerun and passes
+- No bare READY/BUILT/PASS headline when Delivery is NEEDS_FIXES or BLOCKED
 
 ## Trigger examples
 

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-connected-system/scripts/delivery-verdict.js

@@ -0,0 +1,176 @@
+/**
+ * Delivery verdict for a customer Connected System and Role Assistant.
+ *
+ * The agent records what it observed; this decides the verdict. Keeping the decision here
+ * rather than in skill prose means a passing package cannot be narrated into a passing
+ * delivery: precedence is computed, not chosen.
+ *
+ * Gates are reported separately on purpose. A package can be BUILT while the delivery
+ * needs fixes and prove is blocked, and all three are true at once.
+ *
+ * @fileoverview Deterministic status matrix and overall verdict for customer delivery skills
+ */
+
+'use strict';
+
+/** Worst-first. A later gate never improves an earlier one. */
+const RANK = ['BLOCKED', 'NEEDS_FIXES', 'PASS_WITH_SKIPS', 'PASS'];
+const UNKNOWN = 'UNKNOWN';
+
+/**
+ * @param {string} a First verdict
+ * @param {string} b Second verdict
+ * @returns {string} The worse of the two
+ */
+function worse(a, b) {
+  const left = RANK.indexOf(a);
+  const right = RANK.indexOf(b);
+  if (left < 0) return b;
+  if (right < 0) return a;
+  return left <= right ? a : b;
+}
+
+/**
+ * Trim and uppercase an observed field. Missing values become an empty string.
+ * @param {*} value Observed field
+ * @returns {string} Normalized token
+ */
+function norm(value) {
+  return String(value === undefined || value === null ? '' : value).trim().toUpperCase();
+}
+
+/**
+ * Published is the only online state that permits publish completion or live prove.
+ * @param {object} signals Observed signals
+ * @returns {{ state: string, published: boolean, known: boolean }} Online state
+ */
+function onlineState(signals) {
+  const state = norm(signals.onlineState) || UNKNOWN;
+  return {
+    state,
+    published: state === 'PUBLISHED',
+    known: state === 'PUBLISHED' || state === 'DRAFT'
+  };
+}
+
+/**
+ * Builder's pillar verdicts are VERIFIED, FAILED, NOT_VERIFIED and NOT_APPLICABLE
+ * (`lib/lifecycle/product-model.js`). NOT_VERIFIED is not a pass — it is the state a pillar
+ * sits in until it has actually been proved, and treating it as neutral is how an
+ * unverified system gets reported as delivered. A gate that was never run is UNKNOWN.
+ * @param {object} gate Observed gate result
+ * @returns {string} Normalized verdict
+ */
+function gateVerdict(gate) {
+  if (!gate) return UNKNOWN;
+  const verdict = norm(gate.verdict);
+  if (!verdict || verdict === 'NOT_RUN' || verdict === 'SKIPPED') return UNKNOWN;
+  if (verdict === 'VERIFIED' || verdict === 'PASSED' || verdict === 'PASS') return 'PASS';
+  if (verdict === 'NOT_APPLICABLE') return 'PASS';
+  if (verdict === 'FAILED' || verdict === 'FAIL' || verdict === 'NOT_VERIFIED') return 'NEEDS_FIXES';
+  return 'NEEDS_FIXES';
+}
+
+/**
+ * Failures stay active until the same concern is rerun and passes, so a later structural
+ * success cannot clear an earlier runtime, governance, persistence, or E2E failure.
+ * @param {Array} knownFailures Recorded failures
+ * @returns {Array} Failures still open
+ */
+function openFailures(knownFailures) {
+  const rows = Array.isArray(knownFailures) ? knownFailures : [];
+  return rows.filter(row => row && row.resolved !== true && norm(row.resolved) !== 'TRUE');
+}
+
+/**
+ * One status-matrix cell: verdict plus an optional percent.
+ * @param {object} gate Observed gate result
+ * @returns {string} Display text
+ */
+function describeScore(gate) {
+  if (!gate) return UNKNOWN;
+  const verdict = norm(gate.verdict) || norm(gate.category) || UNKNOWN;
+  const percent = gate.percent === undefined || gate.percent === null ? '' : ` ${gate.percent}%`;
+  return `${verdict}${percent}`;
+}
+
+/**
+ * Overall delivery verdict. PASS needs a published system and acceptable Operations,
+ * Trust, Governance and live-evidence results; an unrun gate is not a pass. BLOCKED is
+ * reserved for a delivery that cannot be assessed or was explicitly stopped — a draft
+ * system is fixable work, so it reports NEEDS_FIXES.
+ * @param {object} signals Observed signals
+ * @returns {string} BLOCKED | NEEDS_FIXES | PASS_WITH_SKIPS | PASS
+ */
+function overallVerdict(signals) {
+  const online = onlineState(signals);
+  if (!online.known || signals.blocked === true) return 'BLOCKED';
+  let verdict = online.published ? 'PASS' : 'NEEDS_FIXES';
+  for (const gate of [signals.operations, signals.trust, signals.governance, signals.liveEvidence]) {
+    const result = gateVerdict(gate);
+    verdict = worse(verdict, result === UNKNOWN ? 'NEEDS_FIXES' : result);
+  }
+  if (openFailures(signals.knownFailures).length > 0) verdict = worse(verdict, 'NEEDS_FIXES');
+  const skips = Array.isArray(signals.allowedSkips) ? signals.allowedSkips : [];
+  if (verdict === 'PASS' && skips.length > 0) return 'PASS_WITH_SKIPS';
+  return verdict;
+}
+
+/**
+ * Prove readiness is a business-case gate. Package validation, pipeline checks, a Bronze
+ * certification or TECHNICALLY_READY never establish it on their own.
+ * @param {object} signals Observed signals
+ * @returns {string} READY | BLOCKED
+ */
+function proveReadiness(signals) {
+  const overall = overallVerdict(signals);
+  if (overall !== 'PASS' && overall !== 'PASS_WITH_SKIPS') return 'BLOCKED';
+  const ra = signals.roleAssistant || {};
+  // `role-assistant test --json` gives the verdict. Availability is an operator action with
+  // no CLI surface, so it must be confirmed explicitly; unconfirmed is not available.
+  if (gateVerdict(ra) !== 'PASS' || norm(ra.availability) !== 'AVAILABLE') return 'BLOCKED';
+  const cases = signals.cases || {};
+  if (cases.happy !== true || cases.safeStop !== true) return 'BLOCKED';
+  if (signals.authorityConfirmed !== true) return 'BLOCKED';
+  return 'READY';
+}
+
+/**
+ * Every row the skills must report, in a fixed order.
+ * @param {object} signals Observed signals
+ * @returns {Array<{ gate: string, value: string }>} Status matrix rows
+ */
+function statusMatrix(signals) {
+  const ra = signals.roleAssistant || {};
+  const availability = `${norm(ra.availability) || UNKNOWN}/${norm(ra.verdict) || UNKNOWN}`;
+  return [
+    { gate: 'Package', value: norm(signals.packageGate) || UNKNOWN },
+    { gate: 'Online', value: onlineState(signals).state },
+    { gate: 'AI Readiness', value: describeScore(signals.aiReadiness) },
+    { gate: 'Operations', value: describeScore(signals.operations) },
+    { gate: 'Trust', value: describeScore(signals.trust) },
+    { gate: 'Governance', value: describeScore(signals.governance) },
+    { gate: 'Role Assistant', value: availability },
+    { gate: 'Prove readiness', value: proveReadiness(signals) },
+    { gate: 'Delivery', value: overallVerdict(signals) }
+  ];
+}
+
+/**
+ * A headline may not claim success the overall verdict does not support.
+ * @param {object} signals Observed signals
+ * @returns {boolean} True when a bare READY, BUILT or PASS headline is forbidden
+ */
+function forbidsSuccessHeadline(signals) {
+  const overall = overallVerdict(signals);
+  return overall === 'BLOCKED' || overall === 'NEEDS_FIXES';
+}
+
+module.exports = {
+  worse,
+  statusMatrix,
+  overallVerdict,
+  proveReadiness,
+  openFailures,
+  forbidsSuccessHeadline
+};

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

@@ -12,8 +12,11 @@ description: >
 Input: business specification and optional `systemKey`.
 Output: one delivery plan from [plan-template.md](references/plan-template.md).
 
+Named with no specification, report what exists and ask; do not start writing a plan from
+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).
 
@@ -29,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

@@ -12,12 +12,36 @@ description: >
 Phases: `validate` | `build` | `prove`.
 Loop: validate ↔ build ↔ prove ↔ learn.
 
+**No phase argument means run prove-readiness validation only.** Report the combined status
+matrix and the readiness verdict, recommend one next phase, and stop. Do not build proof
+assets, run cases, publish, or promote: [status.md](../shared/status.md).
+
 `READY` means prove-ready, not permission to stop authoring. Build may run without READY.
 
+## Prove readiness
+
+READY requires **all** of:
+
+- Connected System PASS, or PASS_WITH_SKIPS whose skips the user allowed by name
+- online state Published
+- Operations not failed
+- relevant governance scenarios passed
+- Role Assistant available and verified
+- happy and safe-stop cases present for the scenarios in scope
+- authority, test subjects, and required business inputs confirmed
+
+Anything short of all of them is BLOCKED, reported with the row that blocks it.
+[delivery-verdict.js](../aifabrix-connected-system/scripts/delivery-verdict.js) computes it.
+
+Package validation, pipeline checks, Bronze certification and TECHNICALLY_READY are **not**
+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).
 
@@ -38,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,13 @@ 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).
 
 ## Preconditions
 
@@ -22,11 +27,32 @@ aifabrix role list --page-size 1000
 Catalog Business Role and an active user binding are prerequisites.
 Connected Systems this assistant needs must be dataplane **published** (deploy, not upload-only).
 
+## Readiness gate
+
+Report the assistant as available and verified only when every row holds. Any missing row
+means NOT_VERIFIED, named by row — never a blanket claim.
+
+| Row | Established by |
+| --- | --- |
+| Active catalog role | `aifabrix role list --page-size 1000` |
+| Required Connected Systems published **and** certified | `show --online` plus their Delivery verdict |
+| Subscribed capabilities available | capability check against those systems |
+| OpenAPI published | `role-assistant test --json` → `openApiPublished` |
+| Lifecycle verified | `role-assistant test --json` → `verdict` is `VERIFIED` |
+| Worker available | operator "Make available"; **no CLI surface** — confirm explicitly or report UNKNOWN |
+| Happy and safe-stop cases discoverable | cases present for the scenarios in scope |
+
+A published Connected System that is not certified does not satisfy row two. `verdict`
+`NOT_VERIFIED` is not a pass, and a `certification.level` such as `BRONZE` never
+substitutes for it.
+
 ## Workflow
 
 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.
 
@@ -41,3 +67,4 @@ Connected Systems this assistant needs must be dataplane **published** (deploy,
 ## 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.