software-defence-factory 0.13.1 → 0.15.0

package/README.md

@@ -48,7 +48,7 @@ The runtime supplies policy and six focused skills to its isolated jobs. `init`
 
 Each result belongs to a specific candidate commit and policy. A failed check blocks delivery. Changing the candidate or check policy invalidates earlier evidence. Approval records a handoff; publishing, merging and deployment follow the application's separate authority.
 
-The project dashboard has an **Inbox**, measured **Analytics**, **Agents**, **Skills**, **Automations**, **Definition** and **Infrastructure**. Inbox opens on a shared list/board of loaded repository issues and local work, with status, search and checkbox filters, readiness and linked execution attempts. New issue offers repository templates or a blank creation form. Create an issue on the supported repository provider, then choose Start work separately; local brief execution remains available. CLI `issue` exposes the same intake. Definition lives with settings above the theme control. The CLI reads the same definition and controller state. Agent roles use a selected harness such as Codex or Pi; a worker executes their isolated jobs on a host. See [concepts](docs/concepts.md) and [supported interfaces](docs/interfaces.md). Optional automations belong to the selected harness, which calls Factory CLI/API. Factory runs no cron scheduler. See [provider boundaries](docs/integrations.md).
+The project dashboard has an **Inbox**, measured **Analytics**, **Agents**, **Skills**, **Automations**, **Definition** and **Infrastructure**. Inbox opens on a shared list/board of loaded repository issues and local work, with status, search and checkbox filters, readiness and linked execution attempts. New issue offers repository templates or a blank creation form. Create an issue on the supported repository provider, then choose Start work separately; local brief execution remains available. CLI `issue` exposes the same intake. Definition lives with settings above the theme control. The CLI reads the same definition and controller state. Agent roles use a selected harness such as Codex or Pi, with opt-in private keyless local bindings for local/hybrid setups; a worker executes their isolated jobs on a host. See [concepts](docs/concepts.md) and [supported interfaces](docs/interfaces.md). Optional automations belong to the selected harness, which calls Factory CLI/API. Factory runs no cron scheduler. See [provider boundaries](docs/integrations.md).
 
 The optional **defence** workflow accepts scoped incident evidence and produces a private, read-only draft. It does not monitor production or claim verified recovery. See [defence integration](docs/defence-integration.md).
 

