software-defence-factory 0.4.3 → 0.4.4

package/.github/ISSUE_TEMPLATE/factory-task.yml

@@ -1,6 +1,7 @@
 name: Factory task
 description: Describe a business outcome and observable acceptance criteria.
 title: "[Factory] "
+labels: ["factory:triage"]
 body:
   - type: textarea
     id: need
@@ -20,7 +21,9 @@ body:
     id: scope
     attributes:
       label: Scope, constraints and recovery
-      description: Affected repository, relevant files, allowed changes and rollback.
+      description: Affected repository, allowed changes, non-goals, dependencies and rollback. Link blocking issues.
+    validations:
+      required: true
   - type: dropdown
     id: track
     attributes:
@@ -32,4 +35,4 @@ body:
     id: capabilities
     attributes:
       label: Required capabilities
-      description: For example browser, computer use, tests, web research or security review. Never paste credentials.
+      description: For example browser, tests, platform tools or security review. Name any external operator proof needed. Never paste credentials or sensitive findings into a public issue.

package/bin/software-defence-factory.mjs

@@ -5,6 +5,7 @@ import { randomBytes } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { createServer } from 'node:net';
 import { ROOT, PINS, DEFAULT_STATE, configAt, save, json, run, stream, digest, api, sleep, stopContainers } from '../factory/lib.mjs';
+import { assertInstalledJobImage, installCustomJobImage, installStandardJobImage, inspectImageInstallation } from '../factory/image-install.mjs';
 import { admitIncident } from '../factory/incident.mjs';
 import { DEFAULT_DEMO_STATE } from '../factory/paths.mjs';
 import { bootstrap, registerInstallation, VERSION } from '../factory/updates.mjs';
@@ -47,27 +48,16 @@ function init(repo, agent='codex', check='', port=7331) {
   console.log(`Configured ${state}\nApp files were not changed. Only committed code is cloned into jobs.`);
 }
 
