software-defence-factory 0.10.0 → 0.11.1

package/.agents/skills/README.md

@@ -1,6 +1,6 @@
 # Factory skills
 
-These six original, portable skills are project-local Markdown. They require no AIOS installation. A harness must discover `.agents/skills` or receive the selected SKILL.md explicitly. The export command `node scripts/export-kit.mjs NEW_OUTPUT_DIRECTORY` stages these skills with the portable adoption kit. Copy the needed folders into a target repository under its own accepted instructions before dispatch. Do not overwrite its AGENTS.md.
+These six original, portable skills are project-local Markdown. A harness must discover `.agents/skills` or receive the selected SKILL.md explicitly. The export command `node scripts/export-kit.mjs NEW_OUTPUT_DIRECTORY` stages these skills with the portable adoption kit. Copy the needed folders into a target repository under its own accepted instructions before dispatch. Do not overwrite its AGENTS.md.
 
 - [factory-triage](factory-triage/SKILL.md): Turn an incoming factory issue into a bounded disposition and capability request. Use before specification or implementation starts.
 - [factory-spec](factory-spec/SKILL.md): Write an implementable factory task with observable acceptance criteria, required capabilities and a bounded verification plan.

package/README.md

@@ -1,27 +1,35 @@
-# Software & Defence Factory
+# Factory
 
 A portable method and a local runtime for taking a scoped software task through implementation, checks, independent review and an explicit handoff.
 
