software-defence-factory 0.5.1 → 0.6.0

package/README.md

@@ -37,7 +37,7 @@ 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. Review the suggested work type before Create & start. 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). Automations are not implemented yet; work starts manually.
+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 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/bin/software-defence-factory.mjs

@@ -7,7 +7,6 @@ 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 { listIssues, readIssue } from '../factory/issue-intake.mjs';
-import { readTemplates, draftFromTemplate } from '../factory/issue-templates.mjs';
 import { recommendWork } from '../factory/intake.mjs';
 import { factoryDefinition, foundationSkill } from '../factory/definition.mjs';
 import { harnessOf } from '../factory/lib.mjs';
@@ -153,7 +152,7 @@ try {
   }
   else if(['infrastructure','automations','inbox'].includes(command)) {
     const snapshot=await api(state,'/api/v1/status');
-    console.log(JSON.stringify(command==='inbox'?snapshot.jobs:snapshot[command],null,2));
+    console.log(JSON.stringify(command==='inbox'?snapshot.jobs: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') {
@@ -161,32 +160,46 @@ try {
     console.log(JSON.stringify({node:process.version,docker:dockerVersion,engineInstalled:imageStatus.installed,image:imageStatus.image,repo:config.repo,harness:harnessOf(config),agent:harnessOf(config),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==='issue') {
-    const action=positional[0];
+    const action=positional[0], sourceURL=flags.url || flags.github;
     if(action==='list') {
-      if(flags.source && !['factory','github'].includes(flags.source))throw new Error('Choose --source factory or github');
-      console.log(JSON.stringify(flags.source==='github' ? await listIssues(configAt(state).repo,Number(flags.page || 1)) : (await api(state,'/api/v1/status')).jobs,null,2));
-    } else if(action==='templates') console.log(JSON.stringify(await readTemplates(configAt(state).repo),null,2));
+      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));
+    } 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));
+    else if(action==='recover') {
+      if(!/^[A-Za-z0-9_-]{16,100}$/.test(flags.key || ''))throw new Error('Use --key with the saved request ID');
+      console.log(JSON.stringify(await api(state,`/api/v1/issue-submissions/${flags.key}/recover`,{}),null,2));
+    }
     else if(action==='preview') {
-      if(!flags.github)throw new Error('Use --github ISSUE_URL');
-      console.log(JSON.stringify(await readIssue(configAt(state).repo,flags.github),null,2));
+      if(!sourceURL)throw new Error('Use --url ISSUE_URL');
+      console.log(JSON.stringify(await api(state,'/api/v1/issues/preview',{url:sourceURL}),null,2));
     } else if(action==='recommend') {
-      if(Boolean(flags.github)===Boolean(flags.file))throw new Error('Choose --file brief.md or --github ISSUE_URL');
-      console.log(JSON.stringify(flags.github ? (await readIssue(configAt(state).repo,flags.github)).recommendation : recommendWork({spec:readFileSync(resolve(flags.file),'utf8')}),null,2));
+      if(Boolean(sourceURL)===Boolean(flags.file))throw new Error('Choose --file brief.md or --url ISSUE_URL');
+      console.log(JSON.stringify(sourceURL ? (await api(state,'/api/v1/issues/preview',{url:sourceURL})).recommendation : recommendWork({spec:readFileSync(resolve(flags.file),'utf8')}),null,2));
     } else if(action==='draft') {
       if(!flags.file||!flags.template||!flags.sha)throw new Error('Use --template NAME --sha SHA --file answers.json with {title, answers}');
-      console.log(JSON.stringify(await draftFromTemplate(configAt(state).repo,{...json(resolve(flags.file)),template:flags.template,sha:flags.sha}),null,2));
+      console.log(JSON.stringify(await api(state,'/api/v1/issue-templates/draft',{...json(resolve(flags.file)),template:flags.template,sha:flags.sha}),null,2));
     } else if(action==='create') {
+      if(flags.workflow||sourceURL)throw new Error('issue create publishes a new repository issue. Use issue start for execution.');
+      if(!flags.key)throw new Error('Provide a stable --key for safe retry and recovery.');
+      if(Boolean(flags.draft)===Boolean(flags.file))throw new Error('Choose --draft draft.json or --file brief.md --title TITLE');
+      const draft=flags.draft ? json(resolve(flags.draft)) : {title:flags.title,spec:readFileSync(resolve(flags.file),'utf8'),labels:[]};
+      const connection=await api(state,'/api/v1/issue-connection');
+      if(!connection.supported)throw new Error('No issue provider is available. Use issue start for a local brief.');
+      console.log(JSON.stringify(await api(state,'/api/v1/issues',{title:flags.title || draft.title,spec:draft.spec,labels:draft.labels || [],request_id:flags.key,repository:connection.repository,actor:connection.actor}),null,2));
+    } 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,flags.github,flags.draft].filter(Boolean).length!==1)throw new Error('Choose --file brief.md, --draft draft.json or --github ISSUE_URL');
+      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(flags.github) { const issue=await readIssue(configAt(state).repo,flags.github);input={title:issue.title,spec:issue.spec,source_url:issue.url}; }
+      if(sourceURL) { const issue=await api(state,'/api/v1/issues/preview',{url:sourceURL});input={title:issue.title,spec:issue.spec,source_url:issue.url}; }
       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(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 || ''}),null,2));
