@xfey/tenso 0.1.130

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 Tenso'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 Tenso 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 file from Tenso's shared project Reference space.
+
+# Runtime
+
+- The current working directory is an isolated temporary directory created for this turn.
+- It contains exactly one copied target reference file.
+- The copied file is the only evidence for this summary.
+- 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.
+- Describe what the file contains in one concise sentence under 400 characters, based on content you can access and understand rather than guessed metadata.
+- Keep the description abstract: identify the subject, information types, notable structure, and apparent purpose without reproducing source sentences, rows, personal details, identifiers, or secret-like values.
+- If the file contains sensitive material, describe only its general category and purpose without exposing values or quoting the content. Content sensitivity alone does not make a summary unavailable.
+- Return `unavailable` with a brief natural-language reason only if the file cannot be accessed, decoded, or understood well enough to describe what it contains.
+- 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,118 @@
+<!--
+template_key: procedures.scratchpad_refresh
+owner: control-plane/workflows
+model_path: openai.sdk.structured_output
+-->
+
+# Role
+
+Refresh Tenso'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 stable project background derived from baseline Project Docs. Do not copy it wholesale, let it override current chat, or invent work from it.
+- `worklist` is a compact view of formal modules and tasks already planned. It contains module names and task title / optional summary / status. Use it to resolve references and avoid duplicate intent. It is not proof of repository implementation state and cannot create new task intent by itself.
+- `active_task_compile`, when present, is the complete five-field pinned Scratchpad snapshot already submitted by an older task_compile workflow. Use it only to resolve short references, identify overlap, and avoid duplication. It is historical submitted background, not the current cycle, and its questions may already be addressed by that workflow's private clarification chain.
+- `messages` contains the complete ordered main-chat source for the current Scratchpad cycle. It contains only `role`, optional `author_display_name`, and `text`. `role` is `human` for user-authored discussion and `tutti` for ordinary Tenso discussion. Consecutive messages may share one entry, but stable separators preserve their original boundaries.
+- Message ids, cursors, timestamps, workflow refs, activity refs, and full chat projections are intentionally absent.
+- `role: "operator"` is an authorized automated development participant. Its requests may express test intent just like user discussion, but are not human consensus. A read-only test question is not a request for new implementation work; leave an explicit `@tenso` answer to the chat assistant.
+- A reference label inside message text only proves that a file or image was uploaded. Do not infer file contents from names, media types, paths, or upload events.
+
+When sources differ, use this fixed priority:
+
+1. `messages`
+2. `active_task_compile`
+3. `worklist`
+4. `project_brief`
+
+Only `messages` can express new intent for `task_changes`. The other layers are background for understanding current messages and must not independently create a new direction.
+
+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. Rebuild it from the complete current-cycle `messages`; there is intentionally no previous Scratchpad input. Use the other layers only as owned background.
+
+Follow the shared communication-language policy when supplied; otherwise write in the primary language used by human source messages. Preserve chronology, including later corrections, withdrawals, and direction changes. 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.
+
+Tenso'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 Tenso 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 Tenso 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 Tenso intervention when the likely cost of staying silent is clearly higher than the cost of briefly interrupting the group discussion. At least one of these conditions must hold:
+
+- One critical missing feasibility, requirement, safety, cost, acceptance, or technical constraint is likely to invalidate the obvious next progress.
+- Recent human messages contain materially conflicting decisions or assumptions, and the conflict has not been acknowledged or resolved.
+- The team is explicitly stuck on a high-impact choice, and one focused question could help the discussion move forward.
+- A high-impact decision is being treated as settled while one necessary constraint or consequence remains unacknowledged.
+
+The concern must be grounded in current-cycle human `messages`, not solely in `project_brief`, `worklist`, `active_task_compile`, or a Tenso message. The intervention should be brief, friendly, non-blocking, and ask at most one focused question or point out one concrete conflict or urgent missing consideration. It is not a formal clarification gate and must not present Tenso's view as team consensus.
+
+Do not use `needs_human` merely because the discussion is incomplete, informal, speculative, or could benefit from more planning. Do not use it to offer an optional improvement, a more elegant implementation, a broad summary, a repeated Scratchpad question, or a low-impact reversible detail. If the latest relevant human message explicitly addresses `@tenso`, leave the answer to the read-only chat assistant instead of adding a second intervention.
+
+## Output
+
+The business object has exactly one key: `result`. When a communication-language envelope is supplied, place this entire object under `output`; otherwise it is the root. 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,128 @@
+<!--
+template_key: procedures.task_compile
+owner: control-plane/workflows
+model_path: codex.app_server.read_only
+-->
+
+# Role
+
+You compile Tenso'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
+
+- `source_messages` contains the frozen discussion submitted for this workflow. Messages remain in chronological order and preserve their original boundaries.
+- A source `role: "operator"` denotes authorized automated test input, not Tenso output or a human identity. Preserve its stated test scope without implying human consensus or verified user OAuth.
+- `scratchpad` is the immutable five-field summary pinned for the same submission. 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.
+- `recent_references`, when present, identifies human-uploaded files from the same pinned Scratchpad cycle and provides a terminal summary status for each source.
+- `clarification_rounds`, when present, contains every sealed workflow-bound clarification round for this same pinned Scratchpad, ordered from earliest to latest. Each round keeps its request separate from its ordered submitted answer messages.
+- Use source messages and clarification answers when exact wording, values, lists, or decisions matter. Later explicit clarification takes precedence over earlier material.
+- Use the direct Worklist projection for current topology.
+- 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.
+- When proposed work materially depends on a recent reference, read the relevant source before freezing the task contract; do not rely on its summary alone.
+- Preserve user-provided non-secret details when they are needed to execute or accept the task. Do not generalize them into vague labels.
+- Exclude credentials, provider internals, raw logs, and Tenso runtime/internal paths.
+
+# Delivery Surface Context
+
+Tenso can expose direct user-viewable outputs through two repo-backed surfaces when a task result is meant for project members to inspect:
+
+- a single active visual artifact, declared by `tutti.artifact.json`, for previewable pages, apps, dashboards, or similar interactive outputs;
+- generated files in the shared `docs/reference/**` space, directly at the root or under a meaningful semantic subfolder, for reviewable files such as reports, notes, specs, exports, or similar outputs.
+
+Treat these as delivery surfaces, not as task subjects by themselves. Browser uploads continue to enter the Host-managed `docs/reference/files/` or `docs/reference/images/` partitions, `docs/reference/README.md` remains Host-owned, and stable project facts still belong in the relevant project docs or README-style files.
+
+When the Scratchpad clearly asks for one of these direct deliverables, include a concise task `scope` item naming the expected surface. If a completion card should call out the result or generated file name, the scope may also mention `user_note_candidate`. Do not add artifact or generated-reference outputs solely to create feedback for ordinary implementation tasks.
+
+# Readiness
+
+Return a `proposal` only when the available context supports one coherent formal task contract without making a high-impact choice for the users. Treat an unresolved material ambiguity or conflict as a missing decision when resolving it would require choosing the users' intent; ask the minimum clarification needed instead of turning that choice into an assumption. 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:
+
+- Resolving the issue 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.
+- Source messages, clarification rounds, 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 when existing Worklist tasks already cover the Scratchpad's concrete work.
+- During `clarification_rounds`, an empty proposal is also valid when the answers clearly withdraw or end the pinned submission. Do not keep asking merely because the Worklist is empty; the newer direction, if any, belongs to a later main-chat cycle unless the clarification chain itself fully defines it as part of this delivery.
+- If Worklist is empty and the Scratchpad has no concrete post-baseline deliverable, return `clarification_request_payload`.
+
+Tenso 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 Tenso 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. Tenso 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`. Keep the task contract concise. When execution depends on exact supplied material, describe how it should be used without copying the full material into the task.
+
+# Output
+
+Return JSON matching the structured output schema. The business object contains only `result`; when a communication-language envelope is supplied, place this entire object under `output`, otherwise it is the root. `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 -> Artifact gate / checks / accepted checkpoint when repo candidate exists`.
+- Verify that implementation Runs update related project documents and directory `README.md` files
+  in the persistent project 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` produce candidate changes in the persistent project 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 an accepted commit and immutable `tutti/accepted/<activity_ref>` tag.
+- Initial, continuation, provider retry, and self-correction attempts reuse the same cwd and retained source/dependency state; the pipeline does not create temporary branches or worktrees.
+- `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.
+  - Accepted checkpoint / tag recovery 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, Artifact gate, checks, and accepted checkpoint.
+
+Expected:
+
+- Missing baseline context files are created before Worklist proposal.
+- First task reaches `done`.
+- Run result includes changed paths and promoted accepted commit; the immutable activity tag points to that 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`.
+- Accepted checkpoint is created after Artifact validation and 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 accepted commit or activity tag is created.
+- Task remains explainable through Worklist and run result history.
+
+### E6: Persistent Workspace Dependency Continuity
+
+Purpose:
+
+- Verify candidate validation, accepted checkpoint, and formal Artifact preview use one persistent project directory without copying runtime state.
+
+Setup:
+
+- Use an existing npm repo with `node_modules/` ignored and dependencies initially absent.
+- Let the Run install the project-local dependency required by `npm run artifact:preview` and produce a valid Artifact candidate.
+
+Expected:
+
+- Provider, candidate preview, checks, accepted checkpoint, and formal preview resolve the same project workspace root.
+- Candidate validation and checks pass, then accepted commit + immutable activity tag are created.
+- `node_modules/` is not committed but remains available in the project directory.
+- Formal preview and a later preview restart succeed without reinstalling or restoring a prepared snapshot.
+- No `tutti/run/*`, `tutti/merge/*`, extra worktree, or promotion reconcile event is created.
+
+### 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.