software-defence-factory 0.13.1 → 0.14.0

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,28 @@ 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;
+      if (['validate', 'diff', 'apply'].includes(action)) {
+        if (!flags.file) throw new Error('--file is required');
+        value = JSON.parse(readFileSync(resolve(flags.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' && !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);
+      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 } : {}) });
+      }
+      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 +343,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
+  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,188 @@
+# Role definitions (0.14.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` and
+`reasoningEffort`; 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 `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 Pi requires a supported
+  `provider/model` prefix so credential selection is unambiguous. For inherited Pi,
+  a model must agree with any installed private `inferenceProvider`.
+- 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 portable roles only, 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 0.14.0 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. No new credentials, endpoint binding, model download or provider is
+created by a definition.
+
+## 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.

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 role definitions | `definition export/validate/diff/apply/rollback` | 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 history; [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.14.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 and 0.14.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 only**, 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

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.

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

package/factory/definition-store.mjs

@@ -0,0 +1,72 @@
+import { closeSync, existsSync, fsyncSync, openSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { configAt, digest, harnessOf } from './lib.mjs';
+import { DefinitionError, installedRoleRecord, parseRoleDefinition, publicRoleProfiles, resolveRoleProfiles, ROLE_CAPABILITIES } from './role-definition.mjs';
+
+function context(state) {
+  const config = configAt(state), record = installedRoleRecord(state);
+  delete config.roleDefinition;
+  return { config, record, revision: digest(JSON.stringify({ config, sequence: record.sequence, definition: record.definition })) };
+}
+function view({ config, record, revision }) {
+  return { revision, inherited_harness: harnessOf(config), definition: record.definition, rollback_available: record.history.length > 0,
+    effective: publicRoleProfiles(resolveRoleProfiles(config, record.definition)), capabilities: ROLE_CAPABILITIES };
+}
+export function inspectDefinition(state) { return view(context(state)); }
+export function previewDefinition(state, value) {
+  const current = context(state), definition = parseRoleDefinition(value);
+  const before = view(current);
+  const effective = publicRoleProfiles(resolveRoleProfiles(current.config, definition));
+  const changes = [];
+  for (const role of ROLE_CAPABILITIES.roles) {
+    if (JSON.stringify(before.definition.roles[role]) !== JSON.stringify(definition.roles[role])
+      || JSON.stringify(before.effective[role]) !== JSON.stringify(effective[role]))
+      changes.push({ role, before: before.effective[role], after: effective[role], selection: definition.roles[role] });
+  }
+  return { revision: current.revision, definition, effective, changes, valid: true,
+    qualification: 'Configuration only; harness, model availability and quality are not qualified' };
+}
+export function previewRollback(state) {
+  const previous = context(state).record.history.at(-1);
+  if (!previous) throw new DefinitionError('No previous definition is available', 409);
+  return { ...previewDefinition(state, previous), rollback: true };
+}
+function assertIdle(queue, state) {
+  if (queue.closing || queue.maintenance || queue.active || queue.actions.size || queue.issueActions.size
+    || queue.all().some(job => !['succeeded', 'failed', 'cancelled', 'blocked', 'interrupted'].includes(job.state)))
+    throw new DefinitionError('Controller is busy; finish or cancel active and awaiting-approval work before applying a definition', 409);
+  const jobs = join(state, 'jobs');
+  if (existsSync(jobs) && readdirSync(jobs).some(id => /^job_[a-z0-9]+$/.test(id) && existsSync(join(jobs, id, 'active.json'))))
+    throw new DefinitionError('Executor recovery is required before applying a definition', 409);
+}
+function persist(state, record) {
+  const destination = join(state, 'role-definition.json'), temp = `${destination}.${randomUUID()}.tmp`;
+  let fd;
+  try {
+    fd = openSync(temp, 'wx', 0o600);
+    writeFileSync(fd, JSON.stringify(record, null, 2) + '\n'); fsyncSync(fd); closeSync(fd); fd = undefined;
+    // Definition and rollback history share one atomic replacement. A crash before
+    // rename retains the old record; after rename it retains the complete new one.
+    renameSync(temp, destination);
+  } finally { if (fd !== undefined) closeSync(fd); rmSync(temp, { force: true }); }
+}
+// Called synchronously only by the single controller, after request body parsing.
+// No await between CAS, idle check and atomic replacement; admission cannot interleave.
+export function changeDefinition(state, queue, input, rollback = false) {
+  const allowed = rollback ? ['expected_revision'] : ['expected_revision', 'definition'];
+  if (!input || Object.keys(input).some(key => !allowed.includes(key)) || typeof input.expected_revision !== 'string')
+    throw new DefinitionError('Expected definition and expected_revision (rollback accepts expected_revision only)');
+  const current = context(state);
+  if (input.expected_revision !== current.revision) throw new DefinitionError('Definition revision changed; refresh and preview again', 409);
+  assertIdle(queue, state);
+  const value = rollback ? current.record.history.at(-1) : input.definition;
+  if (!value) throw new DefinitionError('No previous definition is available', 409);
+  const preview = previewDefinition(state, value);
+  if (!rollback && JSON.stringify(preview.definition) === JSON.stringify(current.record.definition)) return view(current);
+  const history = rollback ? current.record.history.slice(0, -1) : [...current.record.history, current.record.definition].slice(-10);
+  const record = { version: 1, sequence: current.record.sequence + 1, definition: preview.definition, history };
+  persist(state, record);
+  return { revision: digest(JSON.stringify({ config: current.config, sequence: record.sequence, definition: record.definition })),
+    inherited_harness: harnessOf(current.config), definition: record.definition, effective: preview.effective, rollback_available: history.length > 0, capabilities: ROLE_CAPABILITIES };
+}

package/factory/definition.mjs

@@ -1,3 +1,4 @@
+import { resolveRoleProfiles, publicRoleProfiles } from './role-definition.mjs';
 import { readinessMapping } from './issue-lifecycle.mjs';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -23,6 +24,7 @@ const skillRoles = {
 };
 export function factoryDefinition(config) {
   const harness = harnessOf(config);
+  const profiles = publicRoleProfiles(resolveRoleProfiles(config));
   const skills = Object.entries(skillRoles).map(([role, purpose]) => {
     const id = `factory-${role}`, path = `kit/skills/${id}/SKILL.md`;
     const content = readFileSync(join(ROOT, path), 'utf8');
@@ -33,12 +35,12 @@ export function factoryDefinition(config) {
     version: 1, workflows, terminology: JSON.parse(readFileSync(join(ROOT, 'factory/terminology.json'), 'utf8')),
     agents: Object.entries(phaseInfo).filter(([, info]) => info.owner === 'agent').map(([phase, info]) => ({
       id: phase === 'build' ? 'implement' : phase === 'defence' ? 'investigate' : phase,
-      phase, title: info.title, responsibility: info.description, harness, model: config.model || null, skills: info.skills,
+      phase, title: info.title, responsibility: info.description, ...profiles[phase === 'build' ? 'implement' : phase === 'defence' ? 'investigate' : phase], skills: info.skills,
     })),
     operator_skills: [foundationSkill()],
     automations: { owner: 'harness', harness, managed_by_factory: false, discovery: 'unavailable', items: null },
     commands: Object.entries(phaseInfo).map(([name, info]) => ({ name, ...info, prompt: info.description,
-      executor: info.owner === 'agent' ? harnessOf(config) : 'factory', timeout: `${config.timeoutSeconds}s` })),
+      executor: info.owner === 'agent' ? profiles[name === 'build' ? 'implement' : name === 'defence' ? 'investigate' : name].harness : 'factory', timeout: `${config.timeoutSeconds}s` })),
     skills,
     configuration: { issueReadinessLabels: readinessMapping(config.issueReadinessLabels), harness, agent: harness, // agent is a v1 compatibility alias
       model: config.model || null, check: config.check, timeoutSeconds: config.timeoutSeconds,
@@ -52,7 +54,7 @@ export function factoryDefinition(config) {
     method: {
       preparation: ['factory-triage', 'factory-spec'], evaluation: ['factory-evaluate'],
       instructions: 'All six skills are available read-only to agent phases. A skill is an instruction set, not a separate agent or an automatic workflow step.',
-      customization: 'Choose the harness, model, project check and resource limits in the installation’s private factory.json while stopped, then restart. Task scope belongs in the issue or work instructions. Phase order, gates and packaged skills change through a reviewed Factory release; they are not editable prompt templates.',
+      customization: 'Use definition export/validate/diff/apply/rollback for role harness and model selections. Shared checks and resources remain in private factory.json, edited while stopped. Task scope belongs in the issue or work instructions. Phase order, gates and packaged skills change through a reviewed Factory release; they are not editable prompt templates.',
     },
   };
 }

package/factory/execution-evidence.mjs

@@ -1,8 +1,9 @@
+import { installedRoleRecord, hasRoleOverrides } from './role-definition.mjs';
 import { lstatSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { configAt, digest } from './lib.mjs';
-import { effectiveExecutionConfig, isSupportedExecutionProfile } from './execution-profile.mjs';
+import { effectiveExecutionConfig, isSupportedExecutionProfile, assertFrozenExecution } from './execution-profile.mjs';
 import { assertCurrentWebArtifacts, assertCurrentWebEvidence } from './web-verification.mjs';
 
 export function assertCurrentHandoffEvidence(meta, checks, review, policyHash, config = {}, job) {
@@ -35,6 +36,12 @@ export function trustedExecutionProfile(state, job, run, phase, expectedPolicy)
     for (const path of [join(state, 'jobs'), folder, join(folder, 'artifacts'), join(folder, 'artifacts', run.id)])
       assertPrivateDirectory(path);
     const profile = readPrivateJson(join(folder, 'artifacts', run.id, 'execution.json'));
+    if (profile.version === 1 && hasRoleOverrides(installedRoleRecord(state).definition)) return false;
+    if (profile.version === 2) {
+      const frozen = readPrivateJson(join(folder, run.id, 'execution-config.json'));
+      if (!frozen.roleDefinition || !frozen.resolvedRoleProfiles || digest(JSON.stringify(frozen)) !== expectedPolicy) return false;
+      assertFrozenExecution(frozen, profile, phase);
+    }
     const agentPhase = phase === 'build' || phase === 'review';
     const executorMatches = agentPhase
       ? ['codex', 'pi'].includes(profile.executor)