-    } else throw new Error('Use issue list|templates|preview|recommend|draft|create; see help');
+    } 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));
   } else if(command==='recommend') {
@@ -248,13 +261,17 @@ 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 github] [--page N]  List local Factory issues or open GitHub issues
+  issue list [--source remote] [--page N]  List local executions or open repository issues
   issue templates                         Read this repository's issue forms and contact links
-  issue preview --github URL              Preview one GitHub issue without starting work
-  issue recommend --file brief.md | --github URL
+  issue preview --url URL              Preview one repository issue without starting work
+  issue recommend --file brief.md | --url URL
   issue draft --template NAME --sha SHA --file answers.json
                                           Validate {title,answers}; output a local draft JSON
-  issue create --draft draft.json | --github URL | --file brief.md --title TITLE
+  issue create --draft draft.json | --file brief.md --title TITLE --key REQUEST_ID
+                                          Create a repository issue; does not execute work
+  issue connection | submissions          Inspect provider identity or durable creation receipts
+  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 [--model MODEL]
                                           Create a local issue and start work; no GitHub write
   issues [--page N]                       Browse open project issues, with next_page for more

package/docs/concepts.md

@@ -12,14 +12,16 @@ The CLI `definition` command and dashboard Definition page read that same catalo
 | Agent | Responsibility and instructions | Implement, Review, Investigate; one shared harness/model profile |
 | Skill | Reusable instructions | Six job skills; separate operator Factory Foundation |
 | Workflow | Ordered steps and gates | Software: Implement → Check → Review → Accept; Defence: Investigate |
-| Local issue | Bounded work request | Created from a form, brief or GitHub source; stored as a job with retained run attempts |
-| Automation | Trigger, filters and target | Planned; work starts manually |
+| Issue | Bounded work request | Remote issue lives in its provider; a local brief needs no remote issue |
+| Execution | Admitted work and its attempts | Stored in the private SQLite queue with source link and evidence |
+| Provider | Repository issue integration | GitHub adapter first; unknown remotes retain local execution |
+| Automation | External schedule and agent context | Owned by the selected harness; calls Factory CLI/API, no Factory cron |
 | Definition | Effective roles, workflows, skills and settings | Installed method plus private factory.json; read-only catalog |
 
-Inbox contains admitted local issues, not an automatically imported GitHub backlog.
-New issue previews a local draft; Create & start admits execution. GitHub issues
-and templates are source material: nothing is posted back to GitHub. Drafts stay
-in the open form until creation; there is no persistent unstarted backlog yet.
+Inbox contains execution history, not a copied remote issue backlog. New issue
+can create a repository issue without execution; Start work admits execution
+separately. The provider owns issue content/state; SQLite owns queue/attempts and
+creation receipts for recovery. An unfinished local form is not a saved backlog.
 An agent role is neither a machine nor a skill. Check is deterministic, and
 Accept is an operator gate. Triage/specification precede admission; evaluation
 is separately scoped work, not an automatic hidden agent phase.
@@ -51,7 +53,10 @@ Execution IDs (`build`, `verify`, `handoff`, `job_*`, `run_*`) are stable wire a
 evidence identifiers. Human labels explain them without rewriting stored jobs.
 Compatibility is handled at these boundaries; there is one active implementation.
 
