software-defence-factory 0.5.0 → 0.5.1

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. 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 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,9 @@ 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 { 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';
 import { admitIncident } from '../factory/incident.mjs';
@@ -158,14 +160,49 @@ try {
     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];
+    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));
+    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));
+    } 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));
+    } 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));
+    } else if(action==='create') {
+      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');
+      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}; }
+      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 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 +248,18 @@ 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 github] [--page N]  List local Factory issues or open GitHub 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 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]
+                                          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,14 @@ 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 |
+| 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 |
 | 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 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.
 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 +28,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 +50,8 @@ 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, templates, preview, draft, recommend and create. 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.

package/docs/interfaces.md

@@ -10,8 +10,10 @@ shell endpoint or a second scheduler.
 | Capability | CLI | Shared API | Dashboard | Remaining work |
 | --- | --- | --- | --- | --- |
 | Project/queue/attempt state | `status`, `inbox` JSON | `GET /api/v1/status` | Project, tasks, details/history | Stable versioned agent result/error contract |
-| 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 |
+| 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 |
+| 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 |
 | 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 |

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,10 @@ 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. 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
 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/workflows.md

@@ -24,11 +24,59 @@ 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`.
+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 **Create & start**. 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.
+
+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.
+
+CLI equivalents:
+
+```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 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
+```
+
+`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

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-templates.mjs