package/bin/software-defence-factory.mjs

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { harnessPreset, parseRoleDefinition, ROLE_CAPABILITIES } from '../factory/role-definition.mjs';
+import { inspectDefinition, previewDefinition, previewRollback } from '../factory/definition-store.mjs';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, openSync, closeSync, rmSync, renameSync, realpathSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 import { randomBytes } from 'node:crypto';
@@ -41,8 +43,7 @@ function init(repo, harness='codex', check='', port=7331, sourceRef='HEAD', deli
   if ([repo,state,ROOT].some(p=>/[,\n\r]/.test(p))) throw new Error('Paths cannot contain commas or line breaks');
   if (runCandidateGit(repo,'rev-parse','--show-toplevel') !== repo) throw new Error('--repo must be the Git root');
   runCandidateGit(repo,'rev-parse','HEAD');
-  const presets={codex:['codex','exec','--json','--ephemeral','--sandbox','danger-full-access','-'],pi:['pi','--mode','json','--print','--no-session','--no-extensions','--skill','/factory-skills'],mock:['node','/opt/factory/mock.mjs']};
-  const argv=harness==='custom'?JSON.parse(flags['command-json'] || 'null'):presets[harness];
+  const argv=harness==='custom'?JSON.parse(flags['command-json'] || 'null'):harnessPreset(harness);
   if (!argv) throw new Error('Select codex, pi, mock or custom with --command-json');
   if (flags.model && ['codex','pi'].includes(harness)) argv.splice(harness==='codex'?argv.length-1:argv.length,0,'--model',flags.model);
   mkdirSync(state,{recursive:true,mode:0o700});state=realpathSync(state);chmodSync(state,0o700);
@@ -198,7 +199,30 @@ try {
   else if(command==='tunnel')await manageService('tunnel',positional[0],state,flags);
   else if(command==='foundation')console.log(foundationSkill().content);
   else if(['definition','workflows','agents','skills'].includes(command)) {
+    if (command === 'definition' && positional.length) {
+      const action = positional[0];
+      if (!['export', 'validate', 'diff', 'apply', 'rollback'].includes(action) || positional.length !== 1) throw new Error('Choose definition export|validate|diff|apply|rollback');
+      let value, bindings;
+      if (['validate', 'diff', 'apply'].includes(action)) {
+        if (!flags.file) throw new Error('--file is required');
+        value = JSON.parse(readFileSync(resolve(flags.file), 'utf8'));
+        if (flags['bindings-file']) bindings = JSON.parse(readFileSync(resolve(flags['bindings-file']), 'utf8'));
+      }
+      let result;
+      if (action === 'export') result = inspectDefinition(state).definition;
+      else if (action === 'rollback' && !flags['expected-revision']) result = previewRollback(state);
+      else if (action === 'validate' && bindings !== undefined && !existsSync(join(state, 'factory.json'))) throw new Error('Local binding validation requires an installation');
+      else if (action === 'validate' && !existsSync(join(state, 'factory.json'))) result = { valid: true, definition: parseRoleDefinition(value), capabilities: ROLE_CAPABILITIES, resolution: 'Requires an installation for inherited settings' };
+      else if (['validate', 'diff'].includes(action)) result = previewDefinition(state, value, bindings);
+      else {
+        if (!flags['expected-revision']) throw new Error('--expected-revision from the current preview is required');
+        result = await api(state, `/api/v1/definition/${action}`, { expected_revision: flags['expected-revision'], ...(action === 'apply' ? { definition: value, ...(bindings === undefined ? {} : { local_bindings: bindings }) } : {}) });
+      }
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(0);
+    }
     const definition=factoryDefinition(configAt(state));
+    definition.role_definition = inspectDefinition(state);
     const value=command==='agents'?definition.agents:command==='skills'?{agents:definition.skills,operators:definition.operator_skills}:definition;
     console.log(JSON.stringify(value,null,2));
   }
@@ -321,6 +345,9 @@ Compatibility executable: software-defence-factory (same runtime and state)
   web probe --state PATH                    Execute the pinned local Chromium readiness probe
   foundation                              Read the operator setup skill; no installation required
   definition | agents | skills            Inspect roles, instructions and installation settings
+  definition export|validate|diff          Portable roles; validate/diff require --file PATH; optional --bindings-file PRIVATE_PATH
+  definition apply --file PATH --expected-revision HASH
+  definition rollback --expected-revision HASH   Idle controller only
   inbox [--page N] [--issue-state open|closed|all] [--source inbox|factory]
                                           Repository backlog (default); factory: execution-only array
   infrastructure | automations            Inspect host/worker and automation state

package/docs/concepts.md

@@ -9,14 +9,14 @@ The CLI `definition` command and dashboard Definition page read that same catalo
 | Controller | One project's queue, policy, HTTP API and dashboard | One Node/SQLite service |
 | Worker | Executes jobs on a host | One local execution process; bounded Docker containers |
 | Harness | Runs an agent | Codex, Pi, a custom command, or synthetic mock |
-| Agent | Responsibility and instructions | Implement, Review, Investigate; one shared harness/model profile |
+| Agent | Responsibility and instructions | Implement, Review, Investigate; inherited or explicit harness/model per role |
 | Skill | Reusable instructions | Six job skills; separate operator Factory Foundation |
 | Workflow | Ordered steps and gates | Software: Implement → Check → Review → Accept; Defence: Investigate |
 | Issue | Bounded work request | Remote issue lives in its provider; a local brief needs no remote issue |
 | Execution | Admitted work and its attempts | Stored in the private SQLite queue with source link and evidence |
 | Provider | Repository issue integration | GitHub adapter first; unknown remotes retain local execution |
 | Automation | External schedule and agent context | Owned by the selected harness; calls Factory CLI/API, no Factory cron |
-| Definition | Effective roles, workflows, skills and settings | Installed method plus private factory.json; read-only catalog |
+| Definition | Effective roles, workflows, skills and settings | Installed method, private settings and explicitly adopted portable role definition |
 
 Inbox combines an explicitly loaded provider page with retained execution
 history in one list/board, grouped by canonical issue identity. Off-page sources
@@ -29,7 +29,8 @@ Accept is an operator gate. Triage/specification precede admission; evaluation
 is separately scoped work, not an automatic hidden agent phase.
 
 All job skills are available read-only. Role instructions identify relevant
-skills; per-role skill/access/harness profiles are not yet supported. Inference
+skills; per-role skill/access controls remain deferred. Harness/model selection
+uses the [role definition contract](definition.md). Inference
 authentication, GitHub identity and SSH access are separate boundaries. Browser
 GitHub sign-in does not configure `gh` on the controller host, and host `gh` auth
 does not sign a browser in. Writing a blank local issue needs neither a GitHub issue nor

package/docs/definition.md

@@ -0,0 +1,310 @@
+# Role definitions (0.15.0)
+
+The portable definition selects harness/model profiles for **Implement**, **Review**
+and **Investigate**. CLI, local API and the existing Agents/Definition pages use
+one parser, resolver, capability matrix and application path. This first #53 slice
+does not make skills, resources, access, workflow gates or schedules editable.
+
+```json
+{
+  "version": 1,
+  "roles": {
+    "implement": { "harness": "inherit" },
+    "review": { "harness": "pi", "model": "anthropic/operator-selected-model" },
+    "investigate": { "harness": "codex", "model": "operator-selected-model", "reasoningEffort": "high" }
+  }
+}
+```
+
+The root accepts exactly `version` and `roles`. Version must be numeric `1`;
+role names are exactly `implement`, `review`, `investigate`. Missing roles and
+missing `harness` mean `inherit`. Each role accepts only `harness`, `model`, `reasoningEffort` and
+`localBinding`; unknown fields, roles, versions and incompatible combinations
+fail explicitly. The authoritative implementation and capability matrix are in
+[role-definition.mjs](../factory/role-definition.mjs), not a second schema copy.
+
+- `inherit` preserves the installed private command, including a custom wrapper.
+  An omitted model inherits the installed model. Model/reasoning overrides require
+  an inherited Codex/Pi adapter; custom and mock commands have no such controls.
+  For an inherited Codex model or effort override, one bounded option parser
+  supports direct `codex exec` argv (also `e`). Model selection replaces
+  separate/attached `-m` and `--model` forms and direct
+  `-c`/`--config model=...` settings. An explicit model emits one `--model VALUE`;
+  `null` removes those inherited selections. Unrelated supported options, their
+  values and the prompt remain intact; new options precede the prompt or `--`.
+  Effort selection replaces direct `model_reasoning_effort` settings in supported
+  separate/attached `-c`/`--config` forms with one setting. Effort-only changes
+  preserve inherited model arguments exactly, without substituting installed
+  model metadata. Model-only changes preserve inherited effort settings.
+  Opaque wrappers, unknown switches/arity, profile selectors (`-p`/`--profile` or
+  config profile layers), nested commands, multiple prompts, options after a
+  positional prompt and duplicate model flags left by an effort-only selection
+  are refused before adoption. Use the Codex preset or correct the private
+  command while stopped. All-inherit commands remain byte-for-byte unchanged.
+- Explicit `codex` or hosted `pi` uses the same maintained preset as `init`, even when
+  the installed harness has the same name. No command, path, privilege, network,
+  credential or provider-authorization argument can enter the portable payload.
+- `model` is a user-selected identifier (1–128 identifier characters, no paths,
+  URLs, whitespace or command switches). Omit it for the explicit harness default;
+  `null` also requests that default. Explicit hosted Pi requires a supported
+  `provider/model` prefix so credential selection is unambiguous. For inherited Pi,
+  a model must agree with any installed private `inferenceProvider`.
+- `localBinding` selects an explicitly adopted private keyless Pi binding instead
+  of a hosted model; see the opt-in contract below.
+- This slice exposes Codex `reasoningEffort` values `low`, `medium`, `high`, passed
+  as `-c model_reasoning_effort="VALUE"`. Omission preserves private/default
+  behavior; it does not attest a detected effort. Pi effort control is unavailable.
+  The [Codex configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference)
+  documents the setting; actual supported levels depend on the selected model.
+  Validation does not call a model or prove availability, quality or readiness.
+
+## Inspect, review and adopt
+
+```sh
+factory definition --state PATH
+factory agents --state PATH
+factory skills --state PATH
+factory definition export --state PATH > factory-roles.json
+factory definition validate --state PATH --file factory-roles.json
+factory definition diff --state PATH --file factory-roles.json
+factory definition apply --state PATH --file factory-roles.json --expected-revision REVISION
+factory definition rollback --state PATH
+factory definition rollback --state PATH --expected-revision REVISION
+```
+
+`definition`, `agents`, `skills`, and compatibility `workflows` remain readable
+while stopped. Export prints only portable JSON. Validate and diff resolve against
+the installation and return the normalized definition, effective selections,
+changes and **current** revision. With no installation, validate performs portable
+syntax/explicit-combination validation and reports that inheritance still needs
+an installation. No account or provider connection is needed for validation.
+Rollback without `--expected-revision` previews the previous definition. Supply
+that revision to perform rollback; it restores the previous selection, not the
+old revision number. Keep `factory-roles.json` in a repository for ordinary code
+review or in a private local file. No filename is automatically discovered or
+adopted from source, issues, labels or a candidate checkout.
+
+Apply and rollback require the running single controller. The browser uses the
+same endpoints, with labelled role inputs and a diff before explicit Apply.
+A matching revision and an idle controller are required: queued, running,
+cancelling, awaiting-approval work, pending actions, maintenance and unreconciled
+executor fences block application. Stale or invalid requests fail without
+changing installed settings. Reload and preview again after a conflict.
+Configuration adoption never admits work or installs/discovers a schedule.
+
+Authenticated API requests (bearer operator token or local session):
+
+| Request | JSON body / result |
+| --- | --- |
+| `GET /api/v1/definition` | Current `revision`, portable `definition`, `effective`, `inherited_harness`, `capabilities`, `rollback_available` |
+| `POST /api/v1/definition/validate` | `{"definition": {...}}` → validation and effective diff |
+| `POST /api/v1/definition/diff` | `{"definition": {...}}`, or `{"rollback": true}` → current revision, proposed definition, effective changes |
+| `POST /api/v1/definition/apply` | `{"definition": {...}, "expected_revision": "HASH"}` → installed readback |
+| `POST /api/v1/definition/rollback` | `{"expected_revision": "HASH"}` → installed readback |
+
+`GET /api/v1/definitions` remains the safe catalog and includes `role_definition`.
+HTTP 400 means invalid schema/combination; 403 means missing session or rejected
+Host/Origin; 409 means stale/busy/recovery-required or no rollback available.
+Storage errors return 500 with details in private controller logs. CLI errors
+exit nonzero. Neither catalog nor role responses expose private command argv,
+credential values or machine bindings. Unresolved provider defaults remain null;
+execution resolves them from the private installation before launch.
+
+## Private state, policy and evidence
+
+Existing `factory.json` is not rewritten or migrated. With no overrides, the
+legacy effective configuration and policy hash are byte-compatible, including
+private custom commands and legacy `agent` naming. All-inherit adoption is a
+no-op. Shared resources, image, checks, repository identity and credentials stay
+private and are changed while stopped through their existing operator workflow.
+Foundation supplies setup guidance, not another configuration source.
+
+The controller stores the adopted definition and up to ten prior definitions in
+one private `role-definition.json`, using a flushed temporary file and atomic
+rename. Process interruption before rename leaves the old record; after rename,
+the complete new record and history are present. Incomplete temporary files are
+not loaded. The adopted record must be a regular private file; repository symlinks
+are refused. Revisions include a monotonic sequence and the private base settings,
+so an old revision is stale even after rollback. Back up the entire private state
+while stopped; rollback restores roles and adopted local bindings, not separately edited base
+settings, credentials or historical attempts. New reads do not use a startup cache.
+
+Before each attempt, trusted configuration resolves and freezes **all roles** in
+private `execution-config.json`. The executor selects its phase from that frozen
+configuration. One policy hash covers the common configuration across Build,
+deterministic Verify, Review and Handoff; it is not a hash of separately merged
+phase settings. Protected v2 execution evidence records role, requested model,
+provider, explicit effort and a digest binding the exact private command selection.
+The executor checks that binding before launching. Role overrides require v2;
+old v1 evidence cannot attest them. Unchanged legacy configurations still emit
+v1 with the actual installed runtime version. See [compatibility](npm.md#protected-evidence-compatibility).
+
+Changing a role invalidates prior acceptance/checkpoint evidence under that
+policy. Rollback can restore the exact prior policy; it never edits evidence or
+automatically retries work. Recovery, reviewed-candidate continuation and new
+publication use the same current-policy guards. Existing published receipt
+reconciliation retains its read-only semantics. With any role override, task-wide
+`--model`/API `model` is refused, including a value equal to the old shared model.
+Clear it and use the role definition; unchanged legacy installations keep their
+existing task-model behavior.
+
+Only the selected provider's inference settings reach each agent phase. Codex
+account-auth data never reaches Pi, including Pi using OpenAI. Check and Handoff
+receive no inference credentials. Git/issue-provider identity remains on the
+controller. Portable roles create no credentials or model downloads. The opt-in local binding
+contract below explicitly adopts private endpoint details separately.
+
+## Role and output boundaries
+
+Build implements, runs appropriate checks, writes its report and returns. Factory
+owns separate Review; this slice grants no nested reviewer capability or budget.
+Review receives the original source baseline and protected exact-candidate,
+current-policy checks. Its candidate mount is read-only, without installed
+project dependencies; `/tmp` is bounded/noexec. Reuse passing protected checks.
+Additional reproduction requires suitable available capabilities; do not repeat
+impossible installs or treat an unavailable rerun as a code finding or a pass.
+
+Factory owns `/output/agent-report.md`, `/output/review.json` and
+`/output/incident-report.json` as appropriate to the phase. Harness-only final
+output belongs in ephemeral `/tmp/factory-final-message.md`, never those reports.
+The maintained presets do not capture a final-message file over a Factory report.
+Role adoption rejects recognized inherited Codex final-message flags targeting
+non-ephemeral destinations; it never rewrites the private command. Opaque custom
+wrappers remain operator-owned. Redaction covers owned reports/logs, not every
+arbitrary file a custom harness might write. A missing required report remains
+a failure, never a final-message substitution.
+
+All six installed runtime skills remain available read-only, with content/source
+hashes in the catalog. Per-role recommendations are guidance, not access controls.
+Triage/spec are pre-admission method skills, not executable roles. Check remains
+deterministic; acceptance is human-owned. No foreman, scheduler, application
+publishing or production recovery authority is added.
+
+Host, image/toolchain and provider readiness require actual probes on each target
+platform. `doctor` and existing image/browser probes keep their bounded meanings;
+configuration alone is not readiness attestation. Lead qualification of the exact
+package, isolated mixed-role Docker execution and desktop/390/320px browser
+inspection in both themes remain separate gates. #53 stays open for per-role
+skills/resources/access, broader project/flow/automation definitions and readiness
+attestation. #69 owns local/hybrid model benchmarks, #51 measurement and #70
+improvement proposals.
+
+## Opt-in local bindings (0.15.0, #69)
+
+A portable role can select `{"harness":"pi","localBinding":"local-worker"}`
+instead of a hosted `model`. The same reference can serve Implement, Review and
+Investigate, or any role can retain Codex/a hosted Pi model for a hybrid setup.
+Binding references cannot be combined with a role model or reasoning effort.
+They require the maintained Pi preset; private wrappers are not binding adapters.
+
+Connection details belong to explicitly adopted **private installation state**,
+not the portable definition. No repository filename, issue or model response is
+an active configuration source. Save a private JSON binding map, for example:
+
+```json
+{
+  "local-worker": {
+    "endpoint": "http://operator-selected-host:8080/v1",
+    "model": "exact-installed-model-id",
+    "contextWindow": 32768,
+    "maxTokens": 4096,
+    "reasoningEffort": "default",
+    "compat": {
+      "maxTokensField": "max_tokens",
+      "supportsUsageInStreaming": true,
+      "requiresToolResultName": false
+    }
+  }
+}
+```
+
+These illustrative values are not defaults or measured recommendations. Select
+the endpoint, exact model and limits for your installation. `endpoint` is a base
+URL for OpenAI **chat completions**, not a full `/chat/completions` URL. The job's
+isolated network must reach it; its loopback address is not the host's loopback.
+Factory neither opens ports nor adjusts networking or inference services.
+
+```sh
+factory definition diff --state PRIVATE_STATE --file roles.json --bindings-file PRIVATE_BINDINGS.json
+factory definition apply --state PRIVATE_STATE --file roles.json --bindings-file PRIVATE_BINDINGS.json --expected-revision HASH_FROM_DIFF
+factory definition rollback --state PRIVATE_STATE --expected-revision CURRENT_HASH
+```
+
+`validate`, `diff` and `apply` accept `--bindings-file`. Without it they retain the
+installed binding map. Providing a map replaces it in full, so removing a referenced
+binding fails until its roles are changed in the same request. `export` includes
+only portable roles/references. CLI `definition` inspects private bindings locally.
+The authenticated API adds optional `local_bindings` beside `definition` to
+validate/diff/apply; `GET /api/v1/definition` returns both. Diff returns
+`binding_changes`. Unauthenticated `/api/v1/definitions` omits endpoint maps;
+authenticated readback includes them. The existing Agents/Definition editor uses
+this same contract and shows a binding diff before Apply, including connection-only
+changes. Configuration makes no inference/model-list requests and never starts work.
+
+Bindings and roles share one revision, idle check, atomic record and at most ten
+rollback snapshots. Rollback restores both together; stale/busy/invalid writes
+preserve the prior state. Endpoint normalization is idempotent; URLs whose normalized
+form contains forbidden escapes (including Unicode path characters) are rejected.
+The complete serialized record and history are validated before replacement.
+The version-2 private record reads old version-1 role
+records without rewriting them. An old runtime cannot read a newly adopted v2
+record: roll back profiles first and restore a stopped pre-upgrade private-state
+backup before downgrading binaries. Do not hand-edit histories or frozen attempts.
+
+The binding contract supports at most 16 named, keyless HTTP(S) endpoints. URLs
+with user information, queries, fragments, escapes or malformed syntax are refused.
+Model identifiers cannot contain shell syntax, whitespace or traversal. Context
+must be 1,024–1,048,576 tokens; output must be 1–32,000 and smaller than context.
+The output ceiling follows pinned Pi 0.73.1's simple chat adapter. Range acceptance
+is **not** evidence of server allocation or useful task capacity. Only the three
+shown compatibility fields are supported. Authentication, custom headers, shell
+credential commands, arbitrary request fields, sampling overrides, custom thinking
+maps and provider plugins are unsupported. Factory does not spoof local inference
+as the hosted OpenAI provider.
+
+The optional binding `reasoningEffort` accepts only these OpenAI-style requests:
+
+| Binding choice | Chat-completions request |
+| --- | --- |
+| Omitted or `default` | No `reasoning_effort` override; server default applies |
+| `none` | `reasoning_effort: "none"` |
+| `low`, `medium`, `high` | `reasoning_effort` set to that exact value |
+
+This is a request choice, not a measured thinking budget or quality claim. The
+pinned Pi 0.73.1 adapter uses a fixed internal `thinkingLevelMap.off="none"` for
+`none`; `--thinking off` alone does **not** disable a server's default thinking.
+Low/medium/high use the corresponding explicit Pi thinking level. Existing
+bindings with no choice retain their omitted request and private policy shape;
+no default is inserted into their saved configuration. The binding editor,
+CLI/API diff, private readback, frozen selection and rollback share this choice.
+Separate role bindings can request different efforts. Endpoint support and actual
+behavior remain unqualified until tested on that installation. A server rejection
+fails the job without fallback or retrying with a different choice; a server that
+silently ignores the field cannot be detected from successful transport alone.
+
+Before admission, all selected references must resolve. Each attempt freezes the
+chosen endpoint, exact model, declared limits, reasoning request, compatibility settings and maintained
+command along with the common resource/timeout/skill policy. Unselected bindings
+are not included. Local/hybrid attempts emit protected **v3** evidence across all
+phases, binding the selection digest and common policy. Public facts show configured
+context/output, unknown actual allocation and unqualified quality. Old v1/v2 writers
+cannot attest local bindings; unchanged legacy profiles keep their policy bytes and
+compatible evidence. See [the compatibility audit](npm.md#protected-evidence-compatibility).
+
+For the selected local role only, the executor creates a private single-model
+`models.json` and deterministic launcher, mounted read-only at `/factory-local`.
+`PI_CODING_AGENT_DIR` selects that directory; HOME is still ephemeral. The launcher
+checks explicit provider/model argv, removes inherited credential/override inputs
+and propagates Pi JSON provider failures even if Pi exits zero. The registry uses
+Pi's required fixed non-secret key placeholder (`factory-local-keyless`), which may
+be sent as a bearer value; this is not endpoint authentication. No host home, provider
+catalog or credential store is mounted. Repository files cannot replace this mount.
+Files are removed after confirmed container shutdown; uncertain shutdown retains
+them behind the existing recovery fence until normal recovery confirms absence.
+
+Local roles receive no cloud model environment; cloud roles receive no local
+registry/override. Verify and Handoff receive neither. The local preset disables
+automatic skills/extensions/templates but explicitly adds `--skill /factory-skills`,
+preserving the six packaged skills. Recommendations remain guidance, not per-role
+access controls. Build still returns to Factory's independent Review and operator
+handoff; no duplicate review workflow is launched.

package/docs/interfaces.md

@@ -20,7 +20,8 @@ shell endpoint or a second scheduler.
 | Request changes | `revise --file`, optional `--from admitted-source\|reviewed-candidate` or `--source-ref REF` | `request_changes` with `revision_mode`; continuation binds current run/head/tree from shared status | Explicit starting point, baseline and reviewed checkpoint; inline errors | JSON action result; unfinished Build checkpoints remain #42 |
 | Remove a stopped task | No command | `DELETE /api/v1/jobs/:id` | Remove action | Add CLI; keep existing recoverability/history semantics |
 | Evidence list/read/download | No command | Authenticated artifact routes | Files/preview/download | Add CLI with matching access and size/path rules |
-| Roles, workflows and packaged skills | `definition`, `agents`, `skills` JSON (also while stopped) | `GET /api/v1/definitions` | Agents, Skills and Definition | Shared read-only catalog; future editing must preserve common policy/gates |
+| Roles, workflows and packaged skills | `definition`, `agents`, `skills` JSON (also while stopped) | `GET /api/v1/definitions` | Agents, Skills and Definition | Shared catalog plus bounded role harness/model editing; deterministic checks, gates, skills and resources stay shared |
+| Portable roles and private local bindings | `definition export/validate/diff/apply/rollback`, optional `--bindings-file` for validate/diff/apply | Authenticated `/api/v1/definition` and typed operations | Agents/Definition role editor, diff, explicit idle Apply and rollback | One schema/capability matrix; revision CAS and bounded atomic role/binding history; configured context distinct from unknown allocation and unqualified quality; [request shapes](definition.md) |
 | Project repository links | Validated links in `status` | `project_links` from configured Git origin | View repo / optional GitHub issue link | Provider creates/issues reads are separate from Git source links |
 | Recorded token usage | Per-attempt `usage` and `token_usage` in `status` | Same status records | Analytics, task rows, metadata/history | No billing estimate; partial/unknown coverage stays explicit |
 | Analytics/filtering | Raw status available | Source queue records | Derived views | Expose equivalent queries/summaries without inventing usage data |
@@ -35,7 +36,7 @@ shell endpoint or a second scheduler.
 | Synthetic qualification | `demo`, `qualify` | No qualification endpoint | Synthetic disclosure only | Explicit separate state; never target an application accidentally |
 | Immutable source admission | `init --source-ref`, `run --source-ref`, `issue start --source-ref`; status and build evidence carry the resolved SHA | `POST /api/v1/jobs` resolves/retains before acknowledgement; shared source metadata in status | Issue Start work, local request and revision forms accept a ref; task detail shows requested ref, resolved SHA and prior source commits | Build/retry use retained objects; revisions start fresh by default; explicit continuation keeps the reviewed tree and recorded source; a new ref replaces the base; legacy source remains unknown |
 | Trusted PR handoff | `publish JOB_ID` publishes/reconciles; `abandon-delivery JOB_ID --branch-sha SHA` records a checked local resolution for a pre-write branch collision | Authenticated `POST /api/v1/jobs/:id/publish` and `/abandon-delivery`; shared receipt, conflict identity and removal policy | Publish/reconcile and explicit “Abandon local delivery; keep remote branch” actions share controller state; errors/results and inspected branch identity are visible | New writes require matching protected Codex/Pi build/review provenance, deterministic verify/handoff provenance, non-synthetic bound artifacts and a qualified GitHub Actions tree. Shared delivery status exposes `workflow_qualification` and the same reason blocks CLI/API/dashboard capability and publication/retry. Candidate workflow changes, unsupported triggers/syntax, or active generated-push, selected-ref-dispatch and PR jobs with write/secrets/environment/OIDC/deploy access, self-hosted runners or ambiguous privileged guards refuse trusted writes. Supported ASCII guard comparisons follow GitHub's case-insensitive string semantics; unknown PR refs, non-ASCII mismatches, and glob/escaped branch filters cannot prove a privileged job inactive. The shared summary's `action_mode` distinguishes new/resumable publication from read-only reconciliation and drives idle and pending task button wording. Branch-only collisions and unknown/abandoned states offer neither; known PR receipts and pending PR-creation checkpoints retain read-only reconciliation. Abandonment checks the current run, saved intent, exact branch head and absence of an associated PR; it writes no provider data, preserves the remote branch/evidence, disables republishing and permits local removal. Uncertain effects and incompatible evidence stay blocked. Destination remains private operator config; patch-only remains default |
-| Delivered-commit check readback | `publish JOB_ID` reconciles, `status` returns saved checks | Existing publish/status routes return the same `delivery_status.checks` | Delivered-commit checks, per-row conclusions/scope, uncertainty and refresh | 0.13.1 verifies exact commit/provider identity; installed/live/browser qualification pending; no required-check or mergeability claim |
+| Delivered-commit check readback | `publish JOB_ID` reconciles, `status` returns saved checks | Existing publish/status routes return the same `delivery_status.checks` | Delivered-commit checks, per-row conclusions/scope, uncertainty and refresh | 0.13.1 delivered in PR #97 with installed/live/browser qualification recorded; no required-check or mergeability claim |
 | Optional trusted web verification | `web probe` performs a real local Chromium interaction; `doctor` reports readiness | Verify stores a shared story summary and protected JSON artifact in the run | Task history shows passed/failed/unavailable/inconclusive plus tool, candidate, policy and story hashes | Disabled by default. Required operator stories and Playwright/Chromium image ID are frozen in attempt policy. Linux Chromium proof cannot qualify native/mobile OS behavior; see [the browser contract](web-verification.md) |
 
 The current generic task form can name the Defence workflow; that is not a

package/docs/npm.md

@@ -104,8 +104,8 @@ installation or retained attempt needs them.
 
 ## Protected evidence compatibility
 
-Factory 0.13.1 recognizes version-1 execution profiles emitted by native
-**0.8.0, 0.9.0, 0.9.1, 0.10.0, 0.11.0, 0.11.1, 0.11.2, 0.12.0, 0.13.0 and 0.13.1**. This is an exact allowlist in
+Factory 0.15.0 recognizes version-1 execution profiles emitted by native
+**0.8.0, 0.9.0, 0.9.1, 0.10.0, 0.11.0, 0.11.1, 0.11.2, 0.12.0, 0.13.0, 0.13.1, 0.14.0 and 0.15.0**. This is an exact allowlist in
 `factory/execution-profile.mjs`, independent of the installed package version;
 it is not a semver range or an automatic promise for later releases. Unknown
 runtime strings, unknown profile formats and incomplete legacy acceptance
@@ -170,6 +170,17 @@ and publication validation tests; old records remain immutable and unknown
 versions remain blocked. Provider check observations are separate from protected
 Verify evidence and cannot authorize acceptance or publication.
 
+Version 0.14.0 preserves the v1 writer only for unchanged inherited installations:
+policy bytes, candidate/check/review/acceptance bindings, mounts and credential
+rules stay compatible. Adopted role overrides use **v2 from 0.14.0 and 0.15.0**, recording
+role/provider/effort and an exact selection digest. The executor verifies the
+frozen common configuration before phase selection; continuation and both delivery
+validation paths require matching protected v2 evidence and private frozen config.
+V1 cannot attest an override. Mixed roles share one policy across deterministic
+and agent phases. Rollback can restore a prior policy without rewriting a record.
+See the [definition contract](definition.md); installed Docker/provider qualification
+remains separate from schema compatibility.
+
 Old installed releases retain their own files and mount paths until an idle,
 reviewed update. No installed catalog, execution profile or historical hash is
 rewritten by this layout change. Qualify the exact updated package/image before
@@ -216,3 +227,17 @@ delivery under [#61](https://github.com/arcitai/software-and-defence-factory/iss
 
 References: [npm/npx](https://docs.npmjs.com/cli/v11/commands/npx/),
 [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+
+The 0.15.0 compatibility audit preserves unchanged v1/v2 policy construction,
+protected checks, candidate reconstruction, read-only review and acceptance guards.
+Historical 0.14.0 v2 validation compares its actual writer version rather than
+relabeling it as the installed version. Local registry selection is a new execution
+contract: every phase of a local/hybrid attempt requires **v3 from 0.15.0** and its
+exact protected frozen configuration. v1/v2 cannot attest local binding fields,
+providers or a common policy containing a selected local role. A selected endpoint,
+model, limit or compatibility change invalidates the current policy; explicit
+rollback can restore it without editing historical evidence. Controlled regressions
+exercise legacy v2 readback and local v3 rejection/tamper cases. Installed-package
+Docker and independent Review remain delivery qualification, not inferred from this
+compatibility audit.

package/docs/recovery.md

@@ -13,7 +13,7 @@ Use `status --state PATH` and the private supervisor.log to identify the active
 
 Do not remove active.json merely to unblock a job. Establish that its PID, process group and labelled containers are stopped. PID reuse or missing process identity requires operator investigation. Preserve logs and work before cleanup.
 
-For backup, stop the installation and copy the complete private state directory, including SQLite files, factory.json and credentials, to an authorized private destination. Restore only while stopped. Update the repository path if it moved, verify ownership/permissions and the pinned image, then inspect state before any retry. Keep previous backups; no automatic destructive schema migration is provided.
+For backup, stop the installation and copy the complete private state directory, including SQLite files, factory.json, role-definition.json when present, and credentials, to an authorized private destination. Restore only while stopped. Update the repository path if it moved, verify ownership/permissions and the pinned image, then inspect state before any retry. Keep previous backups; no automatic destructive schema migration is provided.
 
 Earlier experimental engines use a different journal. Start a new state directory for the native 0.3 runtime; preserve old journals separately. There is no automatic import of their jobs or approval state.
 
@@ -136,6 +136,16 @@ Unknown formats/versions remain blocked. Published PR receipt reconciliation
 stays read-only, and compatibility does not relax the original-base/remote-target
 guard or add checkpoint continuation.
 
+In 0.14.0, role overrides use v2 protected evidence and one frozen common policy.
+Use [definition rollback](definition.md) through an idle controller to restore the
+previous portable selection. It preserves all attempts and changes the definition
+revision; it does not change separate private settings or credentials. Changed
+roles invalidate checkpoint/new-publication evidence until the exact prior policy
+is restored or a fresh complete cycle succeeds. Task-wide model overrides are
+refused when role overrides are active; an old task with such a model needs a
+replacement admission without it. Incomplete definition temporary files are ignored
+on restart; never splice historical execution evidence into a new profile.
+
 Attempts made before this metadata existed display **Not recorded
 (legacy/unknown)**. Do not copy today's profile onto them. For an investigation,
 compare the retained per-attempt measurement, logs, candidate/check/review hashes

package/docs/setup.md

@@ -183,6 +183,18 @@ An installation already using Codex account auth may set the validated
 Codex agent phases receive it. Pi and checks do not. See the [quickstart
 inference guidance](quickstart.md#connect-an-application) for constraints.
 
+For separate Implement/Review/Investigate harnesses or models, export and review
+[the portable role definition](definition.md), then explicitly apply its preview
+through the idle controller. No overrides preserves the current private command
+and legacy evidence. Do not put credential values, host paths, resources or
+arbitrary command arguments in that file. Shared settings remain in private
+`factory.json`; inference stays in `model.env`. Adoption starts no work or schedule.
+Keep harness final-message capture in ephemeral `/tmp`, separate from durable
+Factory reports. Review reuses protected exact-candidate checks; its read-only
+workspace and noexec temporary space cannot repeat every dependency install or
+executable fixture. Qualify each selected role with the actual image, provider
+and platform; declared configuration and a discovered binary are not model proof.
+
 Checkpoint: record the exact source revision, image ID, check command, resource
 limits, inference connectivity and CI result. Keep product controllers stopped
 until their tasks are explicitly ready to run.
@@ -377,3 +389,44 @@ To add operator scope at admission, use `issue start --url URL --workflow softwa
 --brief-file operator.md --state PATH` with an optional UTF-8 brief of at most
 16000 characters. This keeps the remote identity and current-content check;
 local requests still use `issue start --file` or `--draft` without `--brief-file`.
+
+
+## Optional keyless local or hybrid inference
+
+Use the [local binding recipe](definition.md#opt-in-local-bindings-0150-69) to adopt
+an explicit private endpoint/model map and portable Pi role references. Keep the
+working default and a stopped private-state backup; preview, apply while idle and
+use revision-guarded rollback. A local Implement role can be paired with an existing
+cloud Review role. No downloads, service restarts, port changes or jobs occur during
+configuration. Authenticated endpoints, sampling overrides and custom thinking
+maps are unsupported. Local bindings may request OpenAI-style `reasoningEffort`:
+`default` (or omitted), `none`, `low`, `medium` or `high`. Default omits the request;
+it does not disable server thinking. Qualify the endpoint's actual semantics before
+using a request as a thinking-budget control. Unsupported requests fail without
+fallback when the endpoint rejects them; transport success alone cannot prove a
+server honored the request. Existing omitted choices remain unchanged.
+
+Qualify the actual installed image and endpoint from an isolated job before using
+it for application work. Record server/harness versions, exact model ID and digest,
+quantization, GPU/backend and actual offload, available and peak memory, endpoint
+reachability, tool-call/result compatibility and report/check/review outcomes.
+Keep host inference access separate from controller/forge credentials. Unknown
+values stay unknown; registry discovery only proves client capability.
+
+Reconcile the client's configured context with the server's actual allocation and
+per-request/model overrides. Do not infer a 65k allocation from a remembered agent
+setting or a server default. A bounded 64k/128k allocation experiment, where
+supported, must record KV-cache and Flash Attention settings, memory and allocation
+success separately from long-context task quality. This worker supplies no such
+measurements or driver/kernel advice. Do not recommend larger windows from the
+schema's upper limit.
+
+The operator still owns #69's matched two-fixture comparison: pinned bases,
+comparable prompts/contexts/trials, a measured existing local baseline and one
+selected alternative, decisive independent checks and separate Review contexts.
+Retain failures, repairs and human time. Record wall time, observable prefill/decode,
+input/cached/output tokens, memory/offload and all reviewer usage. Factory currently
+leaves Pi usage unknown; controlled protocol fixtures are not token or quality
+benchmarks. Include cloud Review in hybrid totals. No provider token billing for
+local inference does not mean zero electricity, hardware or operator cost. Only
+then qualify a suitable real Factory issue; no customer jobs are part of this slice.

package/docs/workflows.md

@@ -5,7 +5,7 @@ installation with `factory definition --state PATH`, or its
 Agents, Skills and Definition pages. Both read the same effective catalog.
 
 Software follows **Implement → Check → Review → Accept & hand off**. Implement
-and Review are separate agent invocations using the installation's harness/model.
+and Review are separate agent invocations using their resolved role profiles.
 Check runs the project's command. Accept requires operator approval and confirms
 that the candidate and policy still match their evidence. It does not push,
 merge, deploy or publish. Revisions start a new build/check/review and preserve
@@ -139,11 +139,12 @@ handling, resource limits and stop behavior. No schedule is created by onboardin
 
 ## Change the definition
 
-Select the harness, model, check and resource limits in the private `factory.json`
-while the installation is stopped, then restart. Workflow order and packaged
-skills change through reviewed Factory releases. This release does not support
-per-role profiles or arbitrary editable workflow graphs. Versioned editable
-definitions are tracked in [#53](https://github.com/arcitai/software-and-defence-factory/issues/53).
+Version 0.14.0 supports portable harness/model selections for Implement, Review
+and Investigate. Use the shared [role definition workflow](definition.md) to
+export, validate, preview, apply while idle and roll back. Missing overrides
+inherit the exact private installation profile. Shared checks/resources remain
+in private `factory.json`; workflow order and packaged skills follow reviewed
+Factory releases. Broader definition editing stays under #53.
 
 
 Inbox groups URL case, HTTP/HTTPS, trailing-slash, query and fragment aliases by GitHub