-CLI `issue` groups list, templates, preview, draft, recommend and create. The
+CLI `issue` groups list, connection, templates, preview, draft, recommend, create,
+start, submissions and recover. Since 0.6, `issue create` only publishes; migrate
+0.5.1 execution callers to `issue start`. The
 legacy `run`, `issues` (GitHub list) and `recommend` commands remain compatible.
 Task/job field names and `/api/v1/jobs` are stable wire/storage identifiers for
-these same local issues; this adds no parallel scheduler or issue database.
+these same local issues; the extra SQLite receipt table is external-write bookkeeping, not an issue mirror
+or another scheduler.

package/docs/integrations.md

@@ -0,0 +1,67 @@
+# Repository and issue providers
+
+Git source, issue tracking, execution and scheduling have different owners.
+A Git remote does not guarantee an issue API, GitHub-compatible forms or a
+particular CI system. Factory clones local Git source independently of the
+optional issue integration.
+
+| State | Owner |
+| --- | --- |
+| Source, branches, remote issues and their metadata | Selected repository/issue service |
+| Queue, attempts, checks, approvals and evidence | Factory controller's private SQLite/files |
+| External creation intent, correlation and receipt | SQLite; recovery bookkeeping, not an issue-backlog mirror |
+| Schedules and scheduled-agent context | Selected harness, where it supports automations |
+| Forms and actions | Dashboard and CLI over the same controller API |
+
+## Current selection
+
+`factory/issue-provider.mjs` selects an adapter from the configured Git origin.
+Only public github.com origins select the implemented GitHub adapter. Its own
+module owns GitHub API paths, host authentication, issue formats and recovery.
+Unknown/self-hosted remotes, GitHub Enterprise, Forgejo/Gitea, GitLab and Cursor
+Origin are **not implemented adapters**. They expose no remote-issue capability;
+local brief execution and the method remain usable. Factory never sends GitHub
+credentials to a guessed host or assumes a mirrored repo's original host.
+
+The adapter contract supplies provider identity and explicit capabilities,
+connection/acting identity, paged list, preview, templates/draft, publish and
+read-only recovery. The generic submission store binds a request key to provider,
+repository, identity and content before publication. Another provider can supply
+these operations without changing the queue, controller routes or creation form.
+Unsupported capabilities must fail visibly, not invent a compatible endpoint.
+A non-GitHub test adapter exercises this boundary; it is not a shipped integration.
+
+A future adapter must qualify its actual authentication, template/label model,
+error behavior and ambiguous-write recovery. Add it at this boundary, with
+matching CLI/API/UI support. Do not build a plugin loader, generalized OAuth
+service or second database merely to reserve future extension points. Selecting
+an issue tracker independently of the Git host remains a deliberate future
+configuration extension, not an inferred mapping.
+
+## GitHub adapter
+
+The controller uses its existing `gh` identity. `issue connection` and the creation
+form show the destination and acting user. GitHub enforces Issues write access;
+label application needs suitable repository access. Browser GitHub login is not
+required. Missing/revoked access produces a visible failure without execution.
+No access token, browser cookie or host credential is passed to a job.
+
+Creation sends the selected title/body/labels plus an opaque hidden correlation
+marker. A lost response is recovered by bounded authenticated reads of issues
+created by the original actor; no automatic second POST occurs. If the marker
+was removed, the provider is unavailable or the bounded search cannot find it,
+manual inspection is required. A receipt never claims current issue status;
+read the provider again for current metadata. The published issue is the backlog.
+
+Creation is separate from `issue start`. A remote issue never grants execution,
+merge, deployment or production access. External harness automations use the same
+explicit admission API and remain responsible for their own schedule/deduplication.
+
+The managed updater’s OS timer maintains installed software; it is not a work-admission scheduler.
+
+The dashboard derives its request key from the reviewed destination, identity,
+title, body and labels. Reopening or reloading the same submission therefore
+reuses its receipt, including a successful result whose browser response was
+lost. No unsent draft is persisted by this mechanism. Identical browser content
+returns the existing issue in that controller state; an intentional separate
+copy requires a distinct CLI request key.

package/docs/interfaces.md

