@aifabrix/builder 2.59.0 → 2.60.0

package/lib/utils/compose-generate-docker-compose.js

@@ -249,6 +249,18 @@ function buildComposeTemplateContext(ctx) {
     networkName: ctx.networkName,
     containerName: ctx.containerName,
     misoEnvironment: resolveMisoEnvironment(ctx.options),
+    // Containers are run as the invoking host user so bind-mounted files stay writable.
+    // An app that administers its own operating system — creating accounts, managing
+    // sshd — cannot work that way and declares `runAsRoot: true` to opt out.
+    runAsRoot: ctx.appConfig?.runAsRoot === true,
+    // Extra ports for an application serving a second protocol from the same container,
+    // such as SSH beside HTTP. Each host port uses the main port's formula so developers
+    // on one host do not collide.
+    additionalPorts: (ctx.appConfig?.additionalPorts ?? []).map((entry) => ({
+      name: entry.name,
+      containerPort: entry.containerPort,
+      hostPort: ctx.idNum === 0 ? entry.hostPort : entry.hostPort + ctx.idNum * 100
+    })),
     devMountPath: ctx.devMountPath,
     localDataMountPath,
     reloadStartCommand: ctx.reloadStartCommand,

package/lib/utils/docker-build.js

@@ -96,8 +96,15 @@ function handleDockerClose(code, ctx) {
   }
 }
 
-function buildDockerCliArgs(imageName, tag, dockerfilePath, contextPath, buildArgs, noCache) {
+function buildDockerCliArgs(imageName, tag, dockerfilePath, contextPath, buildArgs, options = {}) {
+  const { noCache = false, target } = options;
   const args = ['build', '-t', `${imageName}:${tag}`, '-f', dockerfilePath];
+  // A multi-stage Dockerfile builds its last stage unless told otherwise. `build.target`
+  // lets one Dockerfile serve several images from the same source, which is the only way
+  // an app can ship two variants without duplicating its build.
+  if (target) {
+    args.push('--target', String(target));
+  }
   for (const [key, value] of Object.entries(buildArgs)) {
     if (value !== null && value !== undefined && String(value).length > 0) {
       args.push('--build-arg', `${key}=${String(value)}`);
@@ -111,9 +118,12 @@ function buildDockerCliArgs(imageName, tag, dockerfilePath, contextPath, buildAr
 }
 
 function createDockerSpawnParams(options) {
-  const { imageName, tag, dockerfilePath, contextPath, buildArgs, noCache, env } = options;
+  const { imageName, tag, dockerfilePath, contextPath, buildArgs, noCache, env, target } = options;
   const spawnEnv = { ...process.env, ...(env || {}) };
-  const args = buildDockerCliArgs(imageName, tag, dockerfilePath, contextPath, buildArgs || {}, noCache);
+  const args = buildDockerCliArgs(imageName, tag, dockerfilePath, contextPath, buildArgs || {}, {
+    noCache,
+    target
+  });
   return { spawnEnv, args };
 }
 
@@ -163,7 +173,8 @@ function runDockerBuildProcess(buildOpts) {
     reject,
     env = {},
     buildArgs = {},
-    noCache = false
+    noCache = false,
+    target
   } = buildOpts;
   const { spawnEnv, args } = createDockerSpawnParams({
     imageName,
@@ -172,7 +183,8 @@ function runDockerBuildProcess(buildOpts) {
     contextPath,
     buildArgs,
     noCache,
-    env
+    env,
+    target
   });
   const dockerProcess = spawn('docker', args, {
     shell: process.platform === 'win32',
@@ -192,7 +204,12 @@ function runDockerBuildProcess(buildOpts) {
  * @returns {Promise<void>} Resolves when build completes
  * @throws {Error} If build fails
  */
-async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs = {}, noCache = false) {
+async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs = {}, options = false) {
+  // Historically the sixth argument was the `noCache` boolean. It is now an options
+  // object so a build stage can be named too; the boolean form still works, because
+  // this function is exported and callers outside this module pass it that way.
+  const { noCache = false, target } =
+    typeof options === 'boolean' ? { noCache: options } : options || {};
   const spinner = ora({ text: 'Starting Docker build...', spinner: 'dots' }).start();
   const fsSync = require('fs');
   const path = require('path');
@@ -228,7 +245,8 @@ async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag, b
       reject,
       env: dockerCliEnv,
       buildArgs: resolvedBuildArgs,
-      noCache
+      noCache,
+      target
     });
   });
 }
@@ -251,7 +269,10 @@ async function executeBuild(imageName, dockerfilePath, contextPath, tag, options
     options &&
       (options.cache === false || options.noCache === true || options['no-cache'] === true)
   );
-  await executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs, noCache);
+  await executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs, {
+    noCache,
+    target: options && options.target
+  });
   await applyTagAliases(imageName, tag, resolveTagAliases(tag, options));
 }
 