-function retainImage(reference) {
-  let image;
-  try { image=run('docker',['image','inspect','--format','{{.Id}}',reference]); }
-  catch(error) { if(/No such image|No such object/.test(error.message))return null;throw error; }
-  if(!/^sha256:[a-f0-9]{64}$/.test(image))throw new Error('Docker returned an unexpected image identity');
-  // Containerd can drop an untagged manifest when the shared build tag moves.
-  // Keep the exact object reachable; existing installations retain their pins.
-  run('docker',['tag',image,`software-defence-factory-retained:${image.slice(7)}`]);
-  return image;
-}
 async function install() {
   const config=configAt(state);
-  if(existsSync(join(state,'supervisor.json'))&&alive(json(join(state,'supervisor.json')).pid))throw new Error('Stop the factory before installing or updating its runtime');
   if (!['darwin','linux'].includes(process.platform)||!['arm64','x64'].includes(process.arch)) throw new Error('Use macOS/Linux arm64/amd64, or WSL2');
-  run('docker',['info','--format','{{.ServerVersion}}']);
-  retainImage(config.image);retainImage(PINS.jobImage);
-  await stream('docker',['build','-t',PINS.jobImage,join(ROOT,'factory/image')]);
-  config.image=retainImage(PINS.jobImage);
-  if(!config.image)throw new Error('Built job image is unavailable');
-  save(join(state,'factory.json'),config);save(join(state,'engine.json'),{runtime:'native-node',version:VERSION,image:config.image});
-  console.log('Installed. Job image is pinned to its local image ID. No model call made.');
+  if(flags.image) {
+    const selected=installCustomJobImage(state,flags.image,{version:VERSION});
+    console.log(`Installed custom job image ${selected.image} from local reference ${selected.reference}. No image was downloaded or built; no model call made.`);
+    return;
+  }
+  const installed=await installStandardJobImage(state,{version:VERSION});
+  console.log(`Installed standard job image ${installed.image}. No model call made.`);
 }
 async function portFree(port) {
   await new Promise((ok,fail)=>{const server=createServer();server.once('error',fail);server.listen(port,'127.0.0.1',()=>server.close(ok));});
@@ -76,9 +66,9 @@ async function up() {
   const config=configAt(state),lock=join(state,'supervisor.json');
   registerInstallation(state);
   if(existsSync(lock)) { if(alive(json(lock).pid))throw new Error('Supervisor already running; use status');rmSync(lock); }
-  if(!existsSync(join(state,'engine.json')))throw new Error('Run install first');
+  assertInstalledJobImage(state,config);
   if(process.getuid()===0)throw new Error('Run the controller as a dedicated unprivileged user with Docker access');
-  run('docker',['image','inspect',config.image]);await portFree(config.port);
+  await portFree(config.port);
   const fd=openSync(join(state,'supervisor.log'),'a',0o600);
   const child=spawn(process.execPath,[join(ROOT,'factory/supervisor.mjs'),state],{detached:true,stdio:['ignore',fd,fd]});
   closeSync(fd);child.unref();
@@ -139,8 +129,7 @@ try {
     const launch=async()=>{
     if(process.getuid()===0)throw new Error('Use a dedicated unprivileged operator account');
     const lock=join(state,'supervisor.json');if(existsSync(lock)){if(alive(json(lock).pid))throw new Error('Supervisor already running');rmSync(lock);}
-    if(!existsSync(join(state,'engine.json')))throw new Error('Run install first');
-    run('docker',['image','inspect',configAt(state).image]);
+    assertInstalledJobImage(state,configAt(state));
     registerInstallation(state);await portFree(configAt(state).port);
     const { supervise } = await import('../factory/supervisor.mjs');await supervise(state);
     };
@@ -153,7 +142,9 @@ try {
   else if(command==='tunnel')await manageService('tunnel',positional[0],state,flags);
   else if(command==='status') { const snapshot=await api(state,'/api/v1/status');delete snapshot.csrf_token;console.log(JSON.stringify(snapshot,null,2)); }
   else if(command==='doctor') {
-    const config=configAt(state);console.log(JSON.stringify({node:process.version,docker:run('docker',['info','--format','{{.ServerVersion}}']),engineInstalled:existsSync(join(state,'engine.json')),repo:config.repo,agent:config.agent,checksConfigured:!!config.check?.trim(),inference:'Not called or verified',dashboard:`http://127.0.0.1:${config.port}`},null,2));
+    const config=configAt(state),dockerVersion=run('docker',['info','--format','{{.ServerVersion}}']),imageStatus=inspectImageInstallation(state,config);
+    console.log(JSON.stringify({node:process.version,docker:dockerVersion,engineInstalled:imageStatus.installed,image:imageStatus.image,repo:config.repo,agent:config.agent,checksConfigured:!!config.check?.trim(),inference:'Not called or verified',qualification:{model:'not assessed',toolchain:'not assessed'},dashboard:`http://127.0.0.1:${config.port}`},null,2));
+    if(!imageStatus.installed)process.exitCode=1;
   } else if(command==='run') {
     let spec;
     if(flags.issue) {
@@ -195,7 +186,7 @@ try {
   demo                                    Install and run a synthetic sample (no model key)
   qualify --state PATH                    Exercise recovery and isolation with a stopped demo job
   init --repo PATH --agent codex|pi|custom --check "npm ci && npm test"
-  install                                 Build the isolated job image; the controller ships with the CLI
+  install [--image LOCAL_REF]             Build the standard image, or select an existing local image
   doctor | up | status | stop              Inspect / operate your private installation
   serve                                   Foreground supervisor
   service [print]                         Print a systemd user-service definition

package/docs/quickstart.md

@@ -61,8 +61,23 @@ Use `status`, `cancel JOB_ID`, `retry JOB_ID` and `stop`, always with the select
 
 ## Native application builds
 
-Pin an application-specific image with the required toolchains. In `factory.json`,
-`cpus` (1–32, default 2), `pidsLimit` (64–16384, default 256), `memoryMiB` and
+Build a compatible application image on the worker, then select its existing
+local tag through the CLI:
+
+```sh
+software-defence-factory install --image LOCAL_IMAGE_REF --state /private/state/my-app
+software-defence-factory doctor --state /private/state/my-app
+```
+
+Selection resolves and retains the immutable image ID. It does not pull or build
+the reference. An unavailable image, a running controller, an unreconciled job
+or a remaining job container makes selection fail without changing the last
+working configuration. Plain `install` remains the standard-image build path
+and selects the standard image again. `doctor` verifies that the recorded image
+metadata matches the image selected in private state; it reports model and
+toolchain qualification separately, and does not perform either qualification.
+
+In `factory.json`, `cpus` (1–32, default 2), `pidsLimit` (64–16384, default 256), `memoryMiB` and
 `timeoutSeconds` bound the job's resources. Verification uses a separate
 disk-backed checkout, keeping the candidate read-only. Its private scratch
 directory is removed after container termination is confirmed. Interrupted

package/docs/recovery.md

@@ -90,3 +90,12 @@ and any contemporaneous private configuration backup. Record only corroborated
 facts in a separate private incident note with evidence paths and unknowns; leave
 the original queue/evidence unchanged. Without that evidence, model/image facts
 cannot be reconstructed reliably.
+
+### Interrupted image selection or controller startup
+
+`installation.lock` serializes image changes with controller startup, including
+managed boot/restarts. A live supervisor then prevents image changes while work
+can run. If an operation is interrupted, preserve the lock and inspect its PID
+and action. Remove it only after confirming that process and its image build or
+startup have stopped, then run `doctor` and reconcile image metadata before
+starting again. The CLI does not automatically clear an unknown lock.

package/docs/setup.md

@@ -104,6 +104,9 @@ anything. Verify the canonical GitHub origin and main branch's tracking target;
 a fork may still track its upstream product. Move application sources into the
 chosen workspace, not into the npm package or private runtime state.
 
+Use [repository readiness](../kit/repository.md) for issue forms, labels, CI
+policy and the explicit issue-to-job handoff. A ready label does not start a job.
+
 Before admitting development work, establish:
 
 - Reproducible toolchain/dependency pins and an actual build/check command.
@@ -123,11 +126,20 @@ software-defence-factory install --state /private/state/my-app
 software-defence-factory doctor --state /private/state/my-app
 ```
 
-Replace the agent/check/paths with the accepted application profile. `install`
-builds the standard image: do not use it to overwrite an existing custom image
-selection. Follow the application image's own build/pinning procedure instead.
-`init` does not edit the app, install personal skills or submit a task. Runtime
-jobs receive the bundled method and six skills automatically.
+Replace the agent/check/paths with the accepted application profile. Plain
+`install` builds the standard image. To use an application-specific image, build
+it on the worker first and select its existing local tag instead:
+
+```sh
+software-defence-factory install --image LOCAL_IMAGE_REF --state /private/state/my-app
+```
+
+This command checks the local Docker daemon, records and retains the exact image
+ID, and does not download or build the selected image. Stop the installation and
+reconcile every job before changing its image. Running plain `install` later
+still rebuilds and selects the standard image. `init` does not edit the app,
+install personal skills or submit a task. Runtime jobs receive the bundled
+method and six skills automatically.
 
 For a local model, verify the existing model service, intended model name and
 its startup. Test the model API from a disposable container using the **selected

package/factory/image-install.mjs

@@ -0,0 +1,189 @@
+import {
+  existsSync, readFileSync, readdirSync, writeFileSync, renameSync, rmSync,
+} from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { configAt, instanceLabel, json, PINS, ROOT, run, stream } from './lib.mjs';
+import { acquireInstallationLock } from './installation-lock.mjs';
+import { VERSION } from './updates.mjs';
+
+const imageIdPattern = /^sha256:[a-f0-9]{64}$/;
+const imageReferencePattern = /^[a-zA-Z0-9][a-zA-Z0-9_./:@-]*$/;
+const missingImage = error => /no such (image|object)/i.test(error.message);
+const alive = pid => {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { if (error.code === 'ESRCH') return false; throw error; }
+};
+
+function docker(args, runner = run) { return runner('docker', args); }
+
+export function inspectLocalImage(reference, runner = run) {
+  if (typeof reference !== 'string' || !imageReferencePattern.test(reference))
+    throw new Error('Invalid Docker image reference');
+  let id;
+  try { id = docker(['image', 'inspect', '--format', '{{.Id}}', reference], runner); }
+  catch (error) {
+    if (missingImage(error)) return null;
+    throw error;
+  }
+  if (!imageIdPattern.test(id)) throw new Error('Docker returned an unexpected image identity');
+  return id;
+}
+
+export function retainImage(image, runner = run) {
+  if (!imageIdPattern.test(image || '')) throw new Error('Expected an immutable Docker image ID');
+  // The shared build tag can move. Keep every selected image reachable by ID.
+  docker(['image', 'tag', image, `software-defence-factory-retained:${image.slice(7)}`], runner);
+  return image;
+}
+
+function retainIfPresent(reference, runner) {
+  const image = inspectLocalImage(reference, runner);
+  if (image) retainImage(image, runner);
+  return image;
+}
+
+export function assertImageChangeSafe(state, { runner = run, isAlive = alive } = {}) {
+  const supervisor = join(state, 'supervisor.json');
+  if (existsSync(supervisor)) {
+    let record;
+    try { record = json(supervisor); }
+    catch { throw new Error('Supervisor state is unreadable; reconcile the installation before changing its image'); }
+    if (!Number.isSafeInteger(record.pid) || record.pid < 1)
+      throw new Error('Supervisor state is unverified; reconcile the installation before changing its image');
+    if (isAlive(record.pid)) throw new Error('Stop the Factory before changing its job image');
+  }
+
+  const jobs = join(state, 'jobs');
+  if (existsSync(jobs)) {
+    for (const job of readdirSync(jobs)) {
+      if (existsSync(join(jobs, job, 'active.json')))
+        throw new Error(`Job ${job} has active or unreconciled execution; reconcile it before changing the image`);
+    }
+  }
+
+  const containers = docker(['ps', '-aq', '--filter', `label=sdf.factory=${instanceLabel(state)}`], runner)
+    .split('\n').filter(Boolean);
+  if (containers.length) throw new Error('Factory job containers remain; stop and reconcile them before changing the image');
+}
+
+function persistInstallation(state, config, metadata, filesystem = undefined) {
+  const fs = filesystem || { readFileSync, writeFileSync, renameSync, rmSync };
+  const configPath = join(state, 'factory.json'), enginePath = join(state, 'engine.json');
+  const previousConfig = fs.readFileSync(configPath);
+  const token = `${process.pid}.${randomBytes(8).toString('hex')}`;
+  const configTemp = `${configPath}.${token}.next`, engineTemp = `${enginePath}.${token}.next`;
+  let configReplaced = false;
+  try {
+    fs.writeFileSync(configTemp, `${JSON.stringify(config, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    fs.writeFileSync(engineTemp, `${JSON.stringify(metadata, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    fs.renameSync(configTemp, configPath);
+    configReplaced = true;
+    fs.renameSync(engineTemp, enginePath);
+  } catch (error) {
+    if (configReplaced) {
+      const rollback = `${configPath}.${token}.rollback`;
+      try {
+        fs.writeFileSync(rollback, previousConfig, { flag: 'wx', mode: 0o600 });
+        fs.renameSync(rollback, configPath);
+      } catch (rollbackError) {
+        throw new Error(`Image installation metadata could not be completed (${error.message}); restoring factory.json also failed (${rollbackError.message})`);
+      } finally { fs.rmSync(rollback, { force: true }); }
+    }
+    throw error;
+  } finally {
+    fs.rmSync(configTemp, { force: true });
+    fs.rmSync(engineTemp, { force: true });
+  }
+}
+
+function metadataFor(image, source, reference, version) {
+  return {
+    runtime: 'native-node',
+    version,
+    image,
+    imageSource: source,
+    imageReference: reference,
+  };
+}
+
+export function installCustomJobImage(state, reference, { runner = run, version = VERSION, isAlive = alive, filesystem } = {}) {
+  const release = acquireInstallationLock(state, 'select image');
+  try {
+    const config = configAt(state);
+    assertImageChangeSafe(state, { runner, isAlive });
+    const image = inspectLocalImage(reference, runner);
+    if (!image) throw new Error(`Docker image ${reference} is not present locally; build or pull it explicitly before selecting it`);
+    retainImage(image, runner);
+    const nextConfig = { ...config, image };
+    const metadata = metadataFor(image, 'custom', reference, version);
+    persistInstallation(state, nextConfig, metadata, filesystem);
+    return { image, reference, config: nextConfig, metadata };
+  } finally { release(); }
+}
+
+export async function installStandardJobImage(state, { runner = run, build = stream, version = VERSION, isAlive = alive, filesystem } = {}) {
+  const release = acquireInstallationLock(state, 'build image');
+  try {
+    const config = configAt(state);
+    assertImageChangeSafe(state, { runner, isAlive });
+    docker(['info', '--format', '{{.ServerVersion}}'], runner);
+    retainIfPresent(config.image, runner);
+    retainIfPresent(PINS.jobImage, runner);
+    await build('docker', ['build', '-t', PINS.jobImage, join(ROOT, 'factory/image')]);
+    const image = inspectLocalImage(PINS.jobImage, runner);
+    if (!image) throw new Error('Built job image is unavailable');
+    retainImage(image, runner);
+    const nextConfig = { ...config, image };
+    const metadata = metadataFor(image, 'standard', PINS.jobImage, version);
+    persistInstallation(state, nextConfig, metadata, filesystem);
+    return { image, config: nextConfig, metadata };
+  } finally { release(); }
+}
+
+function readMetadata(state) {
+  const path = join(state, 'engine.json');
+  if (!existsSync(path)) return null;
+  try { return json(path); } catch { return null; }
+}
+
+export function inspectImageInstallation(state, config = configAt(state), runner = run) {
+  const metadata = readMetadata(state);
+  let image = null;
+  image = inspectLocalImage(config.image, runner);
+
+  const metadataValid = Boolean(metadata
+    && metadata.runtime === 'native-node'
+    && typeof metadata.version === 'string'
+    && imageIdPattern.test(metadata.image || '')
+    && (!metadata.imageSource || ['standard', 'custom'].includes(metadata.imageSource))
+    && (!metadata.imageReference || imageReferencePattern.test(metadata.imageReference)));
+  const imageAvailable = image !== null;
+  const markerMatches = metadataValid && imageAvailable && metadata.image === image;
+  const installed = Boolean(markerMatches);
+  return {
+    installed,
+    image: {
+      reference: config.image,
+      id: image,
+      available: imageAvailable,
+      pinned: imageAvailable && config.image === image,
+      markerImage: metadataValid ? metadata.image : null,
+      source: metadataValid ? (metadata.imageSource || 'legacy') : null,
+      referenceAtInstall: metadataValid ? (metadata.imageReference || null) : null,
+      metadataValid,
+      markerMatches: Boolean(markerMatches),
+      error: imageAvailable ? null : `Selected image ${config.image} is not present locally`,
+    },
+  };
+}
+
+export function assertInstalledJobImage(state, config = configAt(state), runner = run) {
+  const status = inspectImageInstallation(state, config, runner);
+  if (!status.installed) {
+    if (!status.image.available) throw new Error(`Selected job image ${config.image} is not present locally; run install with an available image`);
+    if (!status.image.metadataValid) throw new Error('Runtime image metadata is missing or invalid; run install');
+    throw new Error('Selected job image does not match the installed image metadata; run install');
+  }
+  return status;
+}

package/factory/installation-lock.mjs

@@ -0,0 +1,15 @@
+import { writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Per installation: managed boot bypasses the CLI's global service-operation
+// lock. Hold this fence until image metadata is complete or the supervisor PID
+// is visible, before any queued work can snapshot an execution profile.
+export function acquireInstallationLock(state, action) {
+  const path = join(state, 'installation.lock');
+  try { writeFileSync(path, JSON.stringify({ pid: process.pid, action }), { flag: 'wx', mode: 0o600 }); }
+  catch (error) {
+    if (error.code === 'EEXIST') throw new Error(`Another installation operation may own ${path}; reconcile its PID before removing the lock`);
+    throw error;
+  }
+  return () => rmSync(path);
+}

package/factory/services.mjs

@@ -5,6 +5,7 @@ import { spawnSync } from 'node:child_process';
 import { createServer } from 'node:net';
 import { ROOT, STATE_HOME, DATA_HOME, SOURCE_CHECKOUT } from './paths.mjs';
 import { configAt, json, save, run, api, sleep, digest } from './lib.mjs';
+import { assertInstalledJobImage } from './image-install.mjs';
 import { VERSION, newer, latestVersion, installRelease, busyInstallations } from './updates.mjs';
 import { serviceId, systemdUnit, launchAgent, tunnelArguments, groupArguments, runtimeLauncher } from './service-files.mjs';
 
@@ -127,9 +128,8 @@ async function install(kind, state, flags) {
     console.log(JSON.stringify(await serviceStatus(previous), null, 2)); return;
   }
   if (kind === 'controller') {
-    if (!existsSync(join(state, 'engine.json'))) throw new Error('Run install for this state before installing its service');
+    assertInstalledJobImage(state, configAt(state));
     if (existsSync(join(state, 'supervisor.json')) && alive(json(join(state, 'supervisor.json')).pid)) throw new Error('Stop the manually started controller before adopting it as a service');
-    run('docker', ['image', 'inspect', configAt(state).image]);
   }
   let argv = kind === 'controller' ? [process.execPath, launcher(), 'serve', '--state', state] : tunnelArguments(flags.host, port);
   if (flags.group) {

package/factory/supervisor.mjs

@@ -2,10 +2,18 @@ import { writeFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { configAt, stopContainers } from './lib.mjs';
+import { acquireInstallationLock } from './installation-lock.mjs';
+import { assertInstalledJobImage } from './image-install.mjs';
 import { createController } from './server.mjs';
 export async function supervise(state) {
-const config = configAt(state), lock = join(state, 'supervisor.json');
-writeFileSync(lock, JSON.stringify({ pid: process.pid }), { flag: 'wx', mode: 0o600 });
+const lock = join(state, 'supervisor.json');
+const release = acquireInstallationLock(state, 'start controller');
+let config;
+try {
+  config = configAt(state);
+  assertInstalledJobImage(state, config);
+  writeFileSync(lock, JSON.stringify({ pid: process.pid }), { flag: 'wx', mode: 0o600 });
+} finally { release(); }
 let controller, stopping = false;
 async function shutdown(code = 0) {
   if (stopping) return; stopping = true;

package/kit/README.md

@@ -18,6 +18,10 @@ The six skills cover triage, specification, implementation, review, security and
 
 ## First real task
 
+Follow [repository readiness](repository.md) to adopt issue forms and labels,
+verify CI/protection and explicitly admit a scoped task. Exporting this kit does
+not install GitHub labels, poll issues or start agents.
+
 Choose a small existing defect or improvement. Describe the intended user behavior, allowed scope and observable acceptance check. Implement a working vertical slice, exercise the app's relevant checks and obtain a separate review of the delivered revision. A demo or copied skill files alone do not qualify an application.
 
 A PR requires the configured GitHub authority. Otherwise hand back the branch/diff and evidence with an honest status. Unknown cost/time remain unknown. Automated starts require separate qualification of triggers, deduplication, stop/restart and actual resource limits; a skill does not create a scheduler.

package/kit/repository.md

@@ -0,0 +1,86 @@
+# Prepare a repository for Factory work
+
+The method works with an existing agent and CI. The optional runtime adds a
+queue, isolated execution and dashboard. GitHub preparation provides a shared
+work queue; it does not turn labels into an execution trigger.
+
+## Establish a reproducible baseline
+
+Record the canonical Git origin, target branch, committed source revision,
+toolchain, check command and existing owner instructions. Preserve WIP separately.
+Verify the real checks in the intended job image and CI. Inspect the actual
+branch protection/ruleset: required checks, current-base behavior, PR policy and
+merge authority. If an account plan prevents enforcement, record the limitation;
+do not silently change billing or repository visibility.
+
+## Adopt the issue form and labels
+
+The exported kit includes `.github/ISSUE_TEMPLATE/factory-task.yml` and
+`.factory-kit/labels.json`. Review the form and merge it with existing repository
+templates on a branch. The source repository keeps these label definitions in
+`config/labels.json`. Install labels before enabling the form's default label.
+
+For an authorized GitHub repository, `gh label create` creates one label; use
+`gh label edit` only after comparing an existing label with the proposed meaning.
+Do not delete or overwrite an adopter's unrelated labels. For example:
+
+```sh
+gh label list --repo OWNER/REPO
+gh label create 'factory:triage' --repo OWNER/REPO --color D9E2D3 --description 'Needs bounded scope and capability routing'
+# Repeat for the selected definitions in labels.json, then read them back.
+gh label list --repo OWNER/REPO
+```
+
+| Label | Meaning |
+| --- | --- |
+| `factory:triage` | An idea or report needing bounded scope |
+| `factory:spec` | Outcome, constraints or acceptance still need definition |
+| `factory:ready` | Accepted scope is ready for explicit admission |
+| `factory:review` | A candidate/evidence set needs operator review |
+| `factory:blocked` | A concrete dependency or recovery prevents progress |
+| `track:software` | Software delivery |
+| `track:security` | Appropriately scoped security work; sensitive evidence stays private |
+
+Use at most one Factory stage label at a time; track labels are separate.
+GitHub's closed state records completed or declined issues. Runtime job state is
+more precise than these planning labels and remains authoritative for execution.
+Update labels deliberately; the current runtime does not synchronize them.
+
+## Admit one ready issue
+
+A ready task identifies the desired behavior, allowed scope, non-goals,
+dependencies, meaningful acceptance, required capabilities and delivery target.
+Split a large roadmap into independently reviewable changes. Assign external
+browser/platform proof explicitly when the selected worker image lacks it.
+Never treat a label, issue author or text as permission to obtain credentials,
+change policy, deploy or merge.
+
+For the runtime, inspect the selected installation and queue before starting it;
+existing queued jobs may execute on startup. Hold a dedicated committed source
+at the intended SHA until the current runtime has cloned it, and compare the
+candidate's recorded base before acceptance. Admission-time source snapshots are
+tracked separately in Factory #28; naming a SHA in task text does not pin it.
+
+Submit the selected issue with `software-defence-factory run --issue URL --state
+PATH`, or submit a reviewed task file using `run --file`. Issue submission uses
+the operator's `gh` authentication and checks the issue against the configured
+origin. The dashboard's task form submits text to the same runtime; it does not
+currently browse or import a live GitHub backlog. Keep external link/issue/job
+mapping in the trusted handoff record. No automatic GitHub polling is enabled.
+
+## Review and deliver
+
+The implementation, configured checks and independent review must cover the
+same candidate and acceptance policy. The operator completes external proof and
+approves the specific reviewed result. Retain failed attempts and use explicit
+revision feedback when a candidate needs changes.
+
+The current runtime returns a patch after acceptance. The authorized operator
+applies it at its recorded base on a unique branch, verifies the resulting tree,
+and opens a normal PR subject to current checks/protection. GitHub credentials
+stay outside jobs. Accepted is not pushed, merged or deployed. Optional trusted
+PR publication is Factory #29, not an installed feature of this guide.
+
+Link issue, job, base, candidate, checks, review, external proof and PR. Keep
+private paths, credentials and raw incident/model logs outside public records.
+One successful scoped task qualifies that path, not arbitrary unattended work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "software-defence-factory",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "Scoped software delivery and defence investigations with isolated jobs, evidence and review",
   "type": "module",
   "license": "MIT",

package/scripts/export-kit.mjs

@@ -17,7 +17,7 @@ if (args.length === 1 && args[0] === "--help") {
   const destination = resolve(args[0]);
   try {
     const sources = new Map();
-    for (const name of ["README.md", "policy.md", "installation.md", "delivery.md", "examples/github-checks.yml.example"])
+    for (const name of ["README.md", "policy.md", "installation.md", "delivery.md", "repository.md", "examples/github-checks.yml.example"])
       sources.set(`.factory-kit/${name}`, `kit/${name}`);
     for (const role of ["triage", "spec", "implement", "review", "security", "evaluate"]) {
       const path = `.agents/skills/factory-${role}/SKILL.md`;