@@ -10,16 +10,17 @@ 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 |
-| Create local issue | `issue create --file --title`, `--draft` or `--github`, explicit `--workflow`, optional `--model` | `POST /api/v1/jobs` | New issue → review → Create & start | Persistent unstarted drafts and typed incident intake remain separate |
-| Browse/import GitHub issues | `issue list --source github [--page N]`, `issue preview --github URL` via operator `gh` | 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 | Stronger issue/job identity, issue creation and qualified triggers remain; no implicit polling |
+| 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 |
+| 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 `--github` | 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 |
+| 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 |
 | Cancel/retry/approve | Commands | Job action endpoints with current run ID | Task controls | JSON action results and consistent needs-attention outcomes |
 | Request changes | `revise --file` | `request_changes` action | Feedback form | JSON action result; retain shared stale-action guards |
 | Remove a stopped task | No command | `DELETE /api/v1/jobs/:id` | Remove action | Add CLI; keep existing recoverability/history semantics |
 | Evidence list/read/download | No command | Authenticated artifact routes | Files/preview/download | Add CLI with matching access and size/path rules |
 | Roles, workflows and packaged skills | `definition`, `agents`, `skills` JSON (also while stopped) | `GET /api/v1/definitions` | Agents, Skills and Definition | Shared read-only catalog; future editing must preserve common policy/gates |
-| Project repository links | Validated links in `status` | `project_links` from configured Git origin | View repo / optional GitHub issue link | Links only; no issue synchronization or creation API |
+| Project repository links | Validated links in `status` | `project_links` from configured Git origin | View repo / optional GitHub issue link | Provider creates/issues reads are separate from Git source links |
 | Recorded token usage | Per-attempt `usage` and `token_usage` in `status` | Same status records | Analytics, task rows, metadata/history | No billing estimate; partial/unknown coverage stays explicit |
 | Analytics/filtering | Raw status available | Source queue records | Derived views | Expose equivalent queries/summaries without inventing usage data |
 | Scoped incident admission | `incident --file` validates/deduplicates private evidence | No equivalent typed intake endpoint | Generic Defence form is not equivalent admission | Common typed intake, gaps and deduplication before execution |
@@ -46,8 +47,10 @@ authority. Headless use and GUI use must ultimately reach the same outcomes;
 intermediate releases must explicitly retain their unimplemented rows here.
 
 Infrastructure exposes detected host capacity and the local worker through
-`infrastructure` and the same status API. `automations` returns the supported
-empty list; the UI explicitly states that automatic admission is unavailable.
+`infrastructure` and the same status API. `automations` returns the harness
+ownership contract; the UI explains that external schedules are not discovered.
+Factory has no cron module. The v1 `automations: []` field remains a compatibility
+view; `automation_control` owns the current semantics.
 `foundation` prints the packaged operator skill without configuring anything;
 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

package/docs/quickstart.md

@@ -98,8 +98,7 @@ 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. It does not publish a GitHub issue; Create &
-start queues local work. See [intake and CLI examples](workflows.md). The task detail provides previous/next within the filtered list, copy
+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
 link and close (Escape). Closing preserves the list's filters and position.
 
 If the interface looks unexpectedly small, check the browser zoom. The design

package/docs/recovery.md

@@ -99,3 +99,10 @@ 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.
+
+## Unconfirmed repository issue creation
+
+Use `issue submissions` and `issue recover --key REQUEST_ID` against the same
+controller state. Recovery reads the original provider using the original
+identity; it does not publish again. Do not use a new request key to retry an
+uncertain write. See [provider ownership and recovery limits](integrations.md).

package/docs/setup.md

@@ -103,7 +103,7 @@ qualification record; stop this controller unless it is the selected dashboard.
 ## 4. Prepare each application and inference profile
 
 Preserve existing commits, branches, uncommitted work and licenses before moving
-anything. Verify the canonical GitHub origin and main branch's tracking target;
+anything. Verify the canonical Git 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.
 
@@ -115,7 +115,7 @@ Before admitting development work, establish:
 - Reproducible toolchain/dependency pins and an actual build/check command.
 - A compatible job image for native libraries, browser/mobile tools or custom
   model adapters; the standard image does not supply every application stack.
-- Meaningful checks in GitHub CI on the selected revision, plus the intended
+- Meaningful checks in the selected CI on the selected revision, plus the intended
   review/branch policy. Record plan/access limits if enforcement is unavailable.
 - Applicable application instructions, design/scope, resource limits, secret
   references and a clear delivery destination. Keep unfinished WIP separate

package/docs/workflows.md

@@ -31,7 +31,7 @@ The list excludes pull requests, loads 50 GitHub records per page and offers
 **Load more**; search filters the loaded issues by title, number or label. GitHub
 reads use the controller's existing access, with retry on failure.
 
