software-defence-factory 0.7.0 → 0.9.0

package/docs/setup.md

@@ -155,11 +155,87 @@ model servers, public listeners, Docker socket mounts or whole account folders.
 Cloud inference likewise needs a real provider/model connectivity check without
 printing credentials. A model-list/health response is connectivity evidence;
 qualifying model output requires a separately accepted bounded task.
+Store only supported inference settings in `model.env`; jobs reject unrelated
+names such as deployment credentials. Codex receives its OpenAI setting group,
+and Pi receives only its operator-selected provider group. Use
+`--inference-provider` with `init` when Pi's provider is not encoded in the
+operator-configured model name or when multiple provider groups are stored.
+An installation already using Codex account auth may set the validated
+`FACTORY_CODEX_AUTH_JSON` single-line JSON value in private `model.env`; only
+Codex agent phases receive it. Pi and checks do not. See the [quickstart
+inference guidance](quickstart.md#connect-an-application) for constraints.
 
 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.
 
+Optional web verification is configured separately from the selected harness
+and model. The execution-host owner prepares and pins the Playwright/Chromium
+image, writes trusted stories in private `factory.json`, then runs `web probe`
+and `doctor` on that installation. Use [the browser setup and story contract](web-verification.md)
+for the recipe, dependency preparation and limits. Verify uses separate isolated
+Linux preview and browser containers and cannot qualify native/mobile operating
+systems.
+
+### Optional trusted PR delivery
+
+Patch-only handoff is the default. When the operator intends to enable GitHub
+delivery for this installation, configure the exact canonical repository and
+target while initializing it, for example:
+
+```sh
+software-defence-factory init --repo /absolute/path/to/app --harness pi \
+  --check "npm ci && npm test" --source-ref main \
+  --delivery-provider github \
+  --delivery-repository https://github.com/OWNER/REPO \
+  --delivery-target main --state /private/state/my-app
+```
+
+The admitted source ref and PR target are independent. Only `main` and `dev`
+are supported target choices in this release. The destination must match the
+canonical origin retained at admission. A changed/renamed origin, moved target
+base or changed Factory policy blocks delivery until fresh applicable evidence
+exists. Configure this before admitting work. Unknown providers remain
+patch-only.
+
+Before enabling trusted PR delivery, confirm the repository workflows fit the
+bounded qualification in [recovery](recovery.md#trusted-pr-delivery). Factory
+compares the immutable admitted base and accepted candidate trees, refuses any
+candidate change to a GitHub Actions workflow, and requires jobs that can run
+for generated-branch pushes, PR events or selected-ref manual dispatches to use
+explicit `contents: read` or `none`, a known GitHub-hosted runner, and no
+secrets, protected environments, OIDC or deploy permissions. Unsupported
+workflow syntax keeps the patch-only path available. Organization hooks and
+other external CI automation remain operator-owned and are not audited by this
+check.
+
+The operator's authenticated `gh` identity stays on the controller. Keep GitHub
+credentials out of `model.env`, project files and worker containers. Do not add
+deploy credentials or a Docker socket for PR delivery. Use only the existing
+authorized repository and the repository access already approved for the
+operator; do not create a new fixture repository or request broader access.
+
+The release lead owns the live provider/browser qualification after installing
+the published candidate separately. Use a separate private state against the
+already authorized Factory repository and `main`; ordinary issue admission,
+checks, independent review and approval must produce the disposable candidate.
+Give its issue a title beginning **[Factory PR handoff proof]**, then use the
+normal **Publish accepted candidate as draft PR** action. Record the job,
+candidate SHA/tree, generated unique branch, exact draft PR, base/head/tree and
+triggered check states. The CLI allows up to ten minutes for this multi-request
+controller action; other CLI API requests retain their five-second deadline.
+If the client deadline expires, inspect status and repeat `publish JOB_ID` so
+the controller can reconcile its saved intent. Restart the installed controller
+and repeat `publish JOB_ID`; verify the same branch and PR head are read back
+and no second PR appears. Delete issue is disabled while the delivery is
+unresolved, and the controller rejects the same removal through its API. Leave
+pending/unknown checks labelled as such. After inspection, close the proof PR
+without merging its fixture change. Do not publish a worker candidate from
+inside its sandbox.
+
+Mocks exercise controller and receipt behavior only. They are not live GitHub
+publication or browser proof; record each separately in [qualification](proof.md).
+
 ## 5. Enable only the intended background services
 
 A newly initialized state has no jobs. Before adopting older state, establish
@@ -242,6 +318,8 @@ Copy this private completion record into the installation's handoff:
 | History and intentionally stopped products preserved | Pending | |
 | Backups, logs, stop/update/rollback owner and guide | Pending | |
 | First bounded application task | Not started | Separate task authority and proof |
+| Optional trusted PR provider and target explicitly configured, or patch-only retained | Pending | |
+| Release lead live disposable Factory draft PR/readback/restart/close proof | Not started | Separate from mocked provider tests |
 
 Use Pass, Fail or Not applicable with a reason; never infer success from an
 installed file. Keep host identities, credentials, raw logs and customer details

package/docs/web-verification.md

@@ -0,0 +1,167 @@
+# Optional trusted web verification
+
+Browser verification is an operator-controlled extension of the existing
+Verify phase. It is disabled when `webVerification` is absent. Issue text,
+candidate files and generated tests cannot enable it or change its required
+stories. The selected harness and model remain independent of this capability.
+
+## Prepare and qualify Playwright/Chromium
+
+The first adapter uses the Playwright 1.63.0 package and Chromium version from
+the matching Microsoft Playwright image. Build it explicitly on the execution
+host from the installed Factory package (or a trusted Factory source checkout):
+
+```sh
+docker build --pull -f factory/web/Dockerfile \
+  -t software-defence-factory-playwright:1.63.0 factory/web
+docker image inspect --format '{{.Id}}' software-defence-factory-playwright:1.63.0
+```
+
+Copy the resulting `sha256:…` image ID into private `factory.json`. The
+Dockerfile uses the versioned `mcr.microsoft.com/playwright:v1.63.0-noble`
+base and `npm ci` with the committed lockfile. Factory resolves no tag, pulls
+no image, installs no package and falls back to no other browser during a job.
+Rebuild and deliberately select a new image ID when upgrading the base or
+Playwright version.
+
+For a global npm installation, resolve the packaged recipe directory first:
+
+```sh
+factory_package="$(npm root -g)/software-defence-factory"
+docker build --pull -f "$factory_package/factory/web/Dockerfile" \
+  -t software-defence-factory-playwright:1.63.0 "$factory_package/factory/web"
+browser_image="$(docker image inspect --format '{{.Id}}' software-defence-factory-playwright:1.63.0)"
+```
+
+Run the readiness check from the selected installation:
+
+```sh
+software-defence-factory web probe --state /private/state/project
+software-defence-factory doctor --state /private/state/project
+```
+
+The probe runs a real headless Chromium click and result assertion in a bounded,
+read-only, `network none` Docker container as the controller UID. Its real
+wall-clock deadline stops the exact labelled probe, and readiness is reported
+only after that container is confirmed removed. A missing image, unsupported
+adapter/version or browser launch failure reports unavailable. The probe never
+downloads or builds an image.
+
+## Configure trusted stories
+
+Stop the installation before editing its private `factory.json`. Add an
+operator-authored value like this and adapt names, routes, actions and result
+text to the application:
+
+```json
+{
+  "webVerification": {
+    "enabled": true,
+    "adapter": "playwright",
+    "version": "1.63.0",
+    "image": "sha256:REPLACE_WITH_LOCAL_IMAGE_ID",
+    "previewCommand": ["npm", "run", "preview", "--", "--host", "127.0.0.1", "--port", "4173"],
+    "port": 4173,
+    "timeoutSeconds": 90,
+    "themes": ["light", "dark"],
+    "stories": []
+  }
+}
+```
+
+`stories` is a small declarative contract; the empty array in this sketch is a
+placeholder and is rejected until the complete trusted story set is supplied.
+Every selected theme requires an interactive `desktop-<theme>` and
+`narrow-<theme>` story. All installations
+also require these named stories, using the first configured theme at desktop
+size:
+
+- `busy-disabled`: click an action, observe its disabled state, wait for it to
+  become enabled, and check the result text.
+- `result`: exercise an action and assert its result text.
+- `failure-retry`: assert a `role: "alert"` failure, click Retry, then assert a
+  `role: "status"` result.
+- `keyboard-focus`: press a supported key and assert the expected control has
+  focus.
+
+Each story names `viewport` (`desktop` or `narrow`), `theme` (`light` or
+`dark`), a local `path` beginning with `/`, and ordered `steps`. Supported
+steps are `click`, `expect-visible`, `expect-enabled`, `expect-disabled`,
+`expect-text`, `press` and `expect-focused`. Actions and assertions use exact
+accessible roles and names. Arbitrary selectors, JavaScript, source tests and
+candidate-supplied story files are not accepted. `factory/web/qualification-fixture.mjs`
+shows the complete eight-story contract used by the disposable installed
+qualification.
+
+`execution.json` freezes and hashes this complete operator configuration with
+the attempt policy. The check evidence records the candidate head/tree, Verify
+attempt, policy hash, immutable browser image ID, adapter/tool/browser versions,
+story-set hash and each story's content hash. Any changed tree, tool, story or
+policy makes prior evidence stale. Missing, failed, unavailable, inconclusive
+or malformed required evidence blocks Review, handoff and trusted PR delivery.
+The run summary and `web-verification.json` artifact are shared through CLI,
+API and dashboard; the dashboard renders traces as text and retained PNGs as
+images. It does not execute candidate HTML in the controller origin.
+
+## Package and preview guidance
+
+Use the configured project check for dependency preparation and build output.
+For Node projects, install from the committed lockfile with the project's
+frozen install command (for example `npm ci --ignore-scripts`), run the build,
+then configure `previewCommand` to start the already-prepared local preview
+from the project root in the disposable check copy.
+The preview phase reuses that check's disposable scratch copy. It does not run
+another install or contact a package registry. The qualified project job image
+provides the preview runtime. Do not add secrets to the preview environment or
+image.
+
+Verify starts two containers with separate mount and PID namespaces. The
+preview uses the configured project job image, the candidate at `/workspace`
+read-only, and the writable `/scratch` copy. It runs as the controller UID with
+`network none`, dropped capabilities, a read-only root and bounded resources.
+The browser uses the pinned Playwright image as the same UID, with its own
+read-only root, writable temporary profile and a separate private output mount.
+It receives the frozen trusted stories on stdin and does not mount the
+candidate, project scratch or controller results. The browser shares only the
+exact preview container's `network none` namespace to reach its loopback port;
+each container retains its own PID namespace. Neither container gets host
+networking, published ports, extra capabilities, a Docker socket, controller,
+forge or inference credentials, or a user profile.
+
+The controller enforces a real wall-clock deadline, stops and reconciles both
+exact labelled containers, then reads the bounded result and PNG screenshots
+from the browser-only mount. The private result contains candidate/tree,
+attempt, policy, pinned tool/image and story hashes, bounded action traces and
+screenshot hashes. CLI, API and dashboard expose the same evidence; screenshots
+can be viewed as images, and no candidate HTML is served on the controller
+origin. Chromium is headless and uses the outer Docker boundary; this is not a
+hosted browser service.
+
+This adapter proves only Linux Chromium interaction with a local web preview.
+It does not qualify Android/iOS, desktop-native applications, Safari, Firefox,
+mobile operating systems, production access or an application's overall
+correctness. Deterministic checks and independent Review remain separate.
+
+## Installed synthetic fixture qualification
+
+The release lead owns this Docker/browser qualification on the installed
+execution host. Use a separate demo state, complete and inspect the demo's
+normal sample handoff, stop that controller, then run the exact qualification
+command with the already-built browser image ID:
+
+```sh
+software-defence-factory demo --state /private/state/sdf-web-proof --port 7348
+# Review and approve the synthetic demo task in its dashboard.
+software-defence-factory stop --state /private/state/sdf-web-proof
+browser_image="$(docker image inspect --format '{{.Id}}' software-defence-factory-playwright:1.63.0)"
+software-defence-factory qualify-web --state /private/state/sdf-web-proof --image "$browser_image"
+```
+
+The installed command probes actual Chromium interaction, then runs a
+disposable delayed-save/failure-retry fixture through mock Build/Review and
+real Docker Verify. Its deliberate variant removes the busy disabled state and
+changes the result text; Verify must fail and no acceptance record may appear.
+The command records a private `qualification.json` under the demo state's
+private qualification directory. It never targets an application or calls a
+model/provider. Do not report this as passed until the lead observes the
+installed invocation and its result.

package/factory/definition.mjs

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ROOT, digest, harnessOf } from './lib.mjs';
+import { expectedWebStories, webPolicyHash } from './web-verification.mjs';
 
 // Execution order is shared with the queue; presentation cannot invent phases.
 export const WORKFLOWS = Object.freeze({
@@ -9,7 +10,7 @@ export const WORKFLOWS = Object.freeze({
 });
 const phaseInfo = {
   build: { title: 'Implement', owner: 'agent', skills: ['factory-implement'], description: 'Implement the accepted scope in an isolated checkout. Produce a candidate and evidence.' },
-  verify: { title: 'Check', owner: 'factory', skills: [], description: 'Run the project check command against the candidate. A failure stops delivery.' },
+  verify: { title: 'Check', owner: 'factory', skills: [], description: 'Run project checks and any optional trusted browser stories against the candidate. Missing or non-passing required proof stops delivery.' },
   review: { title: 'Review', owner: 'agent', skills: ['factory-review', 'factory-security'], description: 'Review the candidate and evidence in a separate agent invocation. Security review applies when required by the accepted scope.' },
   handoff: { title: 'Accept & hand off', owner: 'operator', skills: [], description: 'Wait for operator approval, then confirm the candidate and policy still match the checks and review. Record acceptance; do not push, merge or deploy.' },
   defence: { title: 'Investigate', owner: 'agent', skills: ['factory-security'], description: 'Investigate supplied incident evidence within the accepted scope. Produce a private draft with findings and unknowns. No production access or recovery action is granted.' },
@@ -40,7 +41,13 @@ export function factoryDefinition(config) {
     skills,
     configuration: { harness, agent: harness, // agent is a v1 compatibility alias
       model: config.model || null, check: config.check, timeoutSeconds: config.timeoutSeconds,
-      memoryMiB: config.memoryMiB, cpus: config.cpus || 2 },
+      memoryMiB: config.memoryMiB, cpus: config.cpus || 2,
+      web_verification: config.webVerification?.enabled ? {
+        enabled: true, adapter: config.webVerification.adapter, version: config.webVerification.version,
+        browser: 'chromium', image: config.webVerification.image, policy_hash: webPolicyHash(config.webVerification),
+        required_stories: expectedWebStories(config.webVerification), platform: 'linux-container', coverage: 'web',
+      } : { enabled: false },
+    },
     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.',

package/factory/delivery-provider.mjs

@@ -0,0 +1,20 @@
+import { githubDeliveryProvider } from './providers/github-delivery.mjs';
+
+// Provider selection is a trusted installation setting. Unknown providers do
+// not get guessed URLs, credentials or a write path; they remain patch-only.
+export function deliveryProvider(config, integrations = {}) {
+  const provider = config.delivery?.provider;
+  if (provider !== 'github') return { id: provider || null, supported: false };
+  return integrations.deliveryProvider || githubDeliveryProvider();
+}
+
+export function deliveryProviderInfo(config, provider) {
+  const enabled = provider?.supported === true && config.delivery?.provider === provider.id;
+  return {
+    enabled,
+    mode: enabled ? 'trusted_pr' : 'patch_only',
+    provider: config.delivery?.provider || null,
+    repository: enabled ? config.delivery.repository : null,
+    target: enabled ? config.delivery.target : null,
+  };
+}