-Developed by [Arcitai](https://github.com/arcitai). The CLI is **software-defence-factory**. It works with existing repositories, Codex, Pi or a configured executor. No personal context system is required.
+Published by [Arcitai](https://github.com/arcitai). Invoke **factory** with your existing repositories, Codex, Pi or a configured executor. The npm package remains **software-defence-factory**; the compatibility executable `software-defence-factory` uses the same implementation, state and updater.
 
 ## Start here
 
 Install the published [npm package](https://www.npmjs.com/package/software-defence-factory). The CLI includes the dashboard; no source checkout is needed.
 
 ```sh
-npm install --global software-defence-factory
-software-defence-factory help
+npm install --global software-defence-factory@latest
+factory help
 ```
 
-For occasional use: `npx software-defence-factory@latest help`.
+For occasional use: `npm exec --package=software-defence-factory@latest -- factory help`.
+
+Starting with 0.11.1, the package provides both executable names. To upgrade an
+older global installation, run
+`npm install --global software-defence-factory@latest` to expose the new `factory`
+executable. Private cached updates keep the old command working but do not add
+global symlinks. Check `command -v factory` first; if it belongs to another tool,
+keep the compatibility command or use the explicit `npm exec` invocation above.
+Do not overwrite it with `--force`. See [installation compatibility](docs/npm.md).
 
 Choose the part you need:
 
 | Outcome | Command / guide |
 | --- | --- |
 | Set up an operator, worker and application | [Setup plan and acceptance checklist](docs/setup.md) |
-| Use the method with your existing agent | `software-defence-factory kit --output ./factory-kit` — exports a new staging directory |
-| Try the runtime without inference | `software-defence-factory demo` — Docker required; synthetic sample only |
+| Use the method with your existing agent | `factory kit --output ./factory-kit` — exports a new staging directory |
+| Try the runtime without inference | `factory demo` — Docker required; synthetic sample only |
 | Connect an existing repository | [Runtime quickstart](docs/quickstart.md) |
 | Understand installation and updates | [npm and npx](docs/npm.md) |
 | Restore a dashboard after boot or reconnect remotely | [Services and SSH tunnels](docs/services.md) |
@@ -37,11 +45,11 @@ The runtime supplies policy and six focused skills to its isolated jobs. `init`
 
 Each result belongs to a specific candidate commit and policy. A failed check blocks delivery. Changing the candidate or check policy invalidates earlier evidence. Approval records a handoff; publishing, merging and deployment follow the application's separate authority.
 
-The project dashboard has an **Inbox**, measured **Analytics**, **Agents**, **Skills**, **Automations**, **Definition** and **Infrastructure**. New issue offers the repository’s issue templates, a blank local form or a selectable GitHub issue. Create an issue on the supported repository provider, then choose Start work separately; local brief execution remains available. CLI `issue` exposes the same intake. Definition lives with settings above the theme control. The CLI reads the same definition and controller state. Agent roles use a selected harness such as Codex or Pi; a worker executes their isolated jobs on a host. See [concepts](docs/concepts.md) and [supported interfaces](docs/interfaces.md). Optional automations belong to the selected harness, which calls Factory CLI/API. Factory runs no cron scheduler. See [provider boundaries](docs/integrations.md).
+The project dashboard has an **Inbox**, measured **Analytics**, **Agents**, **Skills**, **Automations**, **Definition** and **Infrastructure**. Inbox lists repository issues with readiness and linked execution attempts. New issue offers repository templates or a blank creation form. Create an issue on the supported repository provider, then choose Start work separately; local brief execution remains available. CLI `issue` exposes the same intake. Definition lives with settings above the theme control. The CLI reads the same definition and controller state. Agent roles use a selected harness such as Codex or Pi; a worker executes their isolated jobs on a host. See [concepts](docs/concepts.md) and [supported interfaces](docs/interfaces.md). Optional automations belong to the selected harness, which calls Factory CLI/API. Factory runs no cron scheduler. See [provider boundaries](docs/integrations.md).
 
 The 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).
 
-Start setup with `software-defence-factory foundation` and the [Factory Foundation plan](docs/setup.md). No AIOS installation is required.
+Start setup with `factory foundation` and the [Factory Foundation plan](docs/setup.md).
 
 ## Repository map
 
@@ -55,8 +63,6 @@ Start setup with `software-defence-factory foundation` and the [Factory Foundati
 | `scripts/`, `tests/` | Packaging, qualification, release checks and behavioral tests |
 | `docs/` | Setup, architecture, recovery, proof and ownership |
 
-The current runtime replaces earlier prototypes. Their source and research remain in Git history; they are not part of the installed package.
-
 ## Contributing
 
 Requires Node 22.13+, npm and Git. Docker is needed only for integration qualification.

package/bin/software-defence-factory.mjs

@@ -6,7 +6,7 @@ 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, PUBLICATION_API_TIMEOUT_MS } from '../factory/lib.mjs';
 import { assertInstalledJobImage, installCustomJobImage, installStandardJobImage, inspectImageInstallation } from '../factory/image-install.mjs';
-import { listIssues, readIssue } from '../factory/issue-intake.mjs';
+import { readIssue } from '../factory/issue-intake.mjs';
 import { recommendWork } from '../factory/intake.mjs';
 import { factoryDefinition, foundationSkill } from '../factory/definition.mjs';
 import { harnessOf } from '../factory/lib.mjs';
@@ -55,6 +55,16 @@ function init(repo, harness='codex', check='', port=7331, sourceRef='HEAD', deli
   console.log(`Configured ${state}\nApp files were not changed. Only committed code is cloned into jobs.`);
 }
 
+async function listInbox(defaultSource) {
+  const source=flags.source || defaultSource;
+  if(!['factory','inbox','remote','github'].includes(source))throw new Error('Choose --source factory, inbox or remote');
+  if(source==='factory') {
+    if(flags.page !== undefined || flags['issue-state'] !== undefined)throw new Error('Repository paging/state filters require --source inbox or remote.');
+    return (await api(state,'/api/v1/status')).jobs;
+  }
+  return api(state,`/api/v1/issues?page=${encodeURIComponent(flags.page || 1)}&state=${encodeURIComponent(flags['issue-state'] || 'open')}`);
+}
+
 async function install() {
   const config=configAt(state);
   if (!['darwin','linux'].includes(process.platform)||!['arm64','x64'].includes(process.arch)) throw new Error('Use macOS/Linux arm64/amd64, or WSL2');
@@ -101,10 +111,10 @@ async function stop() {
   }
   stopContainers(state);console.log('Controller and its labelled containers stopped.');
 }
-async function submit(workflow,spec,sourceRef=flags['source-ref']) {
+async function submit(workflow,spec,sourceRef=flags['source-ref'],sourceURL) {
   if(Buffer.byteLength(spec)>240000)throw new Error('Task exceeds 240 KB');
   const title=workflow==='defence'?'Private incident triage':spec.split('\n').find(s=>s.trim())?.replace(/^#+\s*/, '').slice(0,100)||'Software task';
-  return api(state,'/api/v1/jobs',{workflow,repository:'app',spec,title,...(sourceRef===undefined?{}:{source_ref:sourceRef})});
+  return api(state,'/api/v1/jobs',{workflow,repository:'app',spec,title,...(sourceURL?{source_url:sourceURL}:{}),...(sourceRef===undefined?{}:{source_ref:sourceRef})});
 }
 async function jobAction(action) {
   const id=positional[0];if(!/^job_[a-z0-9]+$/.test(id || ''))throw new Error('A job ID is required');
@@ -157,6 +167,7 @@ async function abandonDeliveryJob(jobId) {
 }
 
 try {
+  if(flags['brief-file'] !== undefined && (command !== 'issue' || positional[0] !== 'start' || !(flags.url || flags.github) || flags.file || flags.draft))throw new Error('Use --brief-file only with issue start --url (or --github); local --file/--draft already supplies the scope.');
   if(command==='init') {
     if(!flags.repo)throw new Error('init requires --repo /path/to/existing/git/repo');
     if(flags.harness && flags.agent && flags.harness !== flags.agent)throw new Error('--harness conflicts with legacy --agent');
@@ -191,9 +202,10 @@ try {
     const value=command==='agents'?definition.agents:command==='skills'?{agents:definition.skills,operators:definition.operator_skills}:definition;
     console.log(JSON.stringify(value,null,2));
   }
-  else if(['infrastructure','automations','inbox'].includes(command)) {
+  else if(command==='inbox')console.log(JSON.stringify(await listInbox('inbox'),null,2));
+  else if(['infrastructure','automations'].includes(command)) {
     const snapshot=await api(state,'/api/v1/status');
-    console.log(JSON.stringify(command==='inbox'?snapshot.jobs:command==='automations'?snapshot.automation_control:snapshot[command],null,2));
+    console.log(JSON.stringify(command==='automations'?snapshot.automation_control:snapshot[command],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') {
@@ -204,8 +216,7 @@ try {
   } else if(command==='issue') {
     const action=positional[0], sourceURL=flags.url || flags.github;
     if(action==='list') {
-      if(flags.source && !['factory','remote','github'].includes(flags.source))throw new Error('Choose --source factory or remote');
-      console.log(JSON.stringify(['github','remote'].includes(flags.source) ? await api(state,`/api/v1/issues?page=${encodeURIComponent(flags.page || 1)}`) : (await api(state,'/api/v1/status')).jobs,null,2));
+      console.log(JSON.stringify(await listInbox('factory'),null,2));
     } else if(action==='templates') console.log(JSON.stringify(await api(state,'/api/v1/issue-templates'),null,2));
     else if(action==='connection') console.log(JSON.stringify(await api(state,'/api/v1/issue-connection'),null,2));
     else if(action==='submissions') console.log(JSON.stringify(await api(state,'/api/v1/issue-submissions'),null,2));
@@ -233,17 +244,21 @@ try {
     } else if(action==='start') {
       if(!['software','defence'].includes(flags.workflow))throw new Error('Review the issue and choose --workflow software or defence');
       if([flags.file,sourceURL,flags.draft].filter(Boolean).length!==1)throw new Error('Choose --file brief.md, --draft draft.json or --url ISSUE_URL');
-      let input;
-      if(sourceURL) { const issue=await api(state,'/api/v1/issues/preview',{url:sourceURL});input={title:issue.title,spec:issue.spec,source_url:issue.url}; }
+      let input, brief;
+      if(flags['brief-file'] !== undefined) {
+        brief=readFileSync(resolve(flags['brief-file']),'utf8');
+        if(brief.length>16000)throw new Error('Operator brief must be at most 16000 characters.');
+      }
+      if(sourceURL) { const issue=await api(state,'/api/v1/issues/preview',{url:sourceURL});input={title:issue.title,url:issue.url,expected_spec:issue.spec,...(brief===undefined?{}:{brief})}; }
       else if(flags.draft) { const draft=json(resolve(flags.draft));input={title:draft.title,spec:draft.spec}; }
       else input={title:flags.title,spec:readFileSync(resolve(flags.file),'utf8')};
       input.title=flags.title || input.title;
-      if(typeof input.title!=='string'||!input.title.trim()||input.title.length>160)throw new Error('Provide a title of 1–160 characters (use --title for a blank issue)');
+      if(!sourceURL && (typeof input.title!=='string'||!input.title.trim()||input.title.length>160))throw new Error('Provide a title of 1–160 characters (use --title for a blank issue)');
       if(flags.workflow==='software'&&!configAt(state).check?.trim())throw new Error('Configure an app check before submitting software work');
-      console.log(JSON.stringify(await api(state,'/api/v1/jobs',{...input,workflow:flags.workflow,repository:'app',model:flags.model || '',...(flags['source-ref']===undefined?{}:{source_ref:flags['source-ref']})}),null,2));
+      console.log(JSON.stringify(await api(state,sourceURL ? '/api/v1/issues/start' : '/api/v1/jobs',{...input,workflow:flags.workflow,repository:'app',model:flags.model || '',...(flags['source-ref']===undefined?{}:{source_ref:flags['source-ref']})}),null,2));
     } else throw new Error('Use issue list|connection|templates|preview|recommend|draft|create|start|submissions|recover; see help');
   } else if(command==='issues') {
-    console.log(JSON.stringify(await listIssues(configAt(state).repo,Number(flags.page || 1)),null,2));
+    console.log(JSON.stringify(await listInbox('inbox'),null,2));
   } else if(command==='recommend') {
     if(Boolean(flags.issue) === Boolean(flags.file))throw new Error('Choose --file task.md or --issue URL');
     const recommendation=flags.issue ? (await readIssue(configAt(state).repo,flags.issue)).recommendation : recommendWork({spec:readFileSync(resolve(flags.file),'utf8')});
@@ -251,13 +266,13 @@ try {
   } else if(command==='run') {
     const workflow=flags.workflow || 'software';
     if(!['software','defence'].includes(workflow))throw new Error('Choose --workflow software or defence');
-    let spec;
+    let spec,sourceURL;
     if(flags.issue) {
-      spec=(await readIssue(configAt(state).repo,flags.issue)).spec;
+      const issue=await readIssue(configAt(state).repo,flags.issue);spec=issue.spec;sourceURL=issue.url;
     } 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(workflow==='software'&&!configAt(state).check?.trim())throw new Error('Configure an app check before submitting software work');
-    console.log(JSON.stringify(await submit(workflow,spec)));
+    console.log(JSON.stringify(await submit(workflow,spec,flags['source-ref'],sourceURL)));
   } else if(command==='incident') {
     if(!flags.file)throw new Error('Use --file incident.json; see factory/examples/incident.json');
     console.log(JSON.stringify(await admitIncident(state,json(resolve(flags.file)),submit)));
@@ -289,7 +304,10 @@ try {
   } else if(command==='kit') {
     if(!flags.output)throw new Error('kit requires --output NEW_DIRECTORY');
     await stream(process.execPath,[join(ROOT,'scripts/export-kit.mjs'),resolve(flags.output)]);
-  } else if(['help','--help','-h'].includes(command))console.log(`Software & Defence Factory ${VERSION} (test release)
+  } else if(['help','--help','-h'].includes(command))console.log(`Factory ${VERSION} (test release)
+
+Usage: factory <command> [options]
+Compatibility executable: software-defence-factory (same runtime and state)
 
   kit --output NEW_DIRECTORY               Export the portable method without a runtime
   demo                                    Install and run a synthetic sample (no model key)
@@ -303,7 +321,9 @@ try {
   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
-  inbox | infrastructure | automations    Inspect live tasks, host/worker and automation state
+  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
   workflows                               Compatibility alias for definition
   --agent                                 Legacy alias for init --harness
   serve                                   Foreground supervisor
@@ -316,7 +336,8 @@ try {
   service resume                          Release a reconciled maintenance reservation
   tunnel install|start|stop|status|logs|uninstall --host SSH_ALIAS --port PORT
                                           Persistent loopback SSH tunnel (macOS/Linux)
-  issue list [--source remote] [--page N]  List local executions or open repository issues
+  issue list [--source inbox|remote|factory] [--page N] [--issue-state open|closed|all]
+                                          List linked repository issues or local executions (default)
   issue templates                         Read this repository's issue forms and contact links
   issue preview --url URL              Preview one repository issue without starting work
   issue recommend --file brief.md | --url URL
@@ -328,8 +349,9 @@ try {
   issue recover --key REQUEST_ID           Reconcile an uncertain creation without another write
   issue start --draft draft.json | --url URL | --file brief.md --title TITLE
                --workflow software|defence [--source-ref REF] [--model MODEL]
-                                          Create a local issue and start work; no GitHub write
-  issues [--page N]                       Browse open project issues, with next_page for more
+               [--brief-file operator.md]  Only with --url; at most 16000 characters
+                                          Explicitly start execution; no GitHub write
+  issues [--page N]                       Browse linked project issues; supports --issue-state
   recommend --file task.md | --issue URL  Suggest a work type without starting work
   run --file task.md | --issue URL         Submit software (default), or --workflow defence
        [--source-ref REF]                 Pin a configured-repository ref before admission

package/docs/defence-integration.md

@@ -3,7 +3,7 @@
 The optional defence workflow receives a bounded incident record through:
 
 ```sh
-software-defence-factory incident --file /private/path/incident.json --state /private/state/my-app
+factory incident --file /private/path/incident.json --state /private/state/my-app
 ```
 
 Use factory/examples/incident.json as the input schema example. Intake validates scope and evidence, records a digest and deduplicates the event identity. Evidence and reports remain in the private installation. Do not place customer findings in public issues or source control.

package/docs/interfaces.md

@@ -9,9 +9,10 @@ shell endpoint or a second scheduler.
 
 | Capability | CLI | Shared API | Dashboard | Remaining work |
 | --- | --- | --- | --- | --- |
-| Project/queue/attempt state | `status`, `inbox` JSON | `GET /api/v1/status` | Project, tasks, details/history | Stable versioned agent result/error contract |
-| Start local work | `issue start --file --title`, `--draft` or `--url`, explicit `--workflow`, optional `--model` | `POST /api/v1/jobs` | Local execution only → review → Create & start locally | Persistent unstarted drafts and typed incident intake remain separate |
-| Browse/import repository issues | `issue list --source remote [--page N]`, `issue preview --url URL` via controller provider | Authenticated `GET /api/v1/issues`, `POST /api/v1/issues/preview` using shared readers | Paged open-issue list, search loaded results, preview and explicit start for either type | Issue → execution links retained; no implicit polling |
+| Project/queue/attempt state | `status`, `inbox --source factory` JSON | `GET /api/v1/status` | Project, tasks, details/history | Stable versioned agent result/error contract |
+| Start local work | `issue start --file --title` or `--draft`, explicit `--workflow`, optional `--model` | `POST /api/v1/jobs` | Local execution only → review → Create & start locally | Persistent unstarted drafts and typed incident intake remain separate |
+| Browse repository Inbox | `inbox [--page N] [--issue-state open/closed/all]` (also `issue list --source inbox`), `issue preview --url URL` via controller provider | Authenticated `GET /api/v1/issues`, `POST /api/v1/issues/preview` using shared readers | Inbox with provider/state/readiness, loaded-page counts, linked attempts, local/off-page history; explicit Start work for either type | Issue → execution links retained; no implicit polling |
+| Start repository work | `issue start --url URL --workflow software/defence [--brief-file operator.md]` | `POST /api/v1/issues/start` | Issue context → explicit Start work with operator brief | Rechecks current content and active admission |
 | Create repository issue / recovery | `issue connection`, `create --key`, `submissions`, `recover --key` | Authenticated connection, `POST /issues`, receipts and recovery | Display destination/actor, create without execution, recover uncertain result | GitHub adapter first; assignees/projects and other providers unimplemented |
 | Repository issue templates | `issue templates`, `issue draft --template --sha --file` | Authenticated template list and draft compilation | Chooser, fields/defaults/validation, review | Supports Markdown and YAML markdown/input/textarea/dropdown/checkboxes; unsupported templates link to GitHub |
 | Suggest task type | `issue recommend --file` or `--url` | Authenticated `POST /api/v1/intake/recommend`; issue preview includes suggestion | Editable recommendation after source selection | Deterministic label/brief rules; no model judgment or execution authority |
@@ -32,7 +33,7 @@ shell endpoint or a second scheduler.
 | SSH tunnels | `tunnel` | No tunnel endpoint | None | Client-host ownership; distinguish operator machine from worker |
 | Method export | `kit --output` | No export endpoint | None | Equivalent download/export preserving staging-only adoption |
 | 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 | New issue 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 |
+| 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 |
 | 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) |
 
@@ -57,3 +58,51 @@ the Skills page reads that same file. Full safe setup controls remain #37.
 The roadmap is split into Defence #50, quality measurement #51, GitHub intake
 #52, editable definitions #53 and scoped MCP #54. Existing REST endpoints are
 local single-operator interfaces, not a public multi-user API.
+
+
+## Issue lifecycle API in 0.11.0
+
+`GET /api/v1/issues?page=1&state=open` retains repository/issues/next_page and adds
+provider, page, state, loaded_count, total (null when unknown), and history.
+Each issue adds canonical identity, provider state, readiness, executions,
+latest_execution, active_execution(s), and start_block_reason. History groups
+local jobs and canonical sources outside the page; not_loaded does not claim
+that an issue is missing or closed. `status.issue_history` refreshes these local
+associations without polling the provider. No issue content database was added.
+
+`POST /api/v1/issues/preview` retains content/labels/recommendation and adds the
+same identity/readiness/history contract. `POST /api/v1/issues/start` accepts
+url, expected_spec (the preview's spec), workflow, optional brief, source_ref
+and model. It re-reads current provider context, rejects changed scope, closed
+sources, blocked/conflicting readiness and active/unresolved work, then uses
+existing source admission. HTTP 409 describes stale or duplicate admission.
+`POST /api/v1/jobs` remains compatible for local/direct callers; its queue-level
+canonical reservation also rejects concurrent duplicate active work and retries.
+Terminal succeeded/failed/cancelled executions release the reservation unless
+provider delivery is unresolved. Other/unknown states retain it conservatively.
+
+`inbox` now defaults to the same repository page object as the dashboard (open,
+page 1), an intentional 0.11.0 JSON change from its former jobs array. Use
+`inbox --source factory` for the explicit legacy execution-only array.
+`issue list` still defaults to the original local jobs array (`--source factory`).
+`--source inbox`, `remote` and compatibility `github` return the shared enriched
+page. `issues` now uses this same authenticated controller endpoint and enriched
+JSON, rather than bypassing the controller; scripts need a running controller.
+Use `--issue-state` for provider state; `--state` continues to mean installation
+path. Repository paging/state options are rejected in execution-only mode rather
+than ignored. Unsupported providers return their capability state and local/history
+records; provider/auth failures exit nonzero, never an empty-success backlog.
+`issue start --url URL --brief-file operator.md` reads a UTF-8 operator brief of at
+most 16000 characters (the API's string-length limit), forwarded unchanged to the
+shared preview/start contract. The API appends nonblank, trimmed text under
+`Operator brief:` in the admitted spec, while preserving provider identity and
+rechecking current content. `--brief-file` is optional, only valid with remote
+`issue start --url` (or its `--github` alias); it cannot accompany local `--file`
+or `--draft`, creation, browsing or other commands. Missing/unreadable files and
+oversize text fail without admission. Local file/draft execution is unchanged. `run` retains
+its compatible direct-job path and the controller's duplicate identity guard.
+
+Definition exposes `configuration.issueReadinessLabels`. The optional private
+config field has exactly triage/spec/ready/blocked keys with four distinct label
+names; defaults are factory:triage/spec/ready/blocked. Configuration is validated,
+not inferred from issue content. No browsing path changes labels or comments.

package/docs/npm.md

@@ -4,24 +4,53 @@ Requires Node 22.13 or later. The method export needs no Docker. Running jobs
 also requires Git and a running Docker Engine or Docker Desktop on Linux/macOS.
 
 ```sh
-npm install --global software-defence-factory
-software-defence-factory help
+npm install --global software-defence-factory@latest
+factory help
 ```
 
 For a one-off invocation:
 
 ```sh
-npx software-defence-factory@latest help
+npm exec --package=software-defence-factory@latest -- factory help
 ```
 
 Both commands use the same package. A development checkout is unnecessary.
-Use `software-defence-factory kit --output /new/staging/directory` to export the portable
+Use `factory kit --output /new/staging/directory` to export the portable
 method. It refuses an existing destination and does not modify an app. Use
-`software-defence-factory init --repo /path/to/app --harness codex --check "npm ci && npm test"`
+`factory init --repo /path/to/app --harness codex --check "npm ci && npm test"`
 only when configuring the optional local job runner. `init` does not start jobs,
 copy skills into the app, or copy account credentials. Runtime jobs receive the
 bundled policy and skills directly. Model access is configured separately.
 
+## Executable and package compatibility
+
+Starting with 0.11.1, `factory` and `software-defence-factory` are bin aliases
+for `bin/software-defence-factory.mjs`. They share one runtime, state and updater.
+The npm package is still `software-defence-factory`, published by Arcitai from
+`arcitai/software-and-defence-factory`. Release qualification is tracked in
+[#61](https://github.com/arcitai/software-and-defence-factory/issues/61) and its linked delivery PRs.
+
+An older global bootstrap upgraded through the private release cache keeps
+working through `software-defence-factory`, including offline cached dispatch.
+It does **not** gain a global `factory` symlink. To expose both bins with
+0.11.1 or later, stop and reconcile installations, check `command -v factory`, then run
+`npm install --global software-defence-factory@latest`.
+If that name belongs to another tool, keep the compatibility executable or use
+`npm exec --package=software-defence-factory@latest -- factory ...`. Do not use
+`--force` to replace another program. npm refuses a conflicting unrelated bin.
+Both bin keys point to the same file; tarball tests cover explicit executable
+selection through npm exec and npx. The syntax above avoids relying
+on package-name inference. Never use `npx factory` or `npm install factory` for
+this product.
+
+The selected successor package is `factory-sd`, but account/OIDC prerequisites
+and namespace cutover remain pending under [#61](https://github.com/arcitai/software-and-defence-factory/issues/61).
+The issue records `factory` as owned by another project and `factory-sd` as a
+registry 404 on 2026-09-26; availability is not a reservation. Before cutover,
+verify replacement publishing trust, package/updater identity, Actions references,
+redirects and an explicit idle/recoverable upgrade route. Reconcile ambiguous
+external-write receipts without replaying them under a renamed repository.
+
 ## Persistent data
 
 The npm CLI stores private runtime data under
@@ -34,7 +63,9 @@ the npx cache, or your application repository.
 Source checkouts retain their existing `.factory/platform` and
 `.factory/demo-platform` defaults. Stop the old controller before moving an
 existing state directory. Update its `factory.json` repository path if necessary;
-start a fresh state directory for the native 0.3 runtime. Earlier engine journals are not automatically migrated; keep them separately as evidence.
+retain existing jobs, configuration and evidence. Branding requires no state move
+or migration. State/service/tunnel names, configured image IDs, update keys and
+historical policy/record hashes remain unchanged.
 
 ## Automatic updates
 
@@ -50,10 +81,10 @@ and restores their prior running set without interrupting a job. See
 [services](services.md) for installation, maintenance recovery and limitations.
 
 ```sh
-software-defence-factory update --check
-software-defence-factory update
-software-defence-factory update --auto off
-software-defence-factory update --auto on
+factory update --check
+factory update
+factory update --auto off
+factory update --auto on
 ```
 
 Updates use npm with lifecycle scripts disabled and retain immutable releases
@@ -73,8 +104,8 @@ installation or retained attempt needs them.
 
 ## Protected evidence compatibility
 
-0.10.0 recognizes version-1 execution profiles emitted by native **0.8.0,
-0.9.0, 0.9.1 and 0.10.0**. This is an exact allowlist in
+Factory 0.11.1 recognizes version-1 execution profiles emitted by native
+**0.8.0, 0.9.0, 0.9.1, 0.10.0, 0.11.0 and 0.11.1**. 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
@@ -101,9 +132,9 @@ neither a reason to discard evidence nor proof of compatibility. Retain
 unsupported records unchanged and obtain fresh applicable evidence through the
 normal workflow; never repair them by editing private records or hashes.
 
-The 0.10.0 writer retains the same profile format and original-base, aggregate
-single-parent candidate/check/review/approval guarantees. Continuation adds
-separate provenance; it is not acceptance evidence. The audited 0.8.0, 0.9.0 and
+Versions 0.11.0 and 0.11.1 use the same protected evidence writer and profile
+format, with original-base, aggregate single-parent candidate/check/review/approval
+guarantees. Continuation adds separate provenance; it is not acceptance evidence. The audited 0.8.0, 0.9.0 and
 0.9.1 writers remain supported only when their old records meet all current
 checks. For continuation specifically, the current completed review, successful
 Build/Verify, protected per-attempt artifacts, current policy and clean candidate
@@ -112,14 +143,10 @@ a checkpoint usable. Browser-disabled 0.8.0 records cannot satisfy a newly
 enabled browser policy. Missing or unsupported records stay unchanged and
 unavailable; no schema migration, profile relabeling or policy repair occurs.
 
-#71 shipped 0.9.0 through PR #81 and #84 shipped 0.9.1 through PR #85; both
-passed installed qualification, as reported by the lead. For this 0.10.0 slice,
-native Verify/Review remain required. The lead owns installed continuation,
-disposable protected PR/CI and desktop/narrow light/dark browser qualification
-on Z13. Controlled source fixtures do not supply that proof. New publication
-still requires the current remote target to equal the original accepted base;
-reviewed-candidate continuation preserves that baseline, while target refresh
-remains #72.
+New publication still requires the current remote target to equal the original
+accepted base; reviewed-candidate continuation preserves that baseline, while
+target refresh remains #72. See [the verification map](https://github.com/arcitai/software-and-defence-factory/blob/main/docs/proof.md) for delivered
+capabilities and the distinction between source checks and installed proof.
 
 ## Release flow
 
@@ -133,20 +160,27 @@ For a release, update both manifests with `npm version patch --no-git-tag-versio
 review the change, and push through the project's normal review flow. A code
 push without a version bump is tested but does not overwrite a published package.
 
-The first release is published by the maintainer. Then configure npm trusted
-publishing for GitHub owner `arcitai`, repository `software-and-defence-factory`,
-workflow filename `ci.yml`, with direct publishing enabled. Subsequent releases
-use short-lived OIDC authentication; no npm write token belongs in the repo or
-Z13. The source repository remains private, so npm cannot issue public source
-provenance for it. The public npm package contains an explicit runtime/method
+The current trusted-publisher identity is npm package `software-defence-factory`,
+GitHub owner `arcitai`, repository `software-and-defence-factory`,
+workflow filename `ci.yml`. The workflow uses short-lived OIDC authentication.
+The source repository is **public**, but the current workflow explicitly sets
+`NPM_CONFIG_PROVENANCE=false`; OIDC authenticates publication and does not mean
+this release emits npm provenance. No npm write token belongs in the repository
+or agent jobs. The public npm package contains an explicit runtime/method
 allowlist, excluding operational state, account data and retired research. It includes the explicitly labelled synthetic runtime fixture used by demo and qualification.
 
-Set the GitHub repository variable `NPM_PUBLISH_ENABLED=true` only after that
-first publication and trusted-publisher binding are complete. Until then CI
-still builds and tests every change, while publishing is deliberately skipped.
+Publication requires repository variable `NPM_PUBLISH_ENABLED=true` and the
+matching npm account binding. Preserve the working identity until replacement
+trust is verified. Changes must pass the normal protected PR/CI flow; do not
+weaken protection or bypass merge checks.
 After a CLI update, restart a stopped dashboard with `up --state PATH` and refresh
 the browser to load the new bundled interface. Updates do not replace the code
 of a controller that is still running.
 
+The installed native publisher refuses `.github/workflows` changes. Keep that
+guard. Automated GitHub Releases, immutable tags, registry readback and recovery
+after npm succeeds but Release creation fails remain a separate maintainer
+delivery under [#61](https://github.com/arcitai/software-and-defence-factory/issues/61).
+
 References: [npm/npx](https://docs.npmjs.com/cli/v11/commands/npx/),
 [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).

package/docs/ownership.md

@@ -1,9 +1,9 @@
 # Ownership and provenance
 
-Software & Defence Factory is developed by Arcitai. Original CLI, native Node/SQLite runtime, container boundary, incident intake, updater, method and six skills are maintained in this repository under MIT.
+Factory is developed by Arcitai. Original CLI, native Node/SQLite runtime, container boundary, incident intake, updater, method and six skills are maintained in this repository under MIT.
 
 The dashboard retains the selected third-party interface and interaction model, with modified branding and a factory-owned API integration. Its original copyright, source revision and permission notice are retained in [THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md), together with notices for bundled UI components and fonts. Those notices are required source attribution, not runtime dependencies or product branding.
 
-The installed package includes no personal AIOS home, private owner memory or external agent plugin. A skill is an instruction, not a bundled browser, model subscription, provider account or security scanner. Codex/Pi are separately licensed tools included by the pinned Docker build; the operator supplies authorized inference access.
+A skill is an instruction, not a bundled browser, model subscription, provider account or security scanner. Codex/Pi are separately licensed tools included by the pinned Docker build; the operator supplies authorized inference access.
 
-Earlier research and prototype implementations remain in Git history. Their historical evaluation claims do not establish qualification of the current runtime. Current evidence is recorded in [proof](proof.md).
+Current verification boundaries are recorded in [proof](https://github.com/arcitai/software-and-defence-factory/blob/main/docs/proof.md).

package/docs/quickstart.md

@@ -2,18 +2,18 @@
 
 For a new execution host or remote operator, start with the [setup plan](setup.md).
 
-Install Node 22.13+, Git and Docker Engine/Desktop. Use an unprivileged account with Docker access. Install `software-defence-factory` through npm, or invoke the same package with npx. No factory source checkout is required.
+Install Node 22.13+, Git and Docker Engine/Desktop. Use an unprivileged account with Docker access. Install `software-defence-factory` through npm, or use `npm exec --package=software-defence-factory@latest -- factory help`. No factory source checkout is required.
 
 ## Qualify a synthetic installation
 
 ```sh
-software-defence-factory demo
+factory demo
 ```
 
 Open the printed localhost URL, inspect the sample task and its files, then approve the handoff. This changes only an isolated synthetic repository and makes no inference calls. Once the sample finishes:
 
 ```sh
-software-defence-factory qualify --state /absolute/path/printed/by/demo
+factory qualify --state /absolute/path/printed/by/demo
 ```
 
 The qualification intentionally creates failed, cancelled and interrupted tasks. They are expected evidence of failure handling. Never point qualification at an application installation.
@@ -23,9 +23,9 @@ The qualification intentionally creates failed, cancelled and interrupted tasks.
 Commit an intentional, reviewed starting point in the application first. Jobs clone committed code only; uncommitted work stays in the source checkout.
 
 ```sh
-software-defence-factory init --repo /absolute/path/to/app --harness codex --check "npm ci && npm test" --source-ref main --state /private/state/my-app --port 7331
-software-defence-factory install --state /private/state/my-app
-software-defence-factory doctor --state /private/state/my-app
+factory init --repo /absolute/path/to/app --harness codex --check "npm ci && npm test" --source-ref main --state /private/state/my-app --port 7331
+factory install --state /private/state/my-app
+factory doctor --state /private/state/my-app
 ```
 
 `init --source-ref` selects the configured default ref (`HEAD` when omitted). Each job resolves that ref, or an explicit `--source-ref` on `run`/`issue start`, in the configured repository and durably retains its commit before acknowledging admission. It records the canonical GitHub origin identity when available; the CLI and dashboard show the requested ref and resolved SHA. Task text and reference links do not select a repository, source ref or PR target.
@@ -71,8 +71,8 @@ container. Host loopback addresses do not automatically refer to the host from
 Docker. The package does not automatically expose Ollama or import models.
 
 ```sh
-software-defence-factory up --state /private/state/my-app
-software-defence-factory run --file task.md --source-ref main --state /private/state/my-app
+factory up --state /private/state/my-app
+factory run --file task.md --source-ref main --state /private/state/my-app
 ```
 
 A task should describe the accepted outcome, allowed scope and observable checks. The CLI also accepts `--issue https://github.com/owner/repo/issues/123` for an issue belonging to the configured origin; it uses the operator's existing gh access outside the job. The dashboard supports the same task workflow. Source text and links do not grant additional authority.
@@ -90,7 +90,7 @@ canonical GitHub origin and an explicit target while initializing the private
 installation:
 
 ```sh
-software-defence-factory init --repo /absolute/path/to/app --harness codex \
+factory init --repo /absolute/path/to/app --harness codex \
   --check "npm ci && npm test" --source-ref main \
   --delivery-provider github \
   --delivery-repository https://github.com/OWNER/REPO \
@@ -109,7 +109,7 @@ After the ordinary check, independent review and operator approval complete,
 use **Publish accepted candidate as draft PR** in task details or run:
 
 ```sh
-software-defence-factory publish JOB_ID --state /private/state/my-app
+factory publish JOB_ID --state /private/state/my-app
 ```
 
 Trusted publication requires protected per-run execution records for native
@@ -149,7 +149,7 @@ create a second PR or overwrite a changed branch. The CLI gives this bounded
 multi-request action ten minutes; branch resolution uses the same bound and
 other API calls keep their five-second deadline. If a client deadline expires,
 inspect status and repeat `publish` to reconcile or recheck the reported branch
-identity before `abandon-delivery`. Delete issue stays disabled while delivery
+identity before `abandon-delivery`. Remove local execution history stays disabled while delivery
 is unresolved, and the controller enforces the same guard on its API.
 Publication does not merge, integrate, release or deploy. See [delivery
 recovery](recovery.md#trusted-pr-delivery).
@@ -179,8 +179,8 @@ Build a compatible application image on the execution host, then select its exis
 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
+factory install --image LOCAL_IMAGE_REF --state /private/state/my-app
+factory doctor --state /private/state/my-app
 ```
 
 Selection resolves and retains the immutable image ID. It does not pull or build
@@ -211,8 +211,7 @@ use the [Defence integration](defence-integration.md) recipe; the generic
 Defence form is not that typed intake path.
 
 The header names the configured project. View repo opens a validated GitHub
-origin. New issue opens Factory’s local chooser: repository templates, a blank
-form or existing GitHub issues. Create issue saves to the supported repository provider without execution. Start work queues local work. See [intake and CLI examples](workflows.md). The task detail provides previous/next within the filtered list, copy
+origin. Inbox lists repository issues directly with open/closed/all filters and paging. New issue opens repository templates or a blank creation form. Create issue saves to the supported repository provider without execution. Open an issue from Inbox and choose Start work to admit execution explicitly. The controller rejects duplicate active work; linked attempts remain accessible. See [intake and CLI examples](workflows.md). The task detail provides previous/next within the filtered list, copy
 link and close (Escape). Closing preserves the list's filters and position.
 
 If the interface looks unexpectedly small, check the browser zoom. The design
@@ -229,5 +228,5 @@ is unnecessary for this CLI. Optional
 process settings are `SDF_AUTO_UPDATE=0` (skip automatic CLI update checks),
 `XDG_STATE_HOME`, `XDG_DATA_HOME` and `XDG_CONFIG_HOME` (user-owned state, release
 and service locations). They must be exported in the process environment.
-Legacy prototype names such as `FACTORY_WORKER_CONFIG`, `FACTORY_MODEL`, `PORT`
+Unsupported environment variables such as `FACTORY_WORKER_CONFIG`, `FACTORY_MODEL`, `PORT`
 and `FACTORY_DEMO` are not supported. See [concepts](concepts.md).