-Review the instructions and suggested work type before **Create & start**. The shared,
+Review the instructions and suggested work type before explicitly starting work. The shared,
 deterministic suggestion prioritizes `track:software` and `track:security` (also
 `track:defence`/`track:defense`) labels. Without a track label, explicit incident
 investigation wording suggests Defence; otherwise Software is the default.
@@ -48,40 +48,56 @@ visible with a GitHub link instead of silently dropping fields. Contact links
 preserve the project's private security reporting route. Template Markdown is
 shown as literal text, never executed or rendered as raw HTML.
 
-This creates a **local Factory issue**, not a GitHub issue. GitHub assignees,
-projects and write permissions are not applied. Blank local issues remain
-available without GitHub access; `blank_issues_enabled` governs GitHub's chooser,
-not Factory's local admission. Drafts are not saved as a persistent backlog.
-The reader bounds each template to 100 KB and each chooser to 20 templates;
-failures are explicit. Labels color the issue list and inform suggestions;
-they cannot grant authority or enable automatic execution.
+On a supported repository, **Create issue on GitHub** writes the title, description
+and template labels to that repository using the displayed host identity. It
+returns the real issue number/link and **does not start execution**. Select
+**Start work** separately, or choose the issue later from the repository list.
+Choose **Local execution only** to submit a brief without publishing it. A local
+brief is an execution request; an unfinished form is not a persistent backlog.
+Use the private security contact route for sensitive reports, never a public issue.
 
-CLI equivalents:
+The controller records a durable creation receipt before calling the provider.
+After a timeout, **Check submission** or `issue recover` looks for the original
+result; it never blindly repeats a write. Reuse the same request key on CLI retries.
+Changed content/identity with that key is rejected. An unresolved result stays
+unconfirmed rather than risking a duplicate. Confirmed missing labels are shown;
+GitHub projects, assignees and arbitrary issue form extensions are not applied.
+
+CLI equivalents (the selected controller must be running):
 
 ```sh
-software-defence-factory issue list --state PATH
-software-defence-factory issue list --source github --state PATH --page 1
-software-defence-factory issue preview --github URL --state PATH
+software-defence-factory issue connection --state PATH
+software-defence-factory issue list --source remote --state PATH --page 1
 software-defence-factory issue templates --state PATH
 software-defence-factory issue draft --state PATH --template bug-report.yml --sha TEMPLATE_SHA --file answers.json > draft.json
-software-defence-factory issue create --state PATH --draft draft.json --workflow software
-software-defence-factory issue recommend --file brief.md
-software-defence-factory issue create --state PATH --file brief.md --title "Investigate supplied evidence" --workflow defence
-software-defence-factory issue create --state PATH --github URL --workflow software
+software-defence-factory issue create --state PATH --draft draft.json --key release-board-fix-01
+software-defence-factory issue submissions --state PATH
+software-defence-factory issue recover --state PATH --key release-board-fix-01
+# Explicit execution, independent of creation:
+software-defence-factory issue start --state PATH --url URL --workflow software
+software-defence-factory issue start --state PATH --file brief.md --title "Investigate supplied evidence" --workflow defence
 ```
 
 `answers.json` contains `{"title":"Fix the board","answers":{"problem":"..."}}`;
 keys match `fields[].id` in `issue templates`. Multi-select/checkbox answers are
-arrays of exact option labels. These reads and compilation do not create work.
-Only **Create & start** or `issue create` queues execution. It requires an
-explicit CLI work type; the old `run` command retains its Software default for
-compatibility. Private validated incident intake remains `incident --file`,
-distinct from a generic Defence brief or issue.
-
-View repo opens GitHub in a new tab, where the browser's own login applies.
-Import uses the controller host's `gh` identity; it does not borrow browser
-credentials. Import previews neither enable automatic triggers nor grant an
-issue author more access.
+arrays of exact option labels. `issue create` now publishes only; migrate 0.5.1
+execution scripts to `issue start`. Legacy `run` remains compatible. Typed private
+incident admission remains `incident --file`, distinct from a generic Defence brief.
+`--source github` remains an alias for repository listing; `--github URL` remains a compatibility alias for `--url URL`.
+
+Provider selection and unknown-host behavior are documented in [integrations](integrations.md).
+View repo uses the browser's own login. Factory's provider uses the controller
+host identity; neither shares credentials with the browser or job containers.
+
+## Scheduled work
+
+Configure schedules in the selected harness, where supported (for example Codex
+Automations). The scheduled agent calls Factory CLI/API with explicitly selected
+scope. Factory owns execution, checks and acceptance, not the external schedule.
+There is no Factory cron module, issue watcher or silently enabled automation.
+The Automations view identifies this owner; it does not claim to discover external
+schedules. Before enabling one, test its host availability, access, duplicate
+handling, resource limits and stop behavior. No schedule is created by onboarding.
 
 ## Change the definition
 

package/factory/definition.mjs

@@ -34,7 +34,7 @@ export function factoryDefinition(config) {
       phase, title: info.title, responsibility: info.description, harness, model: config.model || null, skills: info.skills,
     })),
     operator_skills: [foundationSkill()],
-    automations: { supported: false, items: [] },
+    automations: { owner: 'harness', harness, managed_by_factory: false, discovery: 'unavailable', items: null },
     commands: Object.entries(phaseInfo).map(([name, info]) => ({ name, ...info, prompt: info.description,
       executor: info.owner === 'agent' ? harnessOf(config) : 'factory', timeout: `${config.timeoutSeconds}s` })),
     skills,

package/factory/issue-provider.mjs

@@ -0,0 +1,24 @@
+import { execFileSync } from 'node:child_process';
+import { githubIssueProvider } from './providers/github.mjs';
+import { readProjectLinks } from './project-links.mjs';
+import { QueueError } from './queue.mjs';
+
+// Selection is local and capability-based. Unknown hosts never receive a GitHub
+// token or a guessed API request. Git checkout/execution does not need an adapter.
+export function issueProvider(repo) {
+  if (readProjectLinks(repo)) return githubIssueProvider(repo);
+  let host = null;
+  try {
+    const remote = execFileSync('git', ['-c', 'core.fsmonitor=false', '-C', repo, 'config', '--local', '--get', 'remote.origin.url'], { encoding:'utf8', timeout:2000, maxBuffer:4096, stdio:['ignore','pipe','ignore'], env:{...process.env,GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:'/dev/null'} }).trim();
+    if (/^(https?|ssh):\/\//.test(remote)) host = new URL(remote).hostname;
+    else host = remote.match(/^(?:[^@\s]+@)?([a-zA-Z0-9.-]+):[^/]/)?.[1] || null;
+    if (!/^[a-zA-Z0-9.-]+$/.test(host || '')) host = null;
+  } catch { /* No recognizable network origin; local execution remains available. */ }
+  const unavailable = async () => { throw new QueueError('This repository has no supported issue provider. Use a local brief; no remote issue will be created.', 400); };
+  return { id:'unsupported', label:'Repository host', repository:null, host, supported:false,
+    capabilities:{issues:false,templates:false,create:false},
+    context:unavailable, list:unavailable, preview:unavailable, templates:unavailable, draft:unavailable, publish:unavailable, recover:unavailable };
+}
+export function providerInfo(provider) {
+  return {id:provider.id,label:provider.label,repository:provider.repository,host:provider.host || null,supported:provider.supported,capabilities:provider.capabilities};
+}

package/factory/issue-submissions.mjs

@@ -0,0 +1,65 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { QueueError } from './queue.mjs';
+const keyPattern = /^[A-Za-z0-9_-]{16,100}$/;
+const fingerprint = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+
+// Receipts share the controller database and maintenance lock. They are not jobs
+// and cannot schedule execution. A pending write is never blindly repeated.
+export class IssueSubmissions {
+  constructor(queue, provider) {
+    this.queue = queue; this.provider = provider;
+    queue.db.exec('CREATE TABLE IF NOT EXISTS issue_submissions(id TEXT PRIMARY KEY, data TEXT NOT NULL)');
+  }
+  get(key) {
+    if (!keyPattern.test(key || '')) throw new QueueError('Provide a stable request key of 16–100 letters, digits, hyphens or underscores.', 400);
+    const row = this.queue.db.prepare('SELECT data FROM issue_submissions WHERE id=?').get(key);
+    return row && JSON.parse(row.data);
+  }
+  save(record) { this.queue.db.prepare('INSERT INTO issue_submissions VALUES (?,?) ON CONFLICT(id) DO UPDATE SET data=excluded.data').run(record.request_id, JSON.stringify(record)); return this.present(record); }
+  present(record) {
+    return { request_id: record.request_id, state: record.state, provider: record.provider, repository: record.repository, actor: record.actor,
+      title: record.payload.title, created_at: record.created_at, issue: record.issue || null, error: record.error || null };
+  }
+  list() { return this.queue.db.prepare('SELECT data FROM issue_submissions ORDER BY rowid DESC LIMIT 50').all().map(row => this.present(JSON.parse(row.data))); }
+  create(input) { return this.queue.exclusive(`issue-submission:${input.request_id}`, () => this.publish(input)); }
+  async publish(input) {
+    const existing = this.get(input.request_id);
+    if (typeof input.title !== 'string' || !input.title.trim() || input.title.length > 160 || typeof input.spec !== 'string' || !input.spec.trim() || Buffer.byteLength(input.spec) > 60000) throw new QueueError('Provide a title under 161 characters and a description under 60 KB.', 400);
+    if (!Array.isArray(input.labels) || input.labels.length > 50 || input.labels.some(label => typeof label !== 'string' || !label.trim() || label.length > 100)) throw new QueueError('Provide up to 50 valid issue labels.', 400);
+    const payload = { title: input.title.trim(), body: input.spec.trim(), labels: [...new Set(input.labels)].sort() };
+    const context = await this.provider.context();
+    if (input.repository !== context.repository || input.actor !== context.actor) throw new QueueError('Repository destination or identity changed. Review the connection before creating.', 409);
+    const hash = fingerprint({ provider: this.provider.id, repository: context.repository, actor_id: context.actor_id, payload });
+    if (existing) {
+      if (existing.hash !== hash) throw new QueueError('This request key already belongs to different content or identity. Inspect its receipt before creating another issue.', 409);
+      if (existing.state === 'created') return this.present(existing);
+      if (existing.state !== 'rejected') return this.reconcile(existing);
+    }
+    if (!context.available) throw new QueueError('This repository is archived or has issues disabled.', 400);
+    if (payload.labels.length && !context.labels_supported) throw new QueueError('This identity cannot apply the selected labels. Use a repository identity with label access.', 403);
+    const record = existing || { request_id: input.request_id, provider: this.provider.id, hash, repository: context.repository, actor: context.actor, actor_id: context.actor_id,
+      payload, correlation_id: randomUUID(), created_at: new Date().toISOString() };
+    record.state = 'pending'; record.error = null; this.save(record);
+    try {
+      record.issue = await this.provider.publish(record);
+      record.state = 'created'; return this.save(record);
+    } catch (error) {
+      record.state = [400,401,403,404,410,422,429].includes(error.httpStatus) ? 'rejected' : 'uncertain';
+      record.error = record.state === 'rejected' ? 'Repository provider rejected creation. Check Issues write access and repository labels, then retry the same request.' : 'Creation may have succeeded. Check this saved submission; do not create another issue to retry.';
+      this.save(record);
+      throw new QueueError(`${record.error} Request: ${record.request_id}`, 409);
+    }
+  }
+  recover(key) { return this.queue.exclusive(`issue-submission:${key}`, async () => {
+    const record = this.get(key); if (!record) throw new QueueError('Submission not found.', 404);
+    const context = await this.provider.context();
+    if (record.provider !== this.provider.id || record.repository !== context.repository || record.actor_id !== context.actor_id) throw new QueueError('Restore the original repository and provider identity before recovering this submission.', 409);
+    if (record.state === 'created' || record.state === 'rejected') return this.present(record);
+    return this.reconcile(record);
+  }); }
+  async reconcile(record) {
+    const issue = await this.provider.recover(record);
+    record.issue = issue; record.state = 'created'; record.error = null;
+    return this.save(record);
+  }
+}

package/factory/providers/github.mjs

@@ -0,0 +1,77 @@
+import { execFile } from 'node:child_process';
+import { githubRead, listIssues, readIssue } from '../issue-intake.mjs';
+import { readTemplates, draftFromTemplate } from '../issue-templates.mjs';
+import { readProjectLinks } from '../project-links.mjs';
+import { QueueError } from '../queue.mjs';
+const marker = record => `<!-- factory-issue:${record.correlation_id} -->`;
+const apiArgs = path => ['api', '--hostname', 'github.com', path];
+export function githubWrite(path, payload) {
+  return new Promise((resolve, reject) => {
+    const child = execFile('gh', [...apiArgs(path), '--method', 'POST', '--input', '-'], {
+      timeout: 15000, maxBuffer: 1024 * 1024, encoding: 'utf8',
+      env: { ...process.env, GH_PROMPT_DISABLED: '1', GH_PAGER: 'cat' },
+    }, (cause, stdout, stderr) => {
+      if (cause) {
+        const error = new Error('GitHub did not confirm issue creation.');
+        error.httpStatus = Number(stderr?.match(/\(HTTP (\d+)\)/)?.[1]) || undefined;
+        reject(error);
+      } else {
+        try { resolve(JSON.parse(stdout)); } catch { reject(new Error('GitHub returned an unreadable creation result.')); }
+      }
+    });
+    child.stdin.on('error', () => {}); // Process completion reports a broken pipe without exposing request content.
+    child.stdin.end(JSON.stringify(payload));
+  });
+}
+
+function confirm(record, issue) {
+    if (issue?.pull_request || !Number.isSafeInteger(issue?.number) || issue.number < 1 || issue.html_url !== `${record.repository}/issues/${issue.number}` || issue.user?.id !== record.actor_id || !issue.body?.includes(marker(record))) throw new Error('Unexpected GitHub creation result.');
+    const actualLabels = (issue.labels || []).map(label => label.name);
+    const result = { number: issue.number, url: issue.html_url, title: issue.title, labels: actualLabels,
+      missing_labels: record.payload.labels.filter(label => !actualLabels.includes(label)) };
+    return result;
+  }
+
+export function githubIssueProvider(repo, { read = githubRead, write = githubWrite } = {}) {
+  const repository = readProjectLinks(repo)?.repository;
+  return {
+    id: 'github', label: 'GitHub', repository, supported: true,
+    capabilities: { issues: true, templates: true, create: true },
+    list: page => listIssues(repo, page, read),
+    preview: url => readIssue(repo, url, value => read(['issue', 'view', value, '--json', 'title,body,url,labels'])),
+    templates: () => readTemplates(repo, read),
+    draft: input => draftFromTemplate(repo, input, read),
+    async context() {
+    const repository = readProjectLinks(repo)?.repository;
+    if (!repository) throw new QueueError('Configure a GitHub origin for this project.', 400);
+    const slug = repository.slice('https://github.com/'.length);
+    let user, project;
+    try { [user, project] = await Promise.all([read(apiArgs('user')), read(apiArgs(`repos/${slug}`))]); }
+    catch { throw new QueueError('GitHub access unavailable. Check gh authentication on the controller host.', 400); }
+    if (!Number.isSafeInteger(user?.id) || !/^[A-Za-z0-9-]+$/.test(user?.login || '') || project?.full_name?.toLowerCase() !== slug.toLowerCase()) throw new QueueError('GitHub returned an unexpected identity or repository.', 400);
+    return { repository, actor: user.login, actor_id: user.id, available: !project.archived && project.has_issues === true,
+      labels_supported: Boolean(project.permissions?.push || project.permissions?.triage || project.permissions?.maintain || project.permissions?.admin),
+      permission: 'GitHub checks Issues write permission when creating. No credentials are sent to the browser or jobs.' };
+  },
+    async publish(record) {
+      const slug = record.repository.slice('https://github.com/'.length);
+      const issue = await write(`repos/${slug}/issues`, { ...record.payload, body: `${record.payload.body}\n\n${marker(record)}` });
+      return confirm(record, issue);
+    },
+    async recover(record) {
+    const slug = record.repository.slice('https://github.com/'.length);
+    const since = new Date(Date.parse(record.created_at) - 60000).toISOString();
+    try {
+      for (let page = 1; page <= 5; page++) {
+        const result = await read(apiArgs(`repos/${slug}/issues?state=all&creator=${encodeURIComponent(record.actor)}&since=${encodeURIComponent(since)}&sort=created&direction=desc&per_page=100&page=${page}`));
+        if (!Array.isArray(result)) throw new Error('Unexpected issue listing');
+        const matches = result.filter(issue => !issue.pull_request && issue.user?.id === record.actor_id && issue.body?.includes(marker(record)));
+        if (matches.length > 1) throw new Error('Multiple matching issues');
+        if (matches.length === 1) return confirm(record, matches[0]);
+        if (result.length < 100) break;
+      }
+    } catch { throw new QueueError(`Could not reconcile submission ${record.request_id}. No write was retried. Check GitHub access and retry recovery.`, 409); }
+    throw new QueueError(`Submission ${record.request_id} is still unconfirmed. No write was retried. Inspect GitHub before creating another issue.`, 409);
+  }
+  };
+}