@@ -0,0 +1,136 @@
+import { parseDocument } from 'yaml';
+import { githubRead } from './issue-intake.mjs';
+import { readProjectLinks } from './project-links.mjs';
+import { recommendWork } from './intake.mjs';
+
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+const text = value => typeof value === 'string' ? value : '';
+const filename = name => typeof name === 'string' && /^[^/\\\x00-\x1f]{1,120}\.(?:md|ya?ml)$/i.test(name) && !/^config\.ya?ml$/i.test(name);
+function yaml(source) {
+  const doc = parseDocument(source, { schema:'core', uniqueKeys:true });
+  if (doc.errors.length || doc.warnings.length) throw new Error('Invalid or unsupported template YAML.');
+  return doc.toJS({ maxAliasCount:20 });
+}
+function names(value) {
+  const result = typeof value === 'string' ? value.split(',').map(s => s.trim()).filter(Boolean) : value || [];
+  if (!Array.isArray(result) || result.length > 100 || result.some(s => typeof s !== 'string' || s.length > 100)) throw new Error('Invalid template labels.');
+  return result;
+}
+export function parseTemplate(name, source, sha) {
+  if (!filename(name) || typeof source !== 'string' || Buffer.byteLength(source) > 100000) throw new Error('Template is unsupported or exceeds 100 KB.');
+  let data, fields;
+  if (/\.md$/i.test(name)) {
+    const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/);
+    if (!match) throw new Error('Markdown template needs YAML front matter.');
+    data = yaml(match[1]);
+    fields = [{id:'body',type:'textarea',label:'Description',description:'Complete the sections from the repository template.',value:match[2].trim(),required:true}];
+  } else {
+    data = yaml(source);
+    if (!Array.isArray(data?.body) || !data.body.length || data.body.length > 50) throw new Error('Template needs between 1 and 50 form fields.');
+    fields = data.body.map((field,index) => {
+      if (!object(field) || !['markdown','input','textarea','dropdown','checkboxes'].includes(field.type)) throw new Error(`Unsupported field type: ${text(field?.type) || 'unknown'}. Open this form on GitHub instead.`);
+      const attrs = field.attributes;
+      if (!object(attrs)) throw new Error('Template field attributes are missing.');
+      if (field.type === 'markdown') return {id:`note-${index}`,type:'markdown',value:text(attrs.value)};
+      const id = field.id ?? `field-${index}`;
+      if (typeof id !== 'string' || !/^[a-zA-Z0-9_-]{1,80}$/.test(id) || ['__proto__','constructor','prototype'].includes(id)) throw new Error('Invalid form field identifier.');
+      if (!text(attrs.label).trim()) throw new Error('Template field label is missing.');
+      const value = {id,type:field.type,label:attrs.label,description:text(attrs.description),placeholder:text(attrs.placeholder),value:text(attrs.value),required:field.validations?.required === true,render:text(attrs.render)};
+      if (value.render && !/^[A-Za-z0-9_+.-]{1,32}$/.test(value.render)) throw new Error('Unsupported code language in template.');
+      if (field.type === 'dropdown' || field.type === 'checkboxes') {
+        if (!Array.isArray(attrs.options) || !attrs.options.length || attrs.options.length > 100) throw new Error('Invalid form choices.');
+        value.options = attrs.options.map(option => {
+          if (field.type === 'dropdown' && typeof option === 'string') return {label:option,required:false};
+          if (field.type === 'checkboxes' && object(option) && text(option.label).trim()) return {label:option.label,required:option.required === true};
+          throw new Error('Invalid form choice.');
+        });
+        if (new Set(value.options.map(option=>option.label)).size !== value.options.length) throw new Error('Duplicate form choices.');
+        value.multiple = field.type === 'checkboxes' || attrs.multiple === true;
+        value.value = value.multiple ? [] : '';
+        if (field.type === 'dropdown' && attrs.default !== undefined) {
+          if (!Number.isInteger(attrs.default) || !value.options[attrs.default]) throw new Error('Invalid default form choice.');
+          value.value = value.multiple ? [value.options[attrs.default].label] : value.options[attrs.default].label;
+        }
+      }
+      return value;
+    });
+  }
+  if (!object(data) || !text(data.name).trim()) throw new Error('Template name is missing.');
+  if (new Set(fields.map(field=>field.id)).size !== fields.length) throw new Error('Duplicate field identifiers.');
+  return {id:name,sha,name:data.name,description:text(data.description || data.about),title:text(data.title),labels:names(data.labels),fields};
+}
+function project(repo) {
+  const repository=readProjectLinks(repo)?.repository;
+  if (!repository) throw new Error('This project has no configured GitHub origin.');
+  return {repository,slug:repository.slice('https://github.com/'.length)};
+}
+async function contents(slug, name, read) {
+  const value=await read(['api','--hostname','github.com',`repos/${slug}/contents/.github/ISSUE_TEMPLATE/${encodeURIComponent(name)}`]);
+  if (value?.type !== 'file' || value.encoding !== 'base64' || typeof value.content !== 'string' || value.size > 100000 || value.content.length > 150000 || !/^[a-f0-9]{40,64}$/.test(value.sha || '')) throw new Error('Unexpected template file from GitHub.');
+  return {source:Buffer.from(value.content,'base64').toString('utf8'),sha:value.sha};
+}
+export async function readTemplates(repo, read=githubRead) {
+  const {repository,slug}=project(repo);
+  let entries;
+  try { entries=await read(['api','--hostname','github.com',`repos/${slug}/contents/.github/ISSUE_TEMPLATE`]); }
+  catch(error) {
+    if (error.status !== 404) throw error;
+    // A private/inaccessible repository also returns 404; don't call that "no templates".
+    await read(['api','--hostname','github.com',`repos/${slug}`]);
+    return {repository,templates:[],contacts:[],warnings:[]};
+  }
+  if (!Array.isArray(entries)) throw new Error('Unexpected template directory from GitHub.');
+  const files=entries.filter(entry=>entry.type==='file' && filename(entry.name));
+  if (files.length > 20) throw new Error('This repository has more than 20 templates. Open its chooser on GitHub or use a blank local issue.');
+  const templates=await Promise.all(files.map(async file=>{
+    try { const {source,sha}=await contents(slug,file.name,read);return {...parseTemplate(file.name,source,sha),form_url:`${repository}/issues/new?template=${encodeURIComponent(file.name)}`}; }
+    catch(error) { return {id:file.name,name:file.name,description:'',unavailable:error.message,form_url:`${repository}/issues/new?template=${encodeURIComponent(file.name)}`}; }
+  }));
+  const config=entries.find(entry=>entry.type==='file' && /^config\.ya?ml$/i.test(entry.name));
+  const contacts=[],warnings=[];
+  if(config) {
+    try {
+      const value=yaml((await contents(slug,config.name,read)).source);
+      for(const link of Array.isArray(value?.contact_links)?value.contact_links:[]) {
+        const url=new URL(link.url);
+        if(url.protocol==='https:' && !url.username && !url.password && text(link.name).trim()) contacts.push({name:link.name,url:url.href,description:text(link.about)});
+      }
+    } catch { warnings.push('Repository contact links could not be loaded. Check the GitHub issue chooser for private reporting guidance.'); }
+  }
+  return {repository,templates,contacts,warnings};
+}
+export function compileTemplate(template, { title, answers }) {
+  if (typeof title !== 'string' || !title.trim() || title.length > 160) throw new Error('Provide an issue title of 1–160 characters.');
+  if (!object(answers)) throw new Error('Expected field answers.');
+  const sections=[];
+  for(const field of template.fields) {
+    if(field.type==='markdown') continue;
+    const answer=Object.hasOwn(answers,field.id) ? answers[field.id] : field.value;
+    let rendered;
+    if(field.multiple) {
+      if(!Array.isArray(answer) || answer.some(v=>typeof v!=='string' || !field.options.some(o=>o.label===v)) || new Set(answer).size!==answer.length) throw new Error(`Choose valid options for ${field.label}.`);
+      if(field.required&&!answer.length || field.options.some(option=>option.required&&!answer.includes(option.label))) throw new Error(`Complete the required choices in ${field.label}.`);
+      rendered=field.type==='checkboxes' ? field.options.map(option=>`- [${answer.includes(option.label)?'x':' '}] ${option.label}`).join('\n') : answer.join(', ');
+    } else {
+      if(typeof answer!=='string' || Buffer.byteLength(answer)>240000) throw new Error(`Invalid answer for ${field.label}.`);
+      if(field.required&&!answer.trim()) throw new Error(`${field.label} is required.`);
+      if(field.type==='dropdown' && answer && !field.options.some(option=>option.label===answer)) throw new Error(`Choose a valid option for ${field.label}.`);
+      rendered=answer.trim();
+    }
+    if (rendered && field.type==='textarea' && field.render) {
+      const longest=(rendered.match(/`+/g)||[]).reduce((max,run)=>Math.max(max,run.length),0);
+      const fence='`'.repeat(Math.max(3,longest+1));
+      rendered=`${fence}${field.render}\n${rendered}\n${fence}`;
+    }
+    if(rendered) sections.push(`### ${field.label}\n\n${rendered}`);
+  }
+  const spec=`# ${title.trim()}\n\n${sections.join('\n\n')}`;
+  const recommendation=recommendWork({spec,labels:template.labels});
+  return {title:title.trim(),spec,labels:template.labels,template:{id:template.id,sha:template.sha},recommendation};
+}
+export async function draftFromTemplate(repo, input, read=githubRead) {
+  if(!filename(input.template)) throw new Error('Choose a repository issue template.');
+  const {slug}=project(repo), file=await contents(slug,input.template,read);
+  if(typeof input.sha!=='string' || input.sha!==file.sha) throw new Error('The template changed. Reload templates and review the current fields.');
+  return compileTemplate(parseTemplate(input.template,file.source,file.sha),input);
+}

package/factory/server.mjs

@@ -3,7 +3,9 @@ import http from 'node:http';
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { existsSync, readFileSync, readdirSync, lstatSync, realpathSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
-import { readIssue } from './issue-intake.mjs';
+import { listIssues, readIssue } from './issue-intake.mjs';
+import { readTemplates, draftFromTemplate } from './issue-templates.mjs';
+import { recommendWork } from './intake.mjs';
 import { machineInfo } from './machine.mjs';
 import { factoryDefinition } from './definition.mjs';
 import { JobQueue, QueueError } from './queue.mjs';
@@ -57,6 +59,16 @@ export function createController(state, adapter = executors(state)) {
       if (request.method === 'GET' && url.pathname === '/api/v1/definitions') {
         return send(200, definitions);
       }
+      if (request.method === 'GET' && url.pathname === '/api/v1/issues') {
+        if (!authenticated) throw new QueueError('Session required', 403);
+        try { return send(200, await listIssues(config.repo, Number(url.searchParams.get('page') || 1))); }
+        catch (error) { throw new QueueError(error.message, 400); }
+      }
+      if (request.method === 'GET' && url.pathname === '/api/v1/issue-templates') {
+        if (!authenticated) throw new QueueError('Session required', 403);
+        try { return send(200, await readTemplates(config.repo)); }
+        catch (error) { throw new QueueError(error.message, 400); }
+      }
       const content = url.pathname.match(/^\/api\/v1\/artifacts\/(job_[a-f0-9]+)~(run_[a-f0-9]+)~([\w.-]+)\/content$/);
       const artifactList = url.pathname.match(/^\/api\/v1\/jobs\/(job_[a-f0-9]+)\/artifacts$/);
       if (request.method === 'GET' && (artifactList || content)) {
@@ -81,6 +93,14 @@ export function createController(state, adapter = executors(state)) {
           try { return send(200, await readIssue(config.repo, input.url)); }
           catch (error) { throw new QueueError(error.message, 400); }
         }
+        if (url.pathname === '/api/v1/issue-templates/draft') {
+          try { return send(200, await draftFromTemplate(config.repo, input)); }
+          catch (error) { throw new QueueError(error.message, 400); }
+        }
+        if (url.pathname === '/api/v1/intake/recommend') {
+          try { return send(200, recommendWork(input)); }
+          catch (error) { throw new QueueError(error.message, 400); }
+        }
         if (url.pathname === '/api/v1/jobs') {
           if (input.model && input.model !== config.model && !['codex','pi'].includes(harnessOf(config))) throw new QueueError('Model overrides require a codex or pi executor', 400);
           return send(201, queue.submit(input));

package/factory/terminology.json

@@ -6,7 +6,8 @@
   "agent": "A configured work role with a responsibility and instructions, executed through a harness.",
   "skill": "Reusable instructions available to an agent or operator; not a process or an access grant.",
   "workflow": "The ordered agent steps, deterministic checks and approval gates for a work type.",
-  "task": "A bounded work request admitted to the controller; stored as a job with retained run attempts.",
+  "task": "Compatibility name for an admitted local issue, stored as a job with retained run attempts.",
   "automation": "A trigger, filters and target that admits work automatically. Not yet implemented.",
-  "definition": "The effective work roles, workflows, skills and installation settings, separate from runtime records."
+  "definition": "The effective work roles, workflows, skills and installation settings, separate from runtime records.",
+  "issue": "A bounded local work request, created from a repository form, blank brief or GitHub issue; Create & start admits execution. This does not publish a GitHub issue."
 }