software-defence-factory 0.5.1 → 0.7.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';
@@ -15,6 +14,8 @@ import { admitIncident } from '../factory/incident.mjs';
 import { DEFAULT_DEMO_STATE } from '../factory/paths.mjs';
 import { bootstrap, registerInstallation, VERSION } from '../factory/updates.mjs';
 import { hasService, manageService, serviceDefinition, withServiceOperation, isManagedLaunch } from '../factory/services.mjs';
+import { runCandidateGit } from '../factory/git-environment.mjs';
+import { initializeDemoRepository } from '../factory/demo-fixture.mjs';
 
 try {
   const handled = await bootstrap(process.argv.slice(2));
@@ -33,18 +34,18 @@ let state = resolve(flags.state || DEFAULT_STATE);
 if(existsSync(state))state=realpathSync(state);
 const alive = pid => { try { process.kill(pid,0); return true; } catch(error) { if(error.code === 'ESRCH')return false; throw error; } };
 
-function init(repo, harness='codex', check='', port=7331) {
+function init(repo, harness='codex', check='', port=7331, sourceRef='HEAD') {
   repo=realpathSync(resolve(repo));
   if (existsSync(join(state,'factory.json'))) throw new Error('Already configured; edit the private factory.json explicitly or choose another --state');
   if ([repo,state,ROOT].some(p=>/[,\n\r]/.test(p))) throw new Error('Paths cannot contain commas or line breaks');
-  if (run('git',['-C',repo,'rev-parse','--show-toplevel']) !== repo) throw new Error('--repo must be the Git root');
-  run('git',['-C',repo,'rev-parse','HEAD']);
+  if (runCandidateGit(repo,'rev-parse','--show-toplevel') !== repo) throw new Error('--repo must be the Git root');
+  runCandidateGit(repo,'rev-parse','HEAD');
   const presets={codex:['codex','exec','--json','--ephemeral','--sandbox','danger-full-access','-'],pi:['pi','--mode','json','--print','--no-session','--no-extensions','--skill','/factory-skills'],mock:['node','/opt/factory/mock.mjs']};
   const argv=harness==='custom'?JSON.parse(flags['command-json'] || 'null'):presets[harness];
   if (!argv) throw new Error('Select codex, pi, mock or custom with --command-json');
   if (flags.model && ['codex','pi'].includes(harness)) argv.splice(harness==='codex'?argv.length-1:argv.length,0,'--model',flags.model);
   mkdirSync(state,{recursive:true,mode:0o700});state=realpathSync(state);chmodSync(state,0o700);
-  save(join(state,'factory.json'),{version:1,repo,harness,command:argv,check,port:Number(port),image:PINS.jobImage,network:harness==='mock'?'none':'bridge',timeoutSeconds:1800,memoryMiB:2048,model:flags.model || null,
+  save(join(state,'factory.json'),{version:1,repo,sourceRef,harness,command:argv,check,port:Number(port),image:PINS.jobImage,network:harness==='mock'?'none':'bridge',timeoutSeconds:1800,memoryMiB:2048,model:flags.model || null,
     scope:{project:'pilot',service:'app',environment:'test',owner:'operator'}});
   configAt(state);
   writeFileSync(join(state,'worker.token'),randomBytes(32).toString('hex')+'\n',{mode:0o600});
@@ -99,10 +100,10 @@ async function stop() {
   }
   stopContainers(state);console.log('Controller and its labelled containers stopped.');
 }
-async function submit(workflow,spec) {
+async function submit(workflow,spec,sourceRef=flags['source-ref']) {
   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});
+  return api(state,'/api/v1/jobs',{workflow,repository:'app',spec,title,...(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');
@@ -119,12 +120,12 @@ async function jobAction(action) {
   }
   // The controller validates the current run and owns reconciliation atomically.
   // A CLI-side stop after a stale snapshot could terminate a newer attempt.
-  await api(state,`/api/v1/jobs/${id}/${action}`,{run_id:current?.id,...(feedback===undefined?{}:{feedback})});
+  await api(state,`/api/v1/jobs/${id}/${action}`,{run_id:current?.id,...(feedback===undefined?{}:{feedback}),...(flags['source-ref']===undefined?{}:{source_ref:flags['source-ref']})});
   console.log(`${action}: ${id}`);
 }
 
 try {
-  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');init(flags.repo,flags.harness || flags.agent,flags.check,flags.port); }
+  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');init(flags.repo,flags.harness || flags.agent,flags.check,flags.port,flags['source-ref'] || 'HEAD'); }
   else if(command==='install')await withServiceOperation('install',install);
   else if(command==='up') { if(hasService(state))await manageService('controller','start',state);else await withServiceOperation('up',up); }
   else if(command==='stop') { if(hasService(state))await manageService('controller','stop',state);else await withServiceOperation('stop',stop); }
@@ -153,7 +154,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 +162,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');
+      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));
+    } 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') {
@@ -212,9 +227,7 @@ try {
     state=resolve(flags.state || DEFAULT_DEMO_STATE);
     const repo=join(state,'sample-app');
     if(!existsSync(join(state,'factory.json'))) {
-      mkdirSync(repo,{recursive:true,mode:0o700});run('git',['init','-b','main',repo]);
-      writeFileSync(join(repo,'value.txt'),'broken\n');run('git',['-C',repo,'add','value.txt']);
-      run('git',['-C',repo,'-c','user.name=Factory demo','-c','user.email=demo@localhost','commit','-m','Synthetic fixture']);
+      initializeDemoRepository(repo);
       init(repo,'mock',"test \"$(cat value.txt)\" = fixed",Number(flags.port || 7332));
     } else if(harnessOf(configAt(state))!=='mock')throw new Error('Demo requires a mock configuration');
     await withServiceOperation('demo startup',async()=>{await install();await up();});console.log(JSON.stringify(await submit('software','Synthetic installation qualification: fix value.txt. No inference is used.')));
@@ -230,7 +243,7 @@ try {
   kit --output NEW_DIRECTORY               Export the portable method without a runtime
   demo                                    Install and run a synthetic sample (no model key)
   qualify --state PATH                    Exercise recovery and isolation with a stopped demo job
-  init --repo PATH --harness codex|pi|custom --check "npm ci && npm test"
+  init --repo PATH --harness codex|pi|custom --check "npm ci && npm test" [--source-ref REF]
   install [--image LOCAL_REF]             Build the standard image, or select an existing local image
   doctor | up | status | stop              Inspect / operate your private installation
   foundation                              Read the operator setup skill; no installation required
@@ -248,22 +261,28 @@ 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
-               --workflow software|defence [--model MODEL]
+  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 [--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
   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
   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
-  revise JOB_ID --file feedback.md         New build/check/review after a stopped review
+  revise JOB_ID --file feedback.md [--source-ref REF]
+                                          New build/check/review; source stays pinned unless a new ref is explicit
   version                                 Show the active CLI version
   update | update --check                 Update the npm CLI / inspect the latest release
   update --auto on|off                    Control automatic daily CLI updates

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 |
@@ -31,7 +32,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 | Controlled-checkout workaround | Not implemented | Not implemented | #28, same recorded source in both interfaces |
+| 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 keep the recorded source unless a new ref is explicit; legacy source remains unknown |
 | Trusted PR handoff | Operator applies accepted patch | Not implemented | Not implemented | #29; credentials remain outside jobs |
 
 The current generic task form can name the Defence workflow; that is not a
@@ -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

@@ -23,12 +23,14 @@ 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" --state /private/state/my-app --port 7331
+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
 ```
 
-Verification commands receive `FACTORY_BASE_REVISION`, the resolved commit recorded as the candidate base. Diff-based checks should compare against this revision; the isolated checkout has no origin remote. The value comes from protected controller metadata, not the task text.
+`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. The CLI and dashboard show the requested ref and resolved SHA. Task text and reference links do not select a repository or ref.
+
+Verification commands receive `FACTORY_BASE_REVISION`, the resolved admission commit recorded as the candidate base. Diff-based checks should compare against this revision; the isolated checkout has no origin remote. The value comes from protected controller metadata, not the task text.
 
 Replace the check with the application's actual verification command. `init` does not edit the app, copy global skills or start work. It creates factory.json, worker.token and model.env with private permissions. Each installation has one repository and a distinct state path/port. `--harness pi` selects Pi; `--harness custom --command-json '["executable","argument"]'` selects an available command in the job image. The bundled image provides Node, Git, Codex and Pi. Other toolchains require an intentionally built compatible image; do not claim Rust/mobile/browser capabilities from this image alone.
 
@@ -38,14 +40,14 @@ A local model endpoint must be reachable from inside the job container. Host loo
 
 ```sh
 software-defence-factory up --state /private/state/my-app
-software-defence-factory run --file task.md --state /private/state/my-app
+software-defence-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.
 
 ## Review and handoff
 
-Inspect the task's Result, Files and History tabs. Build evidence includes candidate.json, change.patch and the implementation report. Checks and review identify their exact commit and policy hash. Approval revalidates both before writing accepted.json. Request changes creates a new implementation sequence while preserving earlier attempts.
+Inspect the task's Result, Files and History tabs. Task details show the requested source ref, resolved admission SHA and previous source commits when a new base was selected. Build evidence includes candidate.json, change.patch and the implementation report; handoff records its source SHA. Checks and review identify their exact candidate commit and policy hash. Approval revalidates both before writing accepted.json. Request changes preserves the recorded source by default and starts fresh checks/review; an explicit new source ref is retained as a deliberate base change.
 
 The source application is not changed and no branch, PR, merge or deployment is published automatically. A reviewed change.patch can be checked and applied with `git apply --check` and `git apply` on an appropriate branch at its recorded base revision; then follow the application's normal integrated checks and delivery policy.
 
@@ -98,8 +100,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

@@ -4,9 +4,10 @@ Use `status --state PATH` and the private supervisor.log to identify the active
 
 - A normal `stop` signals the controller, waits for the executor process group, removes its labelled containers and retains the database and artifacts.
 - An unconfirmed running attempt becomes `interrupted` on controller restart. It is never silently considered successful.
-- `retry JOB_ID` reconciles the previous process group and containers. A live or unknown writer blocks retry. For a new build/defence attempt, the prior checkout is retained as previous-checkout-*.
+- Admission resolves the configured source ref or an explicit `--source-ref` in the configured repository, records its identity/ref/SHA in private job metadata and retains its Git objects under that job. Build and retry restore from this retained revision; moving or deleting the source ref does not select a new commit.
+- `retry JOB_ID` verifies retained objects and reconciles the previous process group and containers. A missing/corrupt retained source, live writer or unknown process blocks retry. For a new build/defence attempt, the prior checkout is retained as previous-checkout-*.
 - A failed verification can retry the same unchanged candidate after the check environment is repaired. A changed candidate needs a fresh verification/review sequence.
-- A requested revision retains previous evidence and starts a new build from the source repository with the accumulated feedback. It does not reuse earlier approval.
+- A requested revision keeps the recorded source by default, retains previous evidence and starts a new build with accumulated feedback. Supplying a deliberate new `--source-ref` resolves and retains that base before the action; prior source metadata stays in history, and the new build gets fresh checks and review.
 - Removing a stopped task from the dashboard hides its queue record. Private artifacts and its deleted_at record remain on disk; this is not secure erasure.
 
 Do not remove active.json merely to unblock a job. Establish that its PID, process group and labelled containers are stopped. PID reuse or missing process identity requires operator investigation. Preserve logs and work before cleanup.
@@ -34,11 +35,14 @@ software-defence-factory revise JOB_ID --file /private/revision.md --state /priv
 
 Feedback must be nonempty and at most 4,000 characters. It is accumulated in the
 bounded job prompt. The controller checks the latest attempt and reconciles its
-processes before starting a new build from the configured source with that
+processes before starting a new build from the retained source commit with that
 feedback. The old checkout moves to `previous-checkout-*`; the old failed review
 and reports remain intact. Verification, review and operator approval are all
 required again. A stale or duplicate request cannot approve or restart a newer
-attempt. **Retry** only repeats the stopped phase and is suitable for a repaired
+attempt. To deliberately change the base, pass `--source-ref REF`; the controller
+resolves and retains it from the same configured repository before changing the
+job record. If the request cannot reconcile, its unlinked source copy is removed.
+**Retry** only repeats the stopped phase and is suitable for a repaired
 execution environment; retrying review cannot change the candidate.
 
 A crashed review without a validated verdict cannot request implementation
@@ -91,6 +95,22 @@ facts in a separate private incident note with evidence paths and unknowns; leav
 the original queue/evidence unchanged. Without that evidence, model/image facts
 cannot be reconstructed reliably.
 
+### Legacy source records
+
+Jobs admitted before source retention keep their historical candidate and review
+evidence without an invented admission-time SHA. A complete existing candidate
+can still pass the normal current candidate, policy, review and approval guards;
+the handoff labels its source **Not recorded (legacy/unknown)**. An unpinned
+queued job is blocked on controller restart, and an unpinned job cannot retry or
+request implementation changes. Submit a replacement job to capture the
+configured or explicit source ref before execution. Do not reconstruct proof
+from the current checkout, issue text or a later ref value.
+
+If a retained store is missing or corrupt, retry and revision stop with an
+explicit source error. Restore the private state backup containing that job's
+retained Git objects, or submit a replacement from a source ref that still
+resolves. The controller never substitutes the mutable configured checkout.
+
 ### Interrupted image selection or controller startup
 
 `installation.lock` serializes image changes with controller startup, including
@@ -99,3 +119,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