software-defence-factory 0.5.0 → 0.6.0

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

@@ -1,4 +1,4 @@
-name: Factory task
+name: Factory issue
 description: Describe a business outcome and observable acceptance criteria.
 title: "[Factory] "
 labels: ["factory:triage"]

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 task opens a local brief; importing a GitHub issue is optional. 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

@@ -6,7 +6,8 @@ import { spawn } from 'node:child_process';
 import { createServer } from 'node:net';
 import { ROOT, PINS, DEFAULT_STATE, configAt, save, json, run, stream, digest, api, sleep, stopContainers } from '../factory/lib.mjs';
 import { assertInstalledJobImage, installCustomJobImage, installStandardJobImage, inspectImageInstallation } from '../factory/image-install.mjs';
-import { readIssue } from '../factory/issue-intake.mjs';
+import { listIssues, 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';
 import { admitIncident } from '../factory/incident.mjs';
@@ -151,21 +152,70 @@ 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') {
     const config=configAt(state),dockerVersion=run('docker',['info','--format','{{.ServerVersion}}']),imageStatus=inspectImageInstallation(state,config);
     console.log(JSON.stringify({node:process.version,docker:dockerVersion,engineInstalled:imageStatus.installed,image:imageStatus.image,repo:config.repo,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], 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));
+    } 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(!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(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 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,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}; }
+      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|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') {
+    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')});
+    console.log(JSON.stringify(recommendation,null,2));
   } else if(command==='run') {
+    const workflow=flags.workflow || 'software';
+    if(!['software','defence'].includes(workflow))throw new Error('Choose --workflow software or defence');
     let spec;
     if(flags.issue) {
       spec=(await readIssue(configAt(state).repo,flags.issue)).spec;
     } else if(flags.file)spec=readFileSync(resolve(flags.file),'utf8');
     else throw new Error('Use --file task.md or --issue https://github.com/owner/repo/issues/123');
-    if(!configAt(state).check?.trim())throw new Error('Configure an app check before submitting software work');
-    console.log(JSON.stringify(await submit('software',spec)));
+    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)));
   } 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)));
@@ -211,7 +261,22 @@ 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)
-  run --file task.md | --issue URL         Submit one software vertical slice
+  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 --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 | --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
+  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
   incident --file incident.json            Submit a private, read-only incident draft
   approve JOB_ID | cancel JOB_ID           Review gate / stop this attempt
   retry JOB_ID                            Prove stop; retain old checkout and retry

package/docs/concepts.md

@@ -12,12 +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 |
-| Task | Bounded admitted work | A stored job with retained run attempts; not a GitHub issue |
-| 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 tasks, not an imported GitHub backlog. An issue is source
-material; importing it previews the scope and starting a task queues execution.
+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.
@@ -26,7 +30,7 @@ All job skills are available read-only. Role instructions identify relevant
 skills; per-role skill/access/harness profiles are not yet supported. Inference
 authentication, GitHub identity and SSH access are separate boundaries. Browser
 GitHub sign-in does not configure `gh` on the controller host, and host `gh` auth
-does not sign a browser in. Writing a local task needs neither a GitHub issue nor
+does not sign a browser in. Writing a blank local issue needs neither a GitHub issue nor
 browser GitHub login. Import uses the controller's configured-repository `gh`
 access. See [interface support](interfaces.md).
 
@@ -48,3 +52,11 @@ private so existing installations can upgrade without credential migration.
 Execution IDs (`build`, `verify`, `handoff`, `job_*`, `run_*`) are stable wire and
 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, 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; 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,14 +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 |
