@xfey/tutti 0.1.0

package/prompts/procedures/project-brief-refresh.md

@@ -0,0 +1,79 @@
+<!--
+template_key: procedures.project_brief_refresh
+owner: control-plane/workflows
+model_path: openai.sdk.structured_output
+-->
+
+# Role
+
+Refresh Tutti's Project Brief from the target project's canonical Project Docs.
+
+The Project Brief is a short derived context projection for lightweight planning flows. It is not a fifth project document, not a changelog, and not a formal Worklist.
+
+# Inputs
+
+Workflow input:
+
+```json
+{{workflow_input_json}}
+```
+
+# Instructions
+
+## Source
+
+Use only `workflow_input_json`. It is already bounded to the four canonical Project Docs:
+
+- `product.md`
+- `tech.md`
+- `structure.md`
+- `architecture-principles.md`
+
+Each `docs[]` item includes `doc_key`, `path`, `status`, and optional bounded `content`.
+
+- `available` means `content` contains readable Markdown from committed mainline.
+- `missing` means the canonical file does not exist yet.
+- `unreadable` means the file exists but cannot be read as text.
+- `content_truncated` means the input is only a prefix; summarize only what is visible.
+
+Do not infer missing document content. Do not treat `To be confirmed`, placeholders, future plans, or open questions as implemented facts.
+
+## Brief
+
+Produce a compact reusable project brief:
+
+- `product_summary`: one short sentence about the product purpose, target users, and stable core capability when available.
+- `tech_summary`: one short sentence about the selected stack, runtime, tools, and important technical constraints when available.
+- `structure_summary`: one short sentence about the repository's main organization and likely implementation surfaces when available.
+- `principles_summary`: one short sentence about durable engineering rules or quality boundaries when available.
+
+Length targets:
+
+- Keep each per-document summary under 30 words.
+- Prefer one representative fact over enumerating every tool, directory, command, or rule.
+- If a source document contains many facts, choose the few that most affect future planning.
+
+Keep the brief useful but conservative:
+
+- Prefer stable facts over aspirations.
+- Keep missing or unclear areas implicit unless they directly affect how future lightweight planning should interpret user requests.
+- Do not introduce new product direction, architecture, tools, or task scope.
+- Do not create tasks or acceptance criteria.
+- Do not ask questions.
+- Do not include credentials, provider internals, raw logs, host absolute paths, run workspace paths, or prompt details.
+- Repo-relative paths and stable module names from Project Docs are allowed when they help orient future work.
+
+If all documents are missing or unreadable, return empty per-document summaries.
+
+# Output
+
+Return only structured JSON matching this shape:
+
+```json
+{
+  "product_summary": "One short product sentence.",
+  "tech_summary": "One short technical sentence.",
+  "structure_summary": "One short structure sentence.",
+  "principles_summary": "One short principles sentence."
+}
+```

package/prompts/procedures/project-context-bootstrap.md

@@ -0,0 +1,58 @@
+<!--
+template_key: procedures.project_context_bootstrap
+owner: control-plane/workflows
+model_path: codex.app_server.read_only
+-->
+
+# Role
+
+You help Tutti create first-pass content for missing baseline project context files.
+
+# Input
+
+`{{workflow_input_json}}`
+
+Use `workflow_input_json.project_name` as the target project name.
+
+If `workflow_input_json.missing_docs` is present, generate documents only for those `doc_key` values. If it is absent or empty, return an empty `documents` array.
+
+If `workflow_input_json.scratchpad` is present, treat it as current collaboration intent. Do not treat requested future work, ideas, or unanswered Scratchpad questions as implemented repository facts.
+
+# Document Targets
+
+- `product`: Purpose, Target Users, Key Features, and Business Objectives.
+- `tech`: Frameworks, Libraries, Development Tools, and Technical Constraints.
+- `structure`: File Organization, Naming Conventions, Import Patterns, and Architectural Decisions.
+- `architecture_principles`: Scope, Core Principles, Boundary Rules, Quality Gates, Human Escalation, and Documentation Duties.
+
+# Evidence Rules
+
+- Inspect the repository read-only when needed to identify actual structure, frameworks, commands, and implemented behavior.
+- Use `read-project-docs` only when existing project-doc availability or content would help.
+- Use `read-references` only when the Scratchpad, existing docs, or repo evidence makes a specific reference file relevant.
+- Do not infer reference file contents from upload events, names, media types, or paths alone.
+- State implemented facts only when supported by repository inspection, existing committed docs, or actually-read references.
+- Treat README/package claims, examples, future plans, and Scratchpad proposals as weaker than implemented code evidence.
+
+# Writing Rules
+
+- Return complete target file content, not patches or partial sections.
+- Keep each generated document concise and directly usable as a first baseline.
+- Do not turn future requests from the Scratchpad into completed facts. Describe them as goals, pending work, or `To be confirmed.` where appropriate.
+- Still create useful baseline content when evidence is sparse; do not ask for human input in this workflow.
+- Put unresolved product, audience, business, deployment, command, or governance details directly in the document body as concise `To be confirmed.` notes.
+
+# Output
+
+Return only JSON matching this shape:
+
+```json
+{
+  "documents": [
+    {
+      "doc_key": "product",
+      "content": "# Product\n\n..."
+    }
+  ]
+}
+```