package/lib/utils/docker-manifest-public-port.js

@@ -81,6 +81,41 @@ async function mergeDockerManifestPublishedPort(envVars, appDoc) {
   envVars[publicPortKey] = String(devIdNum > 0 ? pubBase + devIdNum * 100 : pubBase);
 }
 
+/**
+ * Publish `<NAME>_PUBLIC_PORT` for every `additionalPorts` entry.
+ *
+ * An application serving a second protocol needs to tell clients which port to use, and
+ * that is the *published* host port, not the one it listens on inside the container. The
+ * two differ by the developer-id offset, so a template that types the number by hand
+ * silently disagrees with the manifest the moment either changes — and the application
+ * then advertises a port nothing is listening on.
+ *
+ * Named after the port, so `additionalPorts: [{ name: ssh, hostPort: 2200 }]` gives
+ * `SSH_PUBLIC_PORT`, which an env.template consumes as `${SSH_PUBLIC_PORT}`.
+ *
+ * @param {Object} envVars - Mutated map from buildEnvVarMap
+ * @param {Object|null|undefined} appDoc - application.yaml root
+ * @returns {Promise<void>}
+ */
+async function mergeAdditionalPublishedPorts(envVars, appDoc) {
+  const entries = appDoc && Array.isArray(appDoc.additionalPorts) ? appDoc.additionalPorts : [];
+  if (entries.length === 0) {
+    return;
+  }
+  const devIdNum = await require('./env-map').getDeveloperIdNumber(null);
+  for (const entry of entries) {
+    if (!entry || typeof entry.name !== 'string') {
+      continue;
+    }
+    const base = Number(entry.hostPort);
+    if (!Number.isFinite(base)) {
+      continue;
+    }
+    const key = `${entry.name.trim().toUpperCase().replace(/-/g, '_')}_PUBLIC_PORT`;
+    envVars[key] = String(devIdNum > 0 ? base + devIdNum * 100 : base);
+  }
+}
+
 /**
  * Rewrite first line for the matched *_PUBLIC_PORT after interpolateEnvVars (early kv pass may have wrong value).
  * @param {string} resolved
@@ -111,6 +146,7 @@ function rewriteDockerManifestPublicPortEnvLine(resolved, envVars, appDoc) {
 module.exports = {
   findDockerHostKeyForAppKey,
   publicPortKeyForAppKey,
+  mergeAdditionalPublishedPorts,
   mergeDockerManifestPublishedPort,
   rewriteDockerManifestPublicPortEnvLine
 };

package/lib/utils/platform-resolution.js

@@ -0,0 +1,226 @@
+/**
+ * Platform and environment configuration resolution (plan 200.0).
+ *
+ * The deployment's Azure resource group is matched against the manifest `platforms` list, yielding
+ * `{platform}` and `{platform.name}`. Platform values expand from those, then the matching
+ * `environments` entry overrides by name. The result is one flat set of names that `env.template`
+ * references as `{NAME}`.
+ *
+ * Pure by contract: manifest + resource group + environment key in, resolved set out. No
+ * filesystem, no Azure, no network — the same function must be implementable in Miso and produce
+ * identical output for the shared test vectors.
+ *
+ * @fileoverview Resource-group driven configuration resolution
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** Local Docker has no resource group; every local run resolves as this platform. */
+const LOCAL_PLATFORM = 'dev';
+/** Capture for `*` in a resource pattern: one group-name segment. */
+const NAME_CAPTURE = '[A-Za-z0-9][A-Za-z0-9-]*';
+const NAME_WILDCARD = '*';
+
+function escapeLiteral(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Compiles a `resource` pattern into a matcher.
+ * `{platform}` matches one of `options`; `*` captures a name segment.
+ * @param {Object} entry - Platform entry
+ * @returns {{ regex: RegExp, order: string[] }} Matcher and the capture order
+ */
+function compileResourcePattern(entry) {
+  const order = [];
+  let source = '';
+  const pattern = String(entry.resource || '');
+  const tokens = pattern.split(/(\{platform\}|\*)/);
+  for (const token of tokens) {
+    if (token === '{platform}') {
+      const options = Array.isArray(entry.options) ? entry.options : [];
+      source += `(${options.map(escapeLiteral).join('|')})`;
+      order.push('platform');
+    } else if (token === NAME_WILDCARD) {
+      source += `(${NAME_CAPTURE})`;
+      order.push('name');
+    } else if (token) {
+      source += escapeLiteral(token);
+    }
+  }
+  return { regex: new RegExp(`^${source}$`), order };
+}
+
+/**
+ * @param {Object} entry - Platform entry
+ * @throws {Error} When the entry cannot yield a platform
+ */
+function assertPlatformDeclaration(entry) {
+  const hasToken = String(entry.resource || '').includes('{platform}');
+  const hasOptions = Array.isArray(entry.options) && entry.options.length > 0;
+  if (hasToken && !hasOptions) {
+    throw new Error(`Platform "${entry.resource}" uses {platform} but declares no options`);
+  }
+  if (!hasToken && !entry.platform) {
+    throw new Error(`Platform "${entry.resource}" has no {platform} token, so it must declare platform:`);
+  }
+  if (hasToken && entry.platform) {
+    throw new Error(`Platform "${entry.resource}" declares both {platform} and platform:; use one`);
+  }
+}
+
+function matchEntry(entry, resourceGroup) {
+  assertPlatformDeclaration(entry);
+  const { regex, order } = compileResourcePattern(entry);
+  const found = regex.exec(resourceGroup);
+  if (!found) return null;
+  const captured = {};
+  order.forEach((key, index) => {
+    captured[key] = found[index + 1];
+  });
+  const platform = captured.platform || entry.platform;
+  const name = entry.name === NAME_WILDCARD ? captured.name : entry.name;
+  if (!name) {
+    throw new Error(`Platform "${entry.resource}" uses name: * but the pattern captures no name segment`);
+  }
+  return { entry, platform, name };
+}
+
+/**
+ * Matches a resource group against the manifest platforms.
+ * @param {Array} platforms - Manifest `platforms`
+ * @param {string} resourceGroup - Target Azure resource group
+ * @returns {{ entry: Object, platform: string, name: string }} The single match
+ * @throws {Error} On no match or more than one match
+ */
+function matchPlatform(platforms, resourceGroup) {
+  const entries = Array.isArray(platforms) ? platforms : [];
+  const group = String(resourceGroup || '').trim();
+  if (!group) {
+    throw new Error('A resource group is required to resolve a platform');
+  }
+  const matches = entries.map(entry => matchEntry(entry, group)).filter(Boolean);
+  if (matches.length === 0) {
+    const tried = entries.map(entry => `"${entry.resource}"`).join(', ') || '(none declared)';
+    throw new Error(`Resource group "${group}" matches no platform. Patterns tried: ${tried}`);
+  }
+  if (matches.length > 1) {
+    const ambiguous = matches.map(match => `"${match.entry.resource}"`).join(', ');
+    throw new Error(`Resource group "${group}" matches more than one platform: ${ambiguous}. Make the patterns exclusive.`);
+  }
+  return matches[0];
+}
+
+/**
+ * Expands `{platform}`, `{platform.name}` and `{resourceGroup}` in a value.
+ * @param {string} value - Raw value
+ * @param {Object} context - `platform`, `name`, `resourceGroup`
+ * @returns {string}
+ * @throws {Error} On an unknown token
+ */
+function expandPlatformTokens(value, context) {
+  const text = value === undefined || value === null ? '' : String(value);
+  return text.replace(/\{([a-zA-Z][a-zA-Z.]*)\}/g, (match, token) => {
+    if (token === 'platform') return context.platform;
+    if (token === 'platform.name') return context.name;
+    if (token === 'resourceGroup') return context.resourceGroup;
+    throw new Error(`Unsupported token ${match}; use {platform}, {platform.name} or {resourceGroup}`);
+  });
+}
+
+function applyItems(target, items, context) {
+  for (const item of Array.isArray(items) ? items : []) {
+    target.set(item.name, expandPlatformTokens(item.value, context));
+  }
+}
+
+/**
+ * Local runs have no resource group, but still need platform values. The first entry that can
+ * produce the local platform supplies them; an `environments` entry still overrides by name.
+ * A `*` name cannot be captured without a group, so it resolves to ''.
+ * @param {Array} platforms - Manifest platforms
+ * @returns {{ entry: Object, platform: string, name: string }|null}
+ */
+function matchLocalPlatform(platforms) {
+  const entry = platforms.find(item =>
+    item.platform === LOCAL_PLATFORM ||
+    (Array.isArray(item.options) && item.options.includes(LOCAL_PLATFORM)));
+  if (!entry) return null;
+  return { entry, platform: LOCAL_PLATFORM, name: entry.name === NAME_WILDCARD ? '' : entry.name };
+}
+
+/**
+ * @param {Object} manifest - Application manifest
+ * @param {string} resourceGroup - Target resource group ('' for local Docker)
+ * @returns {{ entry: Object, platform: string, name: string }|null}
+ */
+function matchIfDeclared(manifest, resourceGroup, allowLocalPlatform) {
+  const platforms = manifest && Array.isArray(manifest.platforms) ? manifest.platforms : [];
+  if (platforms.length === 0) return null;
+  if (!resourceGroup) return allowLocalPlatform ? matchLocalPlatform(platforms) : null;
+  return matchPlatform(platforms, resourceGroup);
+}
+
+function environmentEntry(manifest, environment) {
+  const entries = manifest && Array.isArray(manifest.environments) ? manifest.environments : [];
+  return entries.find(item => item.environment === environment) || null;
+}
+
+function applyBuiltIns(values, context, environment) {
+  const builtIns = [
+    // PLATFORM is omitted when nothing determined it, so a consumer fails closed on {PLATFORM}
+    // rather than receiving a guess.
+    ...(context.platform ? [['PLATFORM', context.platform]] : []),
+    ['PLATFORM_NAME', context.name],
+    ['RESOURCE_GROUP', context.resourceGroup],
+    ['ENVIRONMENT', environment]
+  ];
+  // Built-ins never overwrite an authored name of the same spelling.
+  for (const [key, value] of builtIns) {
+    if (!values.has(key)) values.set(key, value);
+  }
+}
+
+/**
+ * Resolves the configuration set for one deployment.
+ * @param {Object} manifest - Application manifest with optional `platforms` / `environments`
+ * @param {Object} target - `resourceGroup` (omitted for local Docker), `environment`, and
+ *   `allowLocalPlatform` (default true). A caller that is not a local run — the Controller, which
+ *   knows the environment but may not know the group — passes false so a missing group resolves no
+ *   platform at all instead of silently claiming `dev`.
+ * @returns {{ platform: string|null, name: string|null, resourceGroup: string|null, values: Object }}
+ */
+function resolveConfiguration(manifest, target = {}) {
+  const resourceGroup = target.resourceGroup ? String(target.resourceGroup).trim() : '';
+  const environment = target.environment ? String(target.environment).trim() : '';
+  const allowLocalPlatform = target.allowLocalPlatform !== false;
+  const matched = matchIfDeclared(manifest, resourceGroup, allowLocalPlatform);
+  const localPlatform = allowLocalPlatform ? LOCAL_PLATFORM : '';
+  const context = {
+    platform: matched ? matched.platform : localPlatform,
+    name: matched ? matched.name : '',
+    resourceGroup
+  };
+
+  const values = new Map();
+  if (matched) applyItems(values, matched.entry.configuration, context);
+  const envEntry = environmentEntry(manifest, environment);
+  if (envEntry) applyItems(values, envEntry.configuration, context);
+  applyBuiltIns(values, context, environment);
+
+  return {
+    platform: context.platform || null,
+    name: matched && matched.name ? matched.name : null,
+    resourceGroup: resourceGroup || null,
+    values: Object.fromEntries(values)
+  };
+}
+
+module.exports = {
+  LOCAL_PLATFORM,
+  matchPlatform,
+  expandPlatformTokens,
+  resolveConfiguration
+};

package/lib/utils/resolve-docker-image-ref.js

@@ -148,16 +148,21 @@ function qualifyRepository(registry, repository) {
 }
 
 /**
- * Deployment/registration image reference (`registry/name:tag`) using the shared precedence.
+ * Deployment/registration image reference (`registry/name:tag`).
+ *
+ * Deliberately ignores the installation registry (`dev set-registry`): a generated manifest is a
+ * committed artifact shared by the team, so it must carry the application's own `image.registry`,
+ * not one developer's local default. `push` applies the installation registry when it publishes,
+ * and an explicit `options.registry` still wins here for CI that targets another registry.
  * @param {Object} variables - Application manifest
  * @param {string} fallbackName - Name when the manifest has no image name or app key
- * @param {Object} [options] - Same options as {@link resolveEffectiveRegistry}
+ * @param {Object} [options] - `registry` (explicit override only)
  * @returns {string}
  */
 function buildManifestImageReference(variables, fallbackName, options = {}) {
   const imageName = variables?.image?.name || variables?.app?.key || fallbackName;
   const tag = variables?.image?.tag || 'latest';
-  const { registry } = resolveEffectiveRegistry(variables, options);
+  const { registry } = resolveEffectiveRegistry(variables, { ...options, installationRegistry: '' });
   return `${qualifyRepository(registry, imageName)}:${tag}`;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.59.0",
+  "version": "2.60.0",
   "description": "AI Fabrix Builder — CLI and developer scripts (pnpm + af)",
   "main": "lib/index.js",
   "bin": {
@@ -133,7 +133,7 @@
   "dependencies": {
     "@aifabrix/miso-client": "4.23.1",
     "@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.0"
 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,7 +10,14 @@ 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)).
@@ -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,7 @@ System key: argument → active plan → sole `integration/` folder → ask once
 
 ## References
 
+- [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 +82,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