software-defence-factory 0.4.6 → 0.4.7

package/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,32 @@
+name: Bug report
+description: Report an observable failure in the CLI, dashboard or runtime.
+title: "[Bug] "
+labels: ["bug", "factory:triage"]
+body:
+  - type: markdown
+    attributes:
+      value: Do not include credentials, private incident evidence or security exploit details. Use the security reporting link for vulnerabilities.
+  - type: textarea
+    id: problem
+    attributes:
+      label: What happened, and what should happen?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Include a minimal example and sanitized error output.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Factory version, OS, agent and whether this affects the CLI or dashboard. Do not paste factory.json or model.env.
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: How can we verify the fix?

package/.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,24 @@
+name: Feature request
+description: Propose a concrete improvement to Software & Defence Factory.
+title: "[Feature] "
+labels: ["enhancement", "factory:triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Who needs what to improve?
+      description: Describe the problem and when it occurs.
+    validations:
+      required: true
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Desired behavior and acceptance criteria
+      description: Include what should be possible through both CLI and dashboard, when relevant.
+    validations:
+      required: true
+  - type: textarea
+    id: boundaries
+    attributes:
+      label: Boundaries and alternatives
+      description: What should remain outside this change?

package/README.md

@@ -42,7 +42,7 @@ flowchart LR
 
 Each result belongs to a specific candidate commit and policy. A failed check blocks delivery. Changing the candidate or check policy invalidates earlier evidence. Approval records a handoff; publishing, merging and deployment follow the application's separate authority.
 
-The per-project dashboard keeps Software and Defence in one searchable task list, with workflow/model/status filters, a board, task details, files and history. Analytics separates workflows and shows recorded duration and token usage with explicit coverage; missing billing amounts stay unknown. View repo and New issue use the configured GitHub origin. Workers and workflow descriptions remain accessible. It binds to localhost and can be reached remotely through SSH. One controller executes one job phase at a time; each job has its own checkout and bounded Docker containers.
+The per-project dashboard keeps Software and Defence in one searchable task list, with workflow/model/status filters, a board, task details, files and history. Analytics separates workflows and shows recorded duration and token usage with explicit coverage; missing billing amounts stay unknown. View repo and New issue use the configured GitHub origin. Start work opens a modal to import/review an issue or write a scoped brief; it never automatically starts work from a new issue. See [workflows and skills](docs/workflows.md). Workers show detected host identity and capacity. Workflows show the actual phases, six packaged skills and selected configuration, shared with the `workflows` CLI command. It binds to localhost and can be reached remotely through SSH. One controller executes one job phase at a time; each job has its own checkout and bounded Docker containers.
 
 The optional **defence** workflow accepts scoped incident evidence and produces a private, read-only draft. It does not monitor production or claim verified recovery. See [defence integration](docs/defence-integration.md).
 

package/THIRD_PARTY_NOTICES.md

@@ -546,3 +546,31 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+## GitHub mark (Octicons)
+
+`dashboard/src/github-icon.jsx` uses the mark-github-16 path from
+[primer/octicons](https://github.com/primer/octicons/blob/main/icons/mark-github-16.svg).
+The mark identifies the configured GitHub repository; it is not Factory branding.
+
+MIT License
+
+Copyright (c) 2026 GitHub Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/software-defence-factory.mjs

@@ -6,6 +6,8 @@ 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 { readIssue } from '../factory/issue-intake.mjs';
+import { workflowDefinitions } from '../factory/workflows.mjs';
 import { admitIncident } from '../factory/incident.mjs';
 import { DEFAULT_DEMO_STATE } from '../factory/paths.mjs';
 import { bootstrap, registerInstallation, VERSION } from '../factory/updates.mjs';
@@ -140,6 +142,7 @@ try {
     else await manageService('controller',positional[0],state,flags);
   }
   else if(command==='tunnel')await manageService('tunnel',positional[0],state,flags);
+  else if(command==='workflows')console.log(JSON.stringify(workflowDefinitions(configAt(state)),null,2));
   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),dockerVersion=run('docker',['info','--format','{{.ServerVersion}}']),imageStatus=inspectImageInstallation(state,config);
@@ -148,12 +151,7 @@ try {
   } else if(command==='run') {
     let spec;
     if(flags.issue) {
-      if(!/^https:\/\/github\.com\/[^/]+\/[^/]+\/issues\/\d+$/.test(flags.issue))throw new Error('Expected a GitHub issue URL');
-      const origin=run('git',['-C',configAt(state).repo,'remote','get-url','origin']);
-      const match=origin.match(/^(?:https:\/\/github\.com\/|git@github\.com:)([^/]+\/[^/]+?)(?:\.git)?$/);
-      if(!match||!flags.issue.toLowerCase().startsWith(`https://github.com/${match[1].toLowerCase()}/issues/`))throw new Error('Issue does not belong to the configured app origin; use a scoped task file for other input');
-      const issue=JSON.parse(run('gh',['issue','view',flags.issue,'--json','title,body,url']));
-      spec=`Issue: ${issue.url}\n${issue.title}\n\n${issue.body}`;
+      spec=(await readIssue(configAt(state).repo,flags.issue)).spec;
     } else if(flags.file)spec=readFileSync(resolve(flags.file),'utf8');
     else throw new Error('Use --file task.md or --issue https://github.com/owner/repo/issues/123');
     if(!configAt(state).check?.trim())throw new Error('Configure an app check before submitting software work');
@@ -188,6 +186,7 @@ try {
   init --repo PATH --agent codex|pi|custom --check "npm ci && npm test"
   install [--image LOCAL_REF]             Build the standard image, or select an existing local image
   doctor | up | status | stop              Inspect / operate your private installation
+  workflows                               Inspect actual workflow phases, skills and configuration
   serve                                   Foreground supervisor
   service [print]                         Print a systemd user-service definition
   service install|start|stop|restart       Manage a Linux user service (--state PATH)

package/docs/workflows.md

@@ -0,0 +1,70 @@
+# Workflows, skills and work intake
+
+An **issue** defines the problem, boundaries and acceptance criteria. A
+**workflow** defines the runtime's ordered phases and gates. A **task** is one
+execution of that workflow; retries and revisions preserve its prior attempts.
+A **skill** gives an agent instructions for doing part of the work. Six skills
+do not mean six agents, and a skill does not schedule a job.
+
+The queue, dashboard catalog and `software-defence-factory workflows --state PATH`
+use the same installed definition. The CLI command works while the installation
+is stopped; the dashboard reflects its controller's configuration at startup.
+
+## Prepare, execute, evaluate
+
+Triage and specification use `factory-triage` and `factory-spec` before admission.
+They are method activities, not hidden automatically executed phases.
+
+Software execution proceeds through Build → Check → Review → operator approval
+→ Handoff. Build and review use the configured agent (Codex, Pi or a custom
+executor), with `factory-implement`, `factory-review` and, when scoped,
+`factory-security`. Checks run the application's configured command. Handoff
+confirms the accepted candidate and evidence; it does not publish or deploy.
+
+Defence executes a scoped investigation and produces a private draft. It is not
+a production recovery agent. Validated incident intake still uses
+`incident --file incident.json`; the dashboard's investigation brief is not an
+equivalent typed incident adapter.
+
+`factory-evaluate` supports a separately scoped comparison. All six packaged
+skills are mounted read-only for agent phases and visible in the dashboard's
+Skills tab, including their exact installed instructions and file hashes.
+Availability does not prove an agent followed every instruction.
+
+## Start work
+
+**New issue** opens the configured GitHub repository's issue chooser. It creates
+backlog only. **Start work** opens a modal for explicit execution:
+
+- From GitHub issue: load a URL from this project's origin, review the imported
+  title/body and acceptance criteria, then start. GitHub CLI access is required
+  on the controller host. Imports are bounded and cannot select another repo.
+- Write instructions: supply the accepted scope directly. The project and model
+  default to the installation; optional title/reference/model settings are
+  secondary. A reference link does not fetch instructions.
+
+The CLI uses the same issue reader for `run --issue URL`. It deliberately submits
+when invoked; the dashboard lets the operator inspect/edit the imported scope
+before submitting. Issue text is untrusted input, not authority to change policy.
+No issue, label or import alone starts work. Automatic polling/triggers require a
+separate opt-in admission policy and are not implemented by these forms.
+
+## Customize deliberately
+
+Stop the installation before editing its private `factory.json`. Select the
+agent, model, command, check and resource limits according to the setup guide,
+then restart. Never put credentials in task text; model credentials belong in
+private `model.env`. The Configuration tab exposes selected non-secret settings,
+not raw environment or command arguments.
+
+This release does not provide an editable workflow engine. Phase order,
+approval gates and bundled skills change through a reviewed Factory release.
+Editing an exported kit does not change the runtime's mounted skills. A future
+editor must change the same CLI/API contract and acceptance policy, not merely
+editable text in the dashboard. See issue #37.
+
+Worker identity uses the host OS APIs for hostname, OS, architecture, CPU count
+and memory. Hardware model is best-effort when the OS exposes it (Linux DMI),
+with hostname as the fallback. It does not infer a particular machine from the
+project path or expose serials, network addresses or credentials. Host resources
+are distinct from each job's container limits.

package/factory/issue-intake.mjs

@@ -0,0 +1,28 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readProjectLinks } from './project-links.mjs';
+const exec = promisify(execFile);
+
+export function validateIssueURL(repoURL, value) {
+  if (typeof value !== 'string' || value.length > 2048 || !/^https:\/\/github\.com\/[A-Za-z0-9-]+\/[A-Za-z0-9_.-]+\/issues\/[1-9][0-9]*$/.test(value)) throw new Error('Enter a GitHub issue URL without query parameters.');
+  if (!repoURL || !value.toLowerCase().startsWith(`${repoURL.toLowerCase()}/issues/`)) throw new Error('Issue does not belong to this project’s configured GitHub origin.');
+  return value;
+}
+export async function readIssue(repo, url, read = async url => {
+  try {
+    const { stdout } = await exec('gh', ['issue', 'view', url, '--json', 'title,body,url'], {
+      encoding: 'utf8', timeout: 10000, maxBuffer: 300000,
+      env: { ...process.env, GH_PROMPT_DISABLED: '1', GH_PAGER: 'cat' },
+    });
+    return JSON.parse(stdout);
+  } catch { throw new Error('Could not read the issue. Check the URL and GitHub CLI access on the controller host.'); }
+}) {
+  const repoURL = readProjectLinks(repo)?.repository;
+  validateIssueURL(repoURL, url);
+  const issue = await read(url);
+  validateIssueURL(repoURL, issue?.url);
+  if (issue.url.toLowerCase() !== url.toLowerCase() || typeof issue.title !== 'string' || !issue.title.trim() || typeof issue.body !== 'string') throw new Error('GitHub returned an unexpected issue.');
+  const spec = `Issue: ${issue.url}\n${issue.title}\n\n${issue.body}`;
+  if (Buffer.byteLength(spec) > 240000) throw new Error('Issue exceeds the 240 KB task limit. Use a bounded task file instead.');
+  return { title: issue.title, url: issue.url, body: issue.body, spec };
+}

package/factory/machine.mjs

@@ -0,0 +1,15 @@
+import { hostname, platform, arch, cpus, totalmem, release } from 'node:os';
+import { readFileSync } from 'node:fs';
+
+// No subprocess, environment, serial number, network identity or credential data.
+function hardwareModel() {
+  if (platform() !== 'linux') return null;
+  try {
+    const value = readFileSync('/sys/devices/virtual/dmi/id/product_name', 'utf8').trim();
+    return value && value.length <= 160 && !/[\x00-\x1f]/.test(value) && !/default string|to be filled|system product name/i.test(value) ? value : null;
+  } catch { return null; }
+}
+export function machineInfo() {
+  return { hostname: hostname(), hardware: hardwareModel(), platform: platform(), architecture: arch(), osRelease: release(),
+    logicalCpus: cpus().length, memoryMiB: Math.round(totalmem() / 1024 / 1024) };
+}

package/factory/project-links.mjs

@@ -7,7 +7,7 @@ export function githubProjectLinks(remote) {
   const match = remote.trim().match(/^(?:https:\/\/github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)([A-Za-z0-9-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/);
   if (!match || ['.', '..'].includes(match[2])) return undefined;
   const repository = `https://github.com/${match[1]}/${match[2]}`;
-  return { repository, new_issue: `${repository}/issues/new`, source: 'configured_git_origin' };
+  return { repository, new_issue: `${repository}/issues/new/choose`, source: 'configured_git_origin' };
 }
 export function readProjectLinks(repo) {
   try {

package/factory/queue.mjs

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 import { existsSync, writeFileSync, rmSync } from 'node:fs';
 import { usageFields } from './usage.mjs';
 
-const workflows = { software: ['build', 'verify', 'review', 'handoff'], defence: ['defence'] };
+import { WORKFLOWS as workflows } from './workflows.mjs';
 const id = prefix => prefix + '_' + randomBytes(12).toString('hex');
 const now = () => new Date().toISOString();
 export class QueueError extends Error { constructor(message, status = 409) { super(message); this.status = status; } }

package/factory/server.mjs

@@ -2,7 +2,9 @@ import http from 'node:http';
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { existsSync, readFileSync, readdirSync, lstatSync, realpathSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
-import { hostname } from 'node:os';
+import { readIssue } from './issue-intake.mjs';
+import { machineInfo } from './machine.mjs';
+import { workflowDefinitions } from './workflows.mjs';
 import { JobQueue, QueueError } from './queue.mjs';
 import { executors } from './processes.mjs';
 import { configAt, ROOT } from './lib.mjs';
@@ -30,6 +32,7 @@ export function createController(state, adapter = executors(state)) {
   const token = readFileSync(join(state, 'worker.token'), 'utf8').trim();
   const queue = new JobQueue(state, adapter);
   const projectLinks = readProjectLinks(config.repo);
+  const definitions = workflowDefinitions(config), machine = machineInfo();
   const server = http.createServer(async (request, response) => {
     const send = (status, value, type = 'application/json; charset=utf-8') => { response.writeHead(status, { 'Content-Type': type }); response.end(type.startsWith('application/json') ? JSON.stringify(value) : value); };
     response.setHeader('Cache-Control', 'no-store'); response.setHeader('X-Content-Type-Options', 'nosniff'); response.setHeader('Referrer-Policy', 'no-referrer');
@@ -44,20 +47,12 @@ export function createController(state, adapter = executors(state)) {
       if (request.method === 'GET' && url.pathname === '/api/v1/status') {
         const jobs = queue.all().map(job => ({ ...job, can_request_changes: queue.canRequestChanges(job), runs: job.runs.map(attempt => attemptPresentation({ ...attempt,
           outcome: attempt.outcome || (attempt.state === 'succeeded' ? 'complete' : undefined) }, adapter.usage?.(job, attempt))) }));
-        return send(200, { version: 1, runtime_version: VERSION, maintenance: queue.maintenance, workflows: ['software', 'defence'], commands: [], triggers: [], jobs, csrf_token: csrf,
-          workers: [{ name: hostname(), instance_id: 'local-executor', repositories: ['app'], connected: !queue.closing, last_seen_at: new Date().toISOString() }],
+        return send(200, { version: 1, runtime_version: VERSION, maintenance: queue.maintenance, workflows: Object.keys(definitions.workflows), commands: [], triggers: [], jobs, csrf_token: csrf,
+          workers: [{ name: machine.hardware || machine.hostname, machine, instance_id: 'local-executor', repositories: ['app'], connected: !queue.closing, last_seen_at: new Date().toISOString() }],
           repositories: ['app'], repo: config.repo, project_links: projectLinks, agent: config.agent });
       }
       if (request.method === 'GET' && url.pathname === '/api/v1/definitions') {
-        const descriptions = {
-          build: 'Implement the accepted task in an isolated checkout, using the bundled policy and skills. Produce a candidate commit and implementation evidence.',
-          verify: `Run the configured application check on the candidate commit: ${config.check}`,
-          review: 'Independently review the candidate diff and checks. Record pass, changes or blocked with concrete findings.',
-          handoff: 'After operator approval, verify the candidate and policy still match the checks and review. Record acceptance without pushing, merging or deploying.',
-          defence: 'Read-only triage of an admitted, scoped incident. Produce a private draft, preserve unknowns and make no production change or recovery claim.',
-        };
-        return send(200, { workflows: { software: ['build','verify','review','handoff'].map(name => ({ name, approval: name === 'handoff' })), defence: [{ name: 'defence' }] },
-          commands: Object.entries(descriptions).map(([name,prompt]) => ({ name, prompt, executor: ['verify','handoff'].includes(name) ? 'deterministic' : config.agent, timeout: `${config.timeoutSeconds}s` })) });
+        return send(200, definitions);
       }
       const content = url.pathname.match(/^\/api\/v1\/artifacts\/(job_[a-f0-9]+)~(run_[a-f0-9]+)~([\w.-]+)\/content$/);
       const artifactList = url.pathname.match(/^\/api\/v1\/jobs\/(job_[a-f0-9]+)\/artifacts$/);
@@ -79,6 +74,10 @@ export function createController(state, adapter = executors(state)) {
           if (!equal(request.headers.authorization, `Bearer ${token}`)) throw new QueueError('Operator token required for maintenance', 403);
           return send(200, queue.setMaintenance(input.enabled));
         }
+        if (url.pathname === '/api/v1/issues/preview') {
+          try { return send(200, await readIssue(config.repo, input.url)); }
+          catch (error) { throw new QueueError(error.message, 400); }
+        }
         if (url.pathname === '/api/v1/jobs') {
           if (input.model && input.model !== config.model && !['codex','pi'].includes(config.agent)) throw new QueueError('Model overrides require a codex or pi executor', 400);
           return send(201, queue.submit(input));