Support durable natural conversations and guarded source recovery

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 <!-- Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 -->
 
+## 0.2.37 — 2026-10-23
+
+- Continue GitHub conversations in natural language, including later replies to confirmed assistant and worker questions. Keep question, author, issue and original task provenance durable across restarts; clarify ambiguous references without requiring commands or internal IDs.
+- Keep read-only conversation separate from execution consent. Reuse fresh, bounded native authorization for ProductAssistant continuation and worker response or resume; hold uncertain outcomes without automatic replay. The selected Agentic or Bridge route includes Humanizer guidance and at most one confirmed response correction.
+- Add the package-owned, measured Codex 0.163 Darwin arm64 source-only profile, bounded MCP resource metadata and correlated error handling. Preserve private-file boundaries, original command budgets and independent final verification.
+- Reconcile observed source-only effects and sanitize only an explicitly reviewed generated index entry, retaining original intent, current source and authority checks. Preserve the read-only Git index boundary and credential admission checks.
+- Show retained worker requests, answers and continuation state in Studio with readable responsive evidence. Refresh the complete canonical walkthrough for the 0.2.37 stamp.
+- Qualify these transitions with controlled host, browser and native PostgreSQL fixtures. They do not establish completed CRM, live model quality or generated-product acceptance.
+
 ## 0.2.36 — 2026-10-22
 
 - Add separately consented GitHub issue conversations under the exact API-observed account, project, repository, issue and selected assistant profile. Bound each grant by expiration and at most three model turns; retain original requests and uncertain outcomes without automatic retry.

README.md

@@ -61,9 +61,9 @@ A factory administrator can review source-control delegation under **Project acc
 
 SDK, CLI and MCP clients can inspect those original-command candidates through the same authenticated read. Inspection never creates a continuation request or dispatches work. API-only installations report local admission and execution separately in health and metrics; accepting a request does not establish that a remote worker is ready.
 