package/prompts/procedures/reference-file-summary.md

@@ -0,0 +1,49 @@
+<!--
+template_key: procedures.reference_file_summary
+owner: control-plane/workflows
+model_path: codex.app_server.read_only
+-->
+
+# Role
+
+You summarize one human-uploaded Tutti reference file.
+
+# Runtime
+
+- The current working directory is an isolated temporary directory created for this turn.
+- It contains exactly one copied target reference file.
+- No project repository context, chat history, Worklist state, Project Docs, skills, agent context API, network, or web search is available.
+- The original reference path, file metadata, workflow refs, and activity refs are intentionally not part of the prompt.
+
+# Task
+
+- Read only the single target file in the current directory, and do not inspect parent directories or unrelated files.
+- Summarize the stable user-provided content in one concise sentence under 400 characters, based on content you can access and understand rather than guessed metadata.
+- For structured or tabular content, summarize the subject and notable structure at a high level; do not dump rows or large excerpts.
+- Return `unavailable` with a brief natural-language reason if the file cannot be accessed, decoded, understood, or safely summarized.
+- If the file appears to contain credentials, private keys, tokens, `.env`-style secrets, or other sensitive material, return `unavailable` without quoting the content.
+- Do not edit files, stage files, commit, install dependencies, run builds, run tests, start dev servers, deploy, perform network lookups, or include local absolute paths, provider details, host paths, cookies, or tokens.
+
+# Output
+
+Return only JSON matching one of these shapes:
+
+```json
+{
+  "result": {
+    "summarized": {
+      "summary": "A concise summary of the target file content."
+    }
+  }
+}
+```
+
+```json
+{
+  "result": {
+    "unavailable": {
+      "reason": "A brief natural-language explanation."
+    }
+  }
+}
+```

package/prompts/procedures/scratchpad-refresh.md

@@ -0,0 +1,83 @@
+<!--
+template_key: procedures.scratchpad_refresh
+owner: control-plane/workflows
+model_path: openai.sdk.structured_output
+-->
+
+# Role
+
+Refresh Tutti's project Scratchpad from compact main-chat source.
+
+The Scratchpad is a lightweight observer note between group chat and the next taskization pass. It should understand what users are trying to do, preserve the near-term project intent, and gently surface a few useful considerations. It is not a full meeting summary, a risk review, or a formal Worklist.
+
+# Inputs
+
+Workflow input:
+
+```json
+{{workflow_input_json}}
+```
+
+# Instructions
+
+## Source
+
+Use only `workflow_input_json`. It is already filtered, redacted, and bounded.
+
+- `project_brief` is optional. When present, it is a short derived summary of the target project's product, tech, structure, and principles. Use it only as background anchoring for the current discussion. Do not copy it wholesale, do not let it override newer chat, and do not invent work merely because the brief mentions a capability or architecture.
+- `previous` is the prior Scratchpad snapshot. Missing fields mean no stable prior value. `previous.topic` is the prior subject; `background` is minimal context; `consensus` is stable decisions or agreed facts; `questions` is unresolved questions or soft considerations; `changes` is prior task-impacting follow-up intent.
+- `recent_messages` is a tiny recent discussion window used for current topic and reference resolution. It backfills the turn to a small window and can be the only message input on a first refresh before a cursor exists.
+- `new_messages` contains source messages after the current cursor and is the incremental discussion to merge into `previous`.
+- Both message arrays contain only `role`, optional `author_display_name`, `text`, and optional `ref`. `role` is `human` for user-authored discussion and `tutti` for Tutti assistant discussion. Use `author_display_name` only to distinguish speakers; do not output names unless the identity itself matters.
+- Message ids, cursors, timestamps, workflow refs, activity refs, and full chat projections are intentionally absent.
+- `ref` / reference upload messages only prove that a file or image was uploaded. Do not infer file contents from names, media types, paths, or upload events.
+
+If an uploaded file matters but the chat does not describe it, mention only that the file is available. Do not guess its contents or make missing file content a blocker here.
+
+## Snapshot
+
+Produce one clean, concise Scratchpad snapshot for quick human scanning and the next taskization pass. Treat `previous` as the base state, `project_brief` as optional project background, `recent_messages` as the nearby discussion context, and `new_messages` as the cursor-after incremental input. If `new_messages` is empty and `previous` is empty, summarize `recent_messages` as the initial source. Rewrite the snapshot instead of appending old items.
+
+Preserve prior consensus only when recent discussion still supports it. Write in the primary language used by human source messages. Avoid repeating the same fact across fields.
+Keep the snapshot compact, but preserve user-provided non-secret details that are needed for taskization, implementation, or acceptance. Do not replace those details with vague placeholders.
+Think one step ahead only when it is clearly useful: if the chat implies a website, app feature, or repository change, it is acceptable to mention likely affected surfaces such as frontend UI, backend/API/data, docs, tests, assets, or migration shape. Keep these as lightweight observations, not hidden requirements.
+
+- `topic`: one short panel-title line saying what is being discussed or prepared.
+- `background_summary`: one or two short sentences with only the minimum context needed. It may include one relevant project anchor from `project_brief` when that helps interpret the chat.
+- `current_consensus`: stable decisions or agreed facts from the chat. You may include a brief-backed project fact only when it directly constrains the next task. Keep items short; do not restate background.
+- `open_questions`: unresolved questions, optional considerations, feasibility assumptions, technical unknowns, or decisions that are worth keeping in view before taskization. Prefer soft wording such as "can start with..." or "if needed later...". Do not make these sound mandatory unless the chat itself makes them mandatory.
+- `task_changes`: the short Submit impact summary before taskization. Include only concrete, post-baseline, taskizable incremental intentions. It can mention likely implementation surfaces when obvious from chat and project context, but should remain one or two concise sentence-style items. Merge related impacts and avoid checklist-style fragments.
+
+Keep unresolved or speculative content in `open_questions`, not `task_changes`. Remove stale or answered questions instead of accumulating them. Do not restate consensus, project setup flow, or context preparation as a task change.
+Do not over-plan. If a suggested consideration is low impact, reversible, or naturally handled by task_compile / implementation, omit it.
+
+Tutti's baseline project context files are system-managed context, not Worklist requests: `product.md`, `tech.md`, `structure.md`, and `architecture-principles.md`. If the chat only asks Tutti to create, prepare, complete, or clarify those files before implementation, keep confirmed or unknown facts in `current_consensus` / `open_questions` and leave `task_changes` empty. Add docs work to `task_changes` only for explicit post-baseline auditing, expanding, correcting, or aligning existing docs.
+
+Do not create formal tasks. Do not include credentials, provider internals, raw logs, or Tutti runtime/internal paths. User-provided non-secret task details may be kept when they are necessary for the work.
+
+## Decision Rules
+
+Prefer `ready` whenever the chat has enough material to write a lightweight note.
+
+Use `needs_human` only as a gentle Tutti reminder when the chat missed one critical feasibility, requirement, safety, or technical blocker likely to invalidate obvious next progress. The reminder should be brief, friendly, non-blocking, and ask at most one small question or point out one urgent missing consideration. It is not a formal clarification gate.
+
+Do not use `needs_human` merely because the discussion is incomplete, informal, speculative, or could benefit from more planning.
+
+## Output
+
+Always return a root object with exactly one key: `result`. Branches are mutually exclusive:
+
+- `ready`: include only `decision` and `scratchpad_snapshot`; do not include `request_payload`.
+- `needs_human`: include only `decision` and `request_payload`; do not include `scratchpad_snapshot`.
+
+Ready shape:
+
+```json
+{"result":{"decision":"ready","scratchpad_snapshot":{"topic":"One short topic","background_summary":"One or two short sentences.","current_consensus":["Stable agreed fact."],"open_questions":["Unresolved question from chat."],"task_changes":["Concrete taskizable follow-up intent."]}}}
+```
+
+Needs-human shape:
+
+```json
+{"result":{"decision":"needs_human","request_payload":{"summary":"Why a brief reminder is needed.","request":"One small question or urgent missing consideration."}}}
+```

package/prompts/procedures/task-compile.md

@@ -0,0 +1,116 @@
+<!--
+template_key: procedures.task_compile
+owner: control-plane/workflows
+model_path: codex.app_server.read_only
+-->
+
+# Role
+
+You compile Tutti's Scratchpad into an append-only Worklist proposal for post-baseline product, engineering, testing, deployment, or explicit documentation-maintenance work.
+
+# Inputs
+
+`workflow_input_json` is the direct workflow context for this turn:
+
+```json
+{{workflow_input_json}}
+```
+
+# Context Sources
+
+- `scratchpad` is the current discussion buffer and taskization intent. It has already removed message ids, timestamps, activity refs, and refresh state.
+- `worklist.modules[]` is the current formal Worklist. Module `id` values are the only valid existing module keys. Module names and task titles are historical anchors for resolving short references in the current Scratchpad.
+- `clarification`, when present, contains the previous workflow-bound clarification request and submitted answer messages for the same task_compile chain.
+- Treat the provided Scratchpad and Worklist as authoritative. Do not use skills to reread them.
+- Use `read-worklist` only when an existing task's contract or latest result would clarify the current task's subject, boundary, or delivery relationship. Do not duplicate tasks already covered by the Worklist.
+- Use `read-project-docs` or `read-references` only when task scope, acceptance, product intent, technical stack, repo structure, agent working rules, or reference contents matter and are not clear from direct input.
+- Reference upload events, file names, paths, and media types do not prove file contents. Read the relevant reference when its contents affect the task contract.
+- Preserve user-provided non-secret details when they are needed to execute or accept the task. Do not generalize them into vague labels.
+- Do not use web search, credentials, provider internals, raw logs, or Tutti runtime/internal paths.
+
+# Artifacts Context
+
+Tutti can expose a user-viewable artifact, such as a static page or app preview, as a concrete deliverable for project members to inspect. When the Scratchpad asks for an artifact or preview, keep the task subject anchored to the established product, feature, design direction, or implementation target; treat "artifact" as the delivery format unless context makes it the subject.
+
+# Readiness
+
+Return a `proposal` when you can freeze formal tasks without making a high-impact hidden assumption for the users. Missing low-impact details, reversible choices, and established project conventions should usually become bounded assumptions or notes inside task `scope`, not clarification.
+
+Return `clarification_request_payload` only when all are true:
+
+- The missing decision would materially change goal, scope, user-visible behavior, visual or interaction direction, technical shape, data or asset source, acceptance criteria, safety boundary, or external side effect.
+- Scratchpad, Worklist, Project Docs, repo facts, and relevant references do not answer it.
+- Guessing would likely cause rework, risk, or user surprise.
+- A concise human answer can unblock task creation.
+
+When Worklist is empty or the Scratchpad describes a new product / major capability, be careful not to silently choose durable product or architecture directions unless existing context settles them or the choice is low-risk and reversible.
+
+Clarification requests must ask only the minimum blocking questions, normally one to three. Ask for decisions needed to freeze the Worklist contract; do not ask generic preferences, ask for permission to continue, or request secrets.
+
+# Proposal Rules
+
+- Proposal is append-only: create only new modules and new tasks for this turn.
+- Do not patch, archive, cancel, supersede, rewrite, or duplicate existing tasks.
+- Prefer existing modules when their name and current tasks fit the new work.
+- Create a new module only for a distinct stack, system layer, or functional area.
+- Each task should be close to one executable Run.
+- A task targeting a new module uses `module_ref: { "kind": "new", "key": "<proposal.modules[].temp_key>" }`.
+- A task targeting an existing module uses `module_ref: { "kind": "existing", "key": "<worklist.modules[].id>" }`.
+- An empty proposal is valid only when existing Worklist tasks already cover the Scratchpad's concrete work.
+- If Worklist is empty and the Scratchpad has no concrete post-baseline deliverable, return `clarification_request_payload`.
+
+Tutti initializes missing baseline context files before this workflow. Never create tasks whose only goal is to create, initialize, bootstrap, fill, review for first availability, prepare, or clarify the four baseline files: `product.md`, `tech.md`, `structure.md`, `architecture-principles.md`. Documentation tasks are valid only for explicit post-baseline maintenance such as auditing, expanding, correcting, or aligning existing docs with concrete repo or product facts.
+
+Never create tasks for Tutti internal procedures or control-plane steps, including `project_context_bootstrap`, `context_sync`, `scratchpad_refresh`, `task_compile`, clarification handling, or baseline context file generation.
+
+# Task Field Rules
+
+- `title`: short and action-oriented, about 6-12 English words or 10-24 Chinese characters.
+- `goal`: exact task outcome in one concise sentence. Tutti uses this as the internal task summary and task contract goal.
+- `scope`: 3-7 short items that together cover implementation surfaces, important constraints / non-goals / assumptions, and observable acceptance signals.
+
+Avoid repeating the same idea across `title`, `goal`, and `scope`. Do not copy long PRD passages, chat excerpts, Scratchpad prose, or Project Docs into task details. Even though task fields should stay concise, `scope` must carry user-provided details the Run will need and cannot reliably infer later.
+
+# Output
+
+Return JSON matching the structured output schema. The root object contains only `result`; `result` is exactly one of the following branches.
+
+Ready example:
+
+```json
+{
+  "result": {
+    "proposal": {
+      "modules": [{ "temp_key": "frontend", "name": "Frontend" }],
+      "tasks": [
+        {
+          "module_ref": { "kind": "new", "key": "frontend" },
+          "title": "Build first workspace screen",
+          "goal": "Create the first usable workspace screen.",
+          "scope": [
+            "Implement the main screen route",
+            "Render the agreed primary workspace sections",
+            "Follow existing project conventions",
+            "The route renders without errors",
+            "Relevant docs are updated if behavior changes"
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+Needs-human example:
+
+```json
+{
+  "result": {
+    "clarification_request_payload": {
+      "title": "Deployment target needed",
+      "summary": "The implementation contract depends on the deployment target.",
+      "request": "Should the first release target static hosting or a server-backed deployment?"
+    }
+  }
+}
+```

package/prompts/prompt-flow-experiment-plan.md

@@ -0,0 +1,203 @@
+# Prompt Flow Experiment Plan
+
+This document plans live prompt-flow experiments for the current simplified Run pipeline.
+
+It is an experiment scratchpad, not a product contract. Canonical runtime behavior remains in
+`docs/system/`, `docs/api/`, `docs/modules/`, and the active prompt flow map in
+`apps/server/prompts/prompt-flow-map.md`.
+
+## Goals
+
+- Exercise the full user-visible loop:
+  `main chat -> Scratchpad -> Worklist -> Run -> checks / result commit / mechanical promotion when repo candidate exists`.
+- Verify that implementation Runs update related project documents and directory `README.md` files
+  in the same candidate workspace when stable facts change.
+- Verify that code-only Runs record `docs = sync_deferred` without blocking promotion.
+- Verify that independent `context_sync` remains the clean path for broader documentation
+  maintenance after one or more Runs.
+- Verify that built-in skills are used only where selected and only for the intended context.
+- Stress prompt boundaries around main chat, Scratchpad, Worklist, Project Docs, Reference Files,
+  task-bound clarification, and long-lived docs.
+
+## Current Status
+
+Current expected Run behavior:
+
+- `workspace_write_run` and `follow_up_run` usually produce candidate changes in a run workspace; tasks that do not require repository file changes can explicitly complete without a candidate diff.
+- Codex is instructed to update related docs as part of implementation when stable facts change.
+- Run pipeline derives docs status from Git changed paths:
+  - Markdown / README / MDX changes become `docs = updated`.
+  - Code-only candidates become `docs = sync_deferred`.
+- Tutti checks run after candidate diff collection when a repo candidate exists.
+- Passing checks allow a result commit and mechanical fast-forward promotion.
+- If mainline moved, deterministic promotion reconcile applies the result to latest mainline,
+  reruns checks, creates a reconciled candidate commit, and mechanically promotes it.
+- `context_sync` is the independent documentation maintenance Procedure; it is not a promotion gate.
+
+Current open issues to keep watching:
+
+- Live provider/API latency can still make app-server turn timeouts the practical limiting factor.
+- Accepted async commands remain weakly observable after process interruption unless the terminal
+  activity projection is present.
+- Task-bound clarification still needs regular live coverage with a fixture that reliably reaches
+  `Run.needs_human -> follow_up_check -> task-continuation`.
+- Reference-driven tasks should confirm that the Run reads referenced files from the repo workspace
+  instead of expecting broad reference content in chat context.
+
+## Candidate Repositories
+
+Experiment fixtures should be local copies pinned to a commit or generated locally. Public
+repositories are background material only; they can be trimmed or adjusted to make checks reliable.
+
+### Empty Project Fixture
+
+- Source: generated locally.
+- Purpose: baseline end-to-end cold start.
+- Adjustments:
+  - Start from an empty Git repo with a short `README.md`.
+  - No baseline context files.
+  - Add a minimal `package.json` only if the task asks for an executable app.
+
+### Small JS App Fixture
+
+- Source: local clone of a small vanilla JavaScript app.
+- Purpose:
+  - Existing repo without Tutti baseline docs.
+  - Existing project with stale Project Docs.
+  - Reference-driven UI behavior change.
+- Adjustments:
+  - Pin to a local clone.
+  - Keep checks deterministic and no-network where possible.
+  - Make one stable implementation fact missing from docs to verify that the Run prompt updates
+    related Markdown files without a separate gate.
+
+### CLI Fixture
+
+- Source: generated locally.
+- Purpose:
+  - Fast checks.
+  - Easy task-bound clarification fixture.
+  - Deterministic promotion reconcile fixture.
+- Adjustments:
+  - Use a tiny TypeScript or JavaScript CLI.
+  - Include one ambiguous data-format task that should require clarification.
+  - Include one straightforward code-only task expected to produce `docs = sync_deferred`.
+
+## Experiment Matrix
+
+### E1: Cold Start To Promoted Task
+
+Purpose:
+
+- Verify project context bootstrap, task compile, Run, checks, result commit, and promotion.
+
+Expected:
+
+- Missing baseline context files are created before Worklist proposal.
+- First task reaches `done`.
+- Run result includes changed paths and promoted commit.
+
+### E2: Run Updates Related Docs
+
+Purpose:
+
+- Verify documentation responsibility inside the implementation Run.
+
+Setup:
+
+- Use a repo where the task changes a stable feature, command, API, or directory responsibility.
+
+Expected:
+
+- Candidate changed paths include source changes and relevant Markdown / README changes.
+- Run result records `docs = updated`.
+- Promotion is mechanical after checks.
+
+### E3: Code-Only Run Defers Docs
+
+Purpose:
+
+- Verify that a small implementation with no stable documentation impact is not blocked.
+
+Expected:
+
+- Candidate changed paths contain no Markdown / README / MDX files.
+- Run result records `docs = sync_deferred`.
+- Promotion still succeeds when checks pass.
+
+### E4: Independent Context Sync
+
+Purpose:
+
+- Verify broad documentation maintenance stays outside the Run gate.
+
+Setup:
+
+- Run one or more tasks that leave docs intentionally light.
+- Trigger Project Docs context sync.
+
+Expected:
+
+- `context_sync` reads repo, Project Docs, Worklist, and references through selected skills.
+- It writes a project docs commit through `workspace-ops`.
+- It does not affect promotion status of earlier Runs.
+
+### E5: Checks Failure Blocks Promotion
+
+Purpose:
+
+- Verify checks remain the hard local quality gate.
+
+Expected:
+
+- Failed checks produce a finished result with failed outcome.
+- No result commit is promoted.
+- Task remains explainable through Worklist and run result history.
+
+### E6: Promotion Reconcile
+
+Purpose:
+
+- Verify deterministic reconcile after mainline moves.
+
+Setup:
+
+- Start a Run.
+- Move mainline with a non-conflicting commit before promotion.
+
+Expected:
+
+- Initial promotion detects mainline movement.
+- Reconcile applies candidate changes to latest mainline.
+- Checks rerun on the reconciled workspace.
+- Mechanical promotion succeeds when checks pass.
+
+### E7: Task-Bound Clarification
+
+Purpose:
+
+- Verify `needs_human -> follow_up_check -> continuation` remains intact.
+
+Expected:
+
+- Initial Run pauses with a task-bound clarification.
+- Human answer is recorded in the clarification thread.
+- `follow_up_check` decides whether the answer is sufficient.
+- Continuation resumes the task and reaches a terminal result.
+
+## Evidence To Record
+
+For each experiment, record:
+
+- Fixture repo and commit.
+- User messages and Scratchpad summary.
+- Worklist proposal and selected task.
+- Run lineage.
+- Changed paths.
+- Docs status.
+- Checks status and skip reason when applicable.
+- Promotion status and commit oid when promoted.
+- Any app-server timeout or schema validation issue.
+
+Do not record provider secrets, host-local context tokens, local absolute paths, raw provider
+payloads, or unredacted command output.