-| Submit software text | `run --file` | `POST /api/v1/jobs` | New task modal | Equivalent title/source/model options and validation |
-| Import a GitHub issue | `run --issue` via operator `gh` | Authenticated `POST /api/v1/issues/preview` using the same reader | Import, review and explicitly start | Backlog/listing, stronger issue/job identity and optional 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 `--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 |
@@ -44,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

@@ -88,7 +88,7 @@ No Docker socket, operator credentials or unrelated project caches are mounted.
 
 ## Read the project dashboard
 
-Tasks contains both Software delivery and Defence investigation. Select a
+Inbox contains both Software delivery and Defence investigation. Select a
 workflow to focus the list; workflow, requested-model, status-badge and text
 filters combine. Analytics offers the same workflow separation for recorded
 outcomes, duration and [token usage](usage.md). An issue link is a reference,
@@ -96,9 +96,9 @@ not an execution type. For validated, deduplicated private incident intake,
 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 and New issue appear only
-for a validated GitHub origin; they open GitHub and do not synchronize its
-backlog. The task detail provides previous/next within the filtered list, copy
+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
 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

@@ -24,16 +24,80 @@ kept outside those execution mounts.
 
 ## Start work
 
-Open **New task** in Inbox, write a bounded brief and start it. Alternatively,
-choose **From GitHub issue**, load an issue from the configured repository,
-review the imported scope and start it. Starting queues real work; creating an
-issue or setting a label does not. The CLI equivalent is `run --file task.md`
-or `run --issue URL`. Private validated incident intake uses `incident --file`.
-
-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.
+Open **New issue** in Inbox, choose a repository template (or **Blank issue**),
+complete the title and fields, then **Continue**. Or choose
+**From GitHub issues** and select an open issue from the configured repository.
+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 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.
+Conflicting labels request a choice. This is a simple editable suggestion, not a
+model assessment or permission to act. A security code fix can remain Software.
+Both sources support either type; Defence still produces a private draft.
+
+Repository templates are read from `.github/ISSUE_TEMPLATE` on the default
+branch through GitHub's API. Markdown templates and YAML markdown, input,
+textarea, dropdown (including multiple choices) and checkboxes are supported.
+Required fields/defaults are preserved; compilation checks the template SHA
+again and refuses a changed form. Unsupported forms (including uploads) stay
+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.
+
+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.
+
+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 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 --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. `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/intake.mjs

@@ -0,0 +1,15 @@
+// Suggestions never authorize execution or replace the operator's chosen scope.
+export function recommendWork({ spec, labels = [] }) {
+  if (typeof spec !== 'string' || !spec.trim() || Buffer.byteLength(spec) > 240000) throw new Error('Provide a brief between 1 and 240 KB.');
+  if (!Array.isArray(labels) || labels.length > 100 || labels.some(label => typeof label !== 'string' || label.length > 100)) throw new Error('Expected issue label names.');
+  const names = labels.map(label => label.toLowerCase());
+  const software = names.includes('track:software');
+  const defence = names.some(label => ['track:security', 'track:defence', 'track:defense'].includes(label));
+  if (software !== defence) return { workflow: defence ? 'defence' : 'software', basis: 'label', reason: `The issue is labelled for ${defence ? 'security investigation' : 'software delivery'}.` };
+  if (software && defence) return { workflow: 'software', basis: 'conflicting_labels', reason: 'Both tracks are labelled. Choose whether this task should deliver code or investigate evidence.' };
+  // Deliberately narrow: fixing a vulnerability or building security features is software work.
+  if (/\b(?:investigat(?:e|ion|ing)|triage|analys[ei][rs]?|analy[sz]e|undersøg|undersøge)\b[\s\S]{0,100}\b(?:incident|intrusion|breach|malware|compromise|suspicious|security logs|hændelse|angreb)\b/i.test(spec)) {
+    return { workflow: 'defence', basis: 'brief', reason: 'The brief describes investigating a security incident or supplied evidence.' };
+  }
+  return { workflow: 'software', basis: 'default', reason: 'Software is the default for changes to this project. Choose Defence for a scoped security investigation.' };
+}

package/factory/issue-intake.mjs

@@ -1,22 +1,49 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { readProjectLinks } from './project-links.mjs';
+import { recommendWork } from './intake.mjs';
 const exec = promisify(execFile);
 
+export async function githubRead(args) {
+  try {
+    const { stdout } = await exec('gh', args, {
+      encoding: 'utf8', timeout: 10000, maxBuffer: 8 * 1024 * 1024,
+      env: { ...process.env, GH_PROMPT_DISABLED: '1', GH_PAGER: 'cat' },
+    });
+    return JSON.parse(stdout);
+  } catch (cause) {
+    const error = new Error('Could not read GitHub repository data. Check GitHub CLI access on the controller host and try again.');
+    if (/\(HTTP 404\)/.test(cause.stderr || '')) error.status=404;
+    throw error;
+  }
+}
+
+function issueLabels(labels = []) {
+  if (!Array.isArray(labels) || labels.some(label => typeof label?.name !== 'string')) throw new Error('GitHub returned unexpected labels.');
+  return labels.map(label => ({name:label.name, color:/^[a-f0-9]{6}$/i.test(label.color || '') ? label.color.toLowerCase() : null}));
+}
+
+export async function listIssues(repo, page = 1, read = githubRead) {
+  if (!Number.isSafeInteger(page) || page < 1 || page > 10000) throw new Error('Issue page must be an integer between 1 and 10000.');
+  const repository = readProjectLinks(repo)?.repository;
+  if (!repository) throw new Error('This project has no configured GitHub origin.');
+  const slug = repository.slice('https://github.com/'.length);
+  const result = await read(['api', '--hostname', 'github.com', `repos/${slug}/issues?state=open&sort=created&direction=desc&per_page=50&page=${page}`, '-H', 'Accept: application/vnd.github+json']);
+  if (!Array.isArray(result) || result.length > 50) throw new Error('GitHub returned an unexpected issue list.');
+  const issues = result.filter(issue => !issue.pull_request).map(issue => {
+    validateIssueURL(repository, issue.html_url);
+    if (!Number.isSafeInteger(issue.number) || !issue.html_url.endsWith(`/issues/${issue.number}`) || typeof issue.title !== 'string' || !issue.title.trim()) throw new Error('GitHub returned an unexpected issue.');
+    return { number: issue.number, title: issue.title, url: issue.html_url, labels: issueLabels(issue.labels) };
+  });
+  return { repository, issues, next_page: result.length === 50 && page < 10000 ? page + 1 : null };
+}
+
 export function validateIssueURL(repoURL, value) {
   if (typeof value !== 'string' || value.length > 2048 || !/^https:\/\/github\.com\/[A-Za-z0-9-]+\/[A-Za-z0-9_.-]+\/issues\/[1-9][0-9]*$/.test(value)) throw new Error('Enter a GitHub issue URL without query parameters.');
   if (!repoURL || !value.toLowerCase().startsWith(`${repoURL.toLowerCase()}/issues/`)) throw new Error('Issue does not belong to this project’s configured GitHub origin.');
   return value;
 }
-export async function readIssue(repo, url, read = async url => {
-  try {
-    const { stdout } = await exec('gh', ['issue', 'view', url, '--json', 'title,body,url'], {
-      encoding: 'utf8', timeout: 10000, maxBuffer: 300000,
-      env: { ...process.env, GH_PROMPT_DISABLED: '1', GH_PAGER: 'cat' },
-    });
-    return JSON.parse(stdout);
-  } catch { throw new Error('Could not read the issue. Check the URL and GitHub CLI access on the controller host.'); }
-}) {
+export async function readIssue(repo, url, read = url => githubRead(['issue', 'view', url, '--json', 'title,body,url,labels'])) {
   const repoURL = readProjectLinks(repo)?.repository;
   validateIssueURL(repoURL, url);
   const issue = await read(url);
@@ -24,5 +51,6 @@ export async function readIssue(repo, url, read = async url => {
   if (issue.url.toLowerCase() !== url.toLowerCase() || typeof issue.title !== 'string' || !issue.title.trim() || typeof issue.body !== 'string') throw new Error('GitHub returned an unexpected issue.');
   const spec = `Issue: ${issue.url}\n${issue.title}\n\n${issue.body}`;
   if (Buffer.byteLength(spec) > 240000) throw new Error('Issue exceeds the 240 KB task limit. Use a bounded task file instead.');
-  return { title: issue.title, url: issue.url, body: issue.body, spec };
+  const labels = issueLabels(issue.labels);
+  return { title: issue.title, url: issue.url, body: issue.body, spec, labels, recommendation: recommendWork({ spec, labels: labels.map(label => label.name) }) };
 }

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};
+}