-For a local factory without an incoming webhook route, an administrator can enable [GitHub App issue polling](docs/scm.md#use-github-issue-comments-from-a-local-factory). Complete the baseline and separate account consent before posting a new status or answer comment. The mapped user's current permissions still apply, recorded answers retain their provenance, and answering leaves the existing run paused. For an answered clarification, a separate polling continuation consent lets the mapped person request continuation of that same run. Review its account, components and acknowledgment under **Project access**, then use the exact continuation cut in a new GitHub comment. See the [continuation walkthrough](docs/console-tour.md#review-github-continuation-consent). Polling does not create projects or provide full GitFlow.
+For a local factory without an incoming webhook route, an administrator can enable [GitHub App issue polling](docs/scm.md#use-github-issue-comments-from-a-local-factory) and map your account to current project read access. Ask in the issue: `@forge, how is this going?` or `@forge, ¿qué debería ocurrir si cambia el responsable?` The selected communication model answers from the ticket's verified context. Ambiguous work receives a question with readable labels, rather than an assumed run.
 
-Ask `@forge, how is this going?` or `@forge, ¿cómo va el CRM?` from a mapped account with current ticket read access. Forge uses the ticket's authenticated execution links and asks for clarification when context is missing or ambiguous. With a communication profile selected, the AI writes the complete English or Spanish reply under the same finite review-and-correction contract. The native alias does not rename the GitHub App, and status questions grant no execution permission. See [ticket status conversations](docs/scm.md#ask-about-the-current-ticket).
+When Forge has published a confirmed pending question to you, reply naturally in the same thread: `Sales reviews proposals. Operations may reassign them.` You need no mention, command or internal identifier. The retained question and answer survive a process restart; an execution grant expiring does not discard the conversation. Worker answers and requests such as `Continue the same task` still require fresh, separate effect authority. Unknown outcomes stay held without replay. Product requests such as `@forge, build a CRM with contact imports` are handed to the native product architect under a separate current model allowance; they do not approve a product or start execution. See [natural ticket conversations](docs/scm.md#ask-about-the-current-ticket) for scope, limits and the separate legacy command reference.
 
 For a new product, a separately consented signed GitHub conversation can use `/forge intake` to register its first project and functional definition. This requires current native administrator authority and the repository's explicit intake consent. Registration does not start implementation. Follow [repository intake](docs/repository-workflow.md#register-a-first-product-from-github) for the contract; local issue polling supports status, answers and separately consented clarification continuation on existing runs.
 

docs/agent-roles.md

@@ -56,6 +56,12 @@ Feedback is typed data with a stable ID, role, planned task, attempt 1 to 4, dis
 
 The manager journals feedback before pausing. Questions survive restarts and do not trigger automatic retries. Replaying the same feedback is idempotent; reusing its ID with different content fails. The frozen request budget limits new questions. A response is evidence of an answer, not deployment or publication approval.
 
+For a confirmed question published in a configured GitHub issue, answer naturally in the same thread: “Support account owners receive the alerts.” No mention, request ID or JSON is needed when one current question is unambiguous. forge checks the mapped account, current read access and exact question/publication provenance. It retains the answer across restarts; applying a worker response or continuing execution requires the separate current authority. If several questions fit, identify the question in your own words or answer the clarification. A product-design answer remains part of its ProductAssistant conversation rather than becoming a worker response.
+
+Read-only conversation remains available after an execution grant expires. A request such as “@forge, continue the same task” can use the supported same-run resume path only with fresh consent and unchanged scope. Restricted source-only implementation keeps its [separate readmission limitation](recovery.md); an answer alone does not authorize its next attempt.
+
+### Authenticated API and compatibility clients
+
 Read the durable conversation at `GET /api/v1/runs/{id}/worker-messages`. An authenticated operator answers through `POST /api/v1/runs/{id}/worker-requests/{request_id}/respond`:
 
 ```json
@@ -78,7 +84,7 @@ For issue-bound runs, the existing source-control feedback intent records the pe
 /forge respond {"run_id":"0123456789abcdef0123456789abcdef","request_id":"request-1","answer":"Support account owners receive the alerts."}
 ```
 
-The signed channel receipt supplies a provider actor label and stable response ID, but does not establish an authenticated Forge operator. New replies without that operator context are refused, including internal or channel calls that only supply a label. External actor mapping remains separate work; use the authenticated API or client to answer. The command cannot answer another repository's run, Forge operator credentials are never sent to the provider, and uncertain comment writes require reconciliation rather than blind reposting. `/forge resume` remains a separate enabled action.
+This legacy signed command supplies a provider actor label and stable response ID; the label alone does not establish an authenticated forge operator. Calls without the required operator context are refused. Configured GitHub polling instead uses its explicit native account mapping and separate response/resume consent, as described above. Neither path can answer another repository's run. forge operator credentials are never sent to the provider, and uncertain comment writes require reconciliation rather than blind reposting.
 
 ## Pinned community instructions
 
@@ -100,4 +106,13 @@ The explorer uses `GET /api/v1/agent-roles/lifecycle` and `GET /api/v1/repositor
 
 Choose **Edit** on an instruction role to change its factory instructions or its project skill and native-tool selections. The execution binding and stages stay fixed. Only documentation guidance can be disabled. A draft survives phase navigation and failed saves; close or save it before changing the project. Saving affects later admitted work and leaves retained run snapshots intact.
 
+Factory instructions open in a full-width writing field with keyboard focus.
+Instruction skills and requested native tools have separate labeled groups;
+on a narrow screen they stack above the save and close controls. Project role
+edits keep the same groups while retaining instructions from the registry.
+
+![Factory role instructions and separate skill and tool choices](assets/screenshots/agent-role-instructions-desktop-light.png)
+
+![Role authority and save controls on a narrow screen](assets/screenshots/agent-role-authority-mobile-light.png)
+
 Product dialogue participants are separate from these seven instruction roles. Their task skills are selected from the current validated catalog and frozen in each admitted turn. They do not reuse the deterministic architect role as a model agent. See the [agent lifecycle guide](agent-lifecycle.md) for the phase, skill and knowledge contracts.

docs/architecture.md

@@ -51,11 +51,69 @@ Source: [`api.py`](https://github.com/fireflyframework/firefly-forge/blob/main/s
 
 `Store.event()` retains the sanitized message separately from that bounded projection. Studio renders supported summaries, leaves plain logs readable and offers an explicit verified reader for complete content. Unsupported structured previews receive a generic card. The optional Claude summary fields preserve the existing descriptor version and byte/hash binding; the archive writer, current-authority checks, credential fences and D04 export limits are shared. See [the activity contract](agent-integrations.md#read-complete-retained-provider-activity) and [the operator walkthrough](run-evidence.md#read-complete-provider-activity).
 
+### Durable natural ticket conversations
+
+`SCMNaturalTasks` retains a human message before its configured `communication`
+Agentic/Bridge call. Its separate package-owned YAML catalog and the pinned
+Humanizer adaptation control the typed reply; the qualified source-edit prompt
+manifest is unchanged. `scm_natural_questions.py` projections bind completed typed
+product turns or natural replies to confirmed published comments. Worker
+questions retain their immutable journal identity. No question is extracted from
+untrusted prose.
+
+<div class="forge-flow forge-flow--dependencies" role="region" aria-label="Natural ticket conversation" aria-describedby="natural-conversation-guide" tabindex="0" markdown="1">
+
+```mermaid
+---
+config:
+  flowchart:
+    wrappingWidth: 96
+---
+flowchart LR
+    A[Current issue and reader] --> B[Retain exact human message]
+    B --> C[Configured tool-free AI reply]
+    C --> D[Confirm published typed question]
+    D --> E[Retain later owner answer]
+```
+
+</div>
+
+<p class="forge-flow-caption" id="natural-conversation-guide">A confirmed pending question allows an unmentioned owner reply in the same thread, including after a restart. Focus and scroll the diagram on a narrow screen.</p>
+
+The `retained_question_reply` source kind records this provenance without
+manufacturing a bot mention. Server-owned question references include issue,
+repository, actor, binding, producer and exact published text hashes. Parallel
+contexts require a readable clarification. Typed product answers and proposals
+remain discussion; `NaturalEffects` can project worker answers or continuation
+only into the existing current-permission pipelines. Its retained parent/child
+cut, answer custody and compare-and-set checks prevent late results from
+replacing reconciliation or claiming another channel's answer.
+
+`scm_natural_product.py` hands product requests and exact retained product answers
+to `SCMPollFunctionalAuthority`, `ChannelProducts` and the native ProductAssistant.
+The separately bounded functional grant owns the architect turn; the communication
+classifier cannot spend it implicitly. A new request may create a session or use one
+unique issue/account/model-bound session. An answer uses its exact confirmed
+question producer. Current authority is rechecked through the existing native
+service before effects and after model waits. The original human source, native
+request ID, allowance and parent custody are sealed in a separate child receipt.
+Completed native replies are quoted directly; no model rewrite is added.
+
+The communication route is resolved once per message. Correction and delivery
+checks validate that admitted snapshot against the current profile and routing;
+they do not create a new invocation snapshot during each recheck.
+
+One confirmed invalid typed reply may reserve one correction; unknown outcomes
+are never replayed. Retained answers survive execution-consent expiry. Applying
+one later needs an explicit current review of that same receipt, not another
+human comment or silently renewed consent. See [the user journey and exact
+qualification scope](scm.md#ask-about-the-current-ticket).
+
 ### GitHub polling clarification continuation
 
 `SCMPollResumeGrantInputV3` separates REST-polling continuation consent from status/answer bindings and signed-delivery grants. `SCMPollResumeAuthority` owns current binding, project and native-user checks, immutable consent receipts and bounded history. Its registered pyfly controller, `ForgeClient`, CLI and four MCP tools share the same typed contract. Studio's Mapping, Scope and Review wizard retains one input before submission and reads its exact receipt after an uncertain response.
 
-A new `/forge resume` comment carries the existing version 2 continuation input under the distinct `github_rest_poll_v1` grant. `SCMPollResumeAuthority`, extending `SCMResumeAuthority`, rechecks the current account and application outside the database transaction, then native authority and the original clarification cut under the retained locks. Credential admission waits trigger fresh remote and local checks before action and feedback. An unknown intent remains held; queuing the original run records neither provider execution nor final product acceptance.
+A natural request to continue the same task is projected server-side to the existing version 2 continuation input under the distinct `github_rest_poll_v1` grant. The explicit `/forge resume` form remains a compatibility reference. `SCMPollResumeAuthority`, extending `SCMResumeAuthority`, rechecks the current account and application outside the database transaction, then native authority and the original clarification cut under the retained locks. Credential admission waits trigger fresh remote and local checks before action and feedback. An unknown intent remains held; queuing the original run records neither provider execution nor final product acceptance.
 
 <div class="forge-flow forge-flow--dependencies" role="region" aria-label="GitHub polling continuation boundaries" tabindex="0" markdown="1">