@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/toolkit/skills/kaisoumail-deployment-inventory/references/current-topology.md

@@ -0,0 +1,152 @@
+# KaisouMail current deployment inventory
+
+## Table of contents
+
+- [Verification basis](#verification-basis)
+- [Stable naming rules](#stable-naming-rules)
+- [Current verified production entrypoints](#current-verified-production-entrypoints)
+  - [Web entrypoints](#web-entrypoints)
+  - [API entrypoints](#api-entrypoints)
+- [Current verified runtime resources](#current-verified-runtime-resources)
+  - [API runtime](#api-runtime)
+  - [Email runtime](#email-runtime)
+  - [Database / object storage](#database--object-storage)
+- [Current verified zone / mail routing facts](#current-verified-zone--mail-routing-facts)
+- [Current verified DNS pressure signal](#current-verified-dns-pressure-signal)
+- [Current verified drift between repo and live runtime](#current-verified-drift-between-repo-and-live-runtime)
+- [Current provider-specific pages to open first](#current-provider-specific-pages-to-open-first)
+- [Guardrails for future updates](#guardrails-for-future-updates)
+
+## Verification basis
+
+- This inventory is based on an authenticated control-plane inspection performed on 2026-04-19 (Asia/Shanghai).
+- Current verified hosting / control-plane provider at that time: `Cloudflare`
+- This is current state, not a permanent architectural guarantee.
+- When live control-plane state conflicts with checked-in config, prefer the live control-plane state.
+
+## Stable naming rules
+
+- Canonical project / product name: `KaisouMail`
+- Local repo slug: `cf-mail`
+- Current provider-specific resource names may use labels such as `cf-mail` or `kaisoumail-*`.
+- Never refer to the whole project as `cf-mail` or `Cloudflare mail`; use `KaisouMail` unless naming a specific repo path or runtime resource.
+
+## Current verified production entrypoints
+
+### Web entrypoints
+
+- Public web domains:
+  - `https://cfm.707979.xyz`
+  - `https://km.707979.xyz`
+- Current preview hostname:
+  - `https://cf-mail-e7s.pages.dev`
+- Current provider resource serving the web app:
+  - Cloudflare Pages project resource name: `cf-mail`
+  - This is a provider-side resource name, not the canonical project name.
+
+### API entrypoints
+
+- Public API domains:
+  - `https://api.cfm.707979.xyz`
+  - `https://api.km.707979.xyz`
+- Current provider resource serving the API:
+  - Worker / service name: `kaisoumail-api`
+- Current `workers.dev` hostname retained for provider-side access:
+  - `kaisoumail-api.ivanli2048.workers.dev`
+
+## Current verified runtime resources
+
+### API runtime
+
+- Service name: `kaisoumail-api`
+- Cron trigger: `*/15 * * * *`
+- Visible runtime vars include:
+  - `MAIL_DOMAIN=707979.xyz`
+  - `WEB_APP_ORIGIN=https://cfm.707979.xyz`
+  - `WEB_APP_ORIGINS=https://cfm.707979.xyz,https://km.707979.xyz`
+  - `EMAIL_WORKER_NAME=email-receiver-worker`
+  - `EMAIL_ROUTING_MANAGEMENT_ENABLED=true`
+
+### Email runtime
+
+- Service name: `email-receiver-worker`
+- No public custom domain
+- Provider-side hostname retained:
+  - `email-receiver-worker.ivanli2048.workers.dev`
+- Visible runtime vars include:
+  - `MAIL_DOMAIN=707979.xyz`
+  - `EMAIL_ROUTING_MANAGEMENT_ENABLED=false`
+
+### Database / object storage
+
+- Current production database resource name: `cf-mail-db`
+  - UUID: `460e9fd5-002f-4d45-82be-6d1d6c7abf3a`
+- Current preview database resource name: `cf-mail-db-preview`
+  - UUID: `3584c425-b4df-485f-b863-2db411db8c8e`
+- Current object storage buckets visible in the provider control plane:
+  - `cf-mail-bucket`
+  - `cf-mail-bucket-preview`
+  - `kaisoumail-bucket`
+- Current API runtime binding still points to `kaisoumail-bucket`.
+
+## Current verified zone / mail routing facts
+
+- Relevant active zones visible in the current provider account include:
+  - `707079.xyz`
+  - `707979.xyz`
+  - `fkoai.asia`
+  - `ivanli.asia`
+- `707979.xyz` is active and currently shown as `Free` plan.
+- Current nameservers shown for `707979.xyz`:
+  - `sloan.ns.cloudflare.com`
+  - `theo.ns.cloudflare.com`
+- `707979.xyz` Email Routing currently has an active catch-all rule targeting `email-receiver-worker`.
+- The email worker is shared across multiple visible zones, not only KaisouMail-owned traffic surfaces.
+
+## Current verified DNS pressure signal
+
+- The `707979.xyz` DNS records page currently shows: `1 到 50，2,988 个 已添加记录`.
+- Visible samples include many mailbox-style record names such as `box-*` entries backed by Cloudflare MX records.
+- The report that DNS record capacity is exhausted or nearly exhausted is credible.
+- Start cleanup from dependency mapping, not blind deletion: first map old `box-*` records to still-live mailbox / routing state.
+- Do not state an exact provider quota number unless it is freshly re-verified from an official source and matches current dashboard behavior.
+
+## Current verified drift between repo and live runtime
+
+- The repo and product branding call the project `KaisouMail`.
+- The local repo slug is `cf-mail`.
+- The current web-app provider resource name is `cf-mail`.
+- Some repo docs still describe an intended Pages project name `kaisoumail`.
+- The current production database resource name is `cf-mail-db`, but checked-in config still references the same UUID under legacy name `kaisoumail-db`.
+- The current API runtime still uses legacy names like `kaisoumail-api` and `kaisoumail-bucket`.
+
+## Current provider-specific pages to open first
+
+These URLs are current-state operational shortcuts, not permanent contracts.
+
+- Domains overview:
+  - `https://dash.cloudflare.com/6a0a9f87ad8820dc003b21529cdce222/domains/overview`
+- `707979.xyz` DNS records:
+  - `https://dash.cloudflare.com/6a0a9f87ad8820dc003b21529cdce222/707979.xyz/dns/records`
+- `707979.xyz` Email Routing routes:
+  - `https://dash.cloudflare.com/6a0a9f87ad8820dc003b21529cdce222/707979.xyz/email/routing/routes`
+- Web app custom domains:
+  - `https://dash.cloudflare.com/6a0a9f87ad8820dc003b21529cdce222/pages/view/cf-mail/domains`
+- Web app settings:
+  - `https://dash.cloudflare.com/6a0a9f87ad8820dc003b21529cdce222/pages/view/cf-mail/settings`
+- API runtime settings:
+  - `https://dash.cloudflare.com/6a0a9f87ad8820dc003b21529cdce222/workers/services/view/kaisoumail-api/production/settings`
+- Email runtime settings:
+  - `https://dash.cloudflare.com/6a0a9f87ad8820dc003b21529cdce222/workers/services/view/email-receiver-worker/production/settings`
+- Database overview:
+  - `https://dash.cloudflare.com/6a0a9f87ad8820dc003b21529cdce222/workers/d1`
+- Object storage overview:
+  - `https://dash.cloudflare.com/6a0a9f87ad8820dc003b21529cdce222/r2/overview`
+
+## Guardrails for future updates
+
+- If hosting changes away from Cloudflare, update this file instead of creating a new vendor-branded skill.
+- Keep the skill provider-agnostic; keep provider specifics inside the current-topology reference.
+- Prefer control-plane inspection over repo guesses when asked “what is live right now”.
+- Do not delete DNS records, routes, buckets, or databases without first confirming which runtime resource still depends on them.
+- If browser auth expires or the dashboard requires 2FA, stop and ask the user to re-authenticate manually.

package/toolkit/skills/kaisoumail-deployment-inventory/references/stable-identity.md

@@ -0,0 +1,32 @@
+# KaisouMail stable identity
+
+## Canonical naming
+
+- Canonical project / product name: `KaisouMail`
+- Use `KaisouMail` in owner-facing summaries unless naming a specific repo path or provider resource.
+
+## Mutable implementation details
+
+These may change over time and must not be treated as the project identity:
+
+- local repo slug
+- deployment provider
+- provider-side project / service / bucket / database names
+- preview hostnames
+- provider dashboard URLs
+
+## Current repo relationship
+
+- Current local repo slug: `cf-mail`
+- Repo slug is not the canonical product name.
+
+## Writing rules
+
+- Do not rename the whole project after the current hosting provider.
+- Do not rename the whole project after one repo slug or one provider resource.
+- When an ops note mixes stable identity and runtime facts, write the stable identity first, then the current runtime mapping.
+
+## Inventory split
+
+- Put long-lived identity rules in this file.
+- Put current live deployment facts in `current-topology.md`.

package/toolkit/skills/local-merge-flow/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: local-merge-flow
+description: "Fast local delivery to merge-ready without creating a PR."
+---
+
+# Local merge flow
+
+Use only for explicit `local-merge`, `no-pr`, or a currently locked local-merge run. Generic merge/continue language cannot switch another flow into this one.
+
+## Authorization
+
+- Execute `$project-engineering-workflow` Step 1-4 and Step 5L locally.
+- Authorize local implementation, validation, signed-off commits, applicable contract sync, and fixes required by current local facts. The Agent records a Tier 1..4 review necessity assessment with no categorical rubric: Tier 1 needs no code review, Tier 2 is advisory only, Tier 3 requires fresh clear read-only-sub-agent four-lane current-head review evidence, and Tier 4 requires those lanes plus one or two selected dynamic lanes before Step 5L.
+- Do not create/update/merge a PR or push. A read-only `gh` lookup is allowed only to resolve live base/head facts.
+- Review disposition semantics come from the shared `../project-engineering-workflow/references/review-proof-short-contract.md` contract.
+- Before any Tier 3/4 lane launch, confirm Review Readiness: approved behavior, acceptance, scope, and required contracts are settled; no design decision is unresolved; and current-candidate validation plus applicable visual evidence are complete. Tier 1/2 record only their assessment and rationale.
+- When `empirical_acceptance=required`, the same readiness check requires a passed current Candidate evidence card. Missing, stale, failed, or unavailable evidence blocks Step 5L; a failed run after a comparable pass is diagnosis-only and cannot open another Repair Batch.
+- Step 5L consumes only `pre_merge` acceptance evidence bound to the Candidate SHA. This flow does not manufacture post-merge evidence: `post_merge` requires a real Merge Receipt and `merge_sha`, while `post_deploy` additionally requires a structured `deployment_identity` whose source and bound SHA match that merge. A local merge-ready state is not Flow Complete; missing deployment identity is an owner-action blocker.
+- A Design-Returning Review Finding stops ordinary repair/review convergence; resolve the design and launch fresh formal lanes for the changed candidate. A Review Observation remains report-only, and an In-Scope Review Finding is the only class that may enter the bounded Repair Batch. Missing or stale review output remains an `unchecked` evidence blocker.
+- A separately requested topic push is a narrow side path; it does not authorize PR creation.
+
+## Stop conditions
+
+1. Reach `Step 5L Ready` with current head/base validation and merge facts and stop for owner approval.
+2. After explicit approval, refresh head/base/upstream facts and merge locally with `MODE=merge`. Conflicts or required history rewrite block.
+3. Stop after merge with cleanup unperformed unless the owner explicitly selected `merge+cleanup`; cleanup is owned by `$git-cleanup MODE=local-merge`.
+
+Unrelated dirty state may be preserved through an isolated merge worktree when facts prove it will not be touched. Never move or clean the user's work merely to satisfy this flow.
+
+## Output
+
+Report local merge readiness, merge result, cleanup result when applicable, current validation/merge SHA, and the single next gate. Include recovery fields only while blocked or non-terminal.

package/toolkit/skills/multi-task-flow/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: multi-task-flow
+description: Coordinate a dependency-driven Codex task through an isolated JSON ledger, on-demand delivery-unit and task conversations, PR coordination, and an authenticated local dashboard.
+version: 2.7.2
+---
+
+# Multi-task flow
+
+## 术语约定
+
+本文统一使用以下双语标准称谓：主 Agent（main Agent）负责整个编排；交付 Agent（Delivery Agent）负责所属交付单元；任务 Agent（Task Agent）负责所属子任务。英文名称是稳定的运行时角色标识，中文名称是面向读者的正式称谓，两者不得互相删减或替换为其他别名。
+
+Use for an owner-approved multi-conversation flow with explicit task dependencies. This Skill has its own input contract and runtime lifecycle; it is independent from `$dev-plan` and does not migrate or modify existing runs. Initialization is a mutating runtime action: do not invoke this Skill for read-only review, diagnosis, code exploration, or plan-only work. The 主 Agent（main Agent） creates and manages peer delivery-unit and task conversations as needed. The 交付 Agent（Delivery Agent） owns its parent PR and child PR acceptance; the 任务 Agent（Task Agent） owns its subtask and follow PRs. The 主 Agent（main Agent） schedules; it accepts child PRs only for its own bootstrap delivery unit.
+
+Each run may contain one `bootstrap` delivery unit followed by zero or more `regular` delivery units. Bootstrap is the only main-owned unit: the bound main conversation may commit the initial SPEC/ADR/plan documents and manage the first parent PR. It uses `owner_kind: "main"`, has no delivery-unit conversation binding, and must be first. Regular units retain the delivery-unit-owned contract and require an independent 交付 Agent（Delivery Agent） conversation before activation. Parent PRs are serial by default; regular units may run in parallel only when dependencies allow it. Delivery-unit kind, ownership and delivery-unit conversation binding cannot be rewritten through ordinary delivery-unit updates or plan revisions. This release provides no in-place ownership-transfer command; an existing run retains its current ownership. Initialize the planned bootstrap before publishing its parent PR, then record workspace and publication receipts in the same main-owned workspace.
+
+This remains an active top-level flow for dependency-driven delivery. An approved run requires at least two task nodes when its topology claims multiple tasks, and the authoritative runtime ledger is the source of truth for task, group, dependency, and closeout state.
+
+## Intent and delivery contract
+
+When the owner explicitly asks to do task orchestration with this Skill, the default intent is to create or continue a formal run and deliver its dashboard. Do not silently downgrade that request to a proposal-only Markdown artifact. Use `proposal` only for explicit review, diagnosis, or plan-only requests. The four lifecycle stages are `proposal`, `initialized run`, `scheduled run`, and `completed run`.
+
+The first delivery is complete only when the authoritative ledger exists under `~/.local/share/multi-task-flow/data/runs/<run-id>/`, the run is bound to the current main conversation, the dependency graph is present, and the dashboard is opened using the Dashboard browser route showing the current revision. Markdown, Mermaid, and candidate `init-input.json` files are supporting inputs, never substitutes for the ledger or dashboard.
+
+After the owner approves implementation of a plan, all plan-internal orchestration and repository collaboration actions are authorized: task dispatch, conversation creation, worktrees, Git push, branch publication, child PR creation/update, child PR merge, notifications, checks and cut operations. A delivery-unit parent PR merge into the integration branch requires a separate `protected-approve`; release and deployment actions require their own protected approval. Plan revisions, scope expansion, target drift and new environments require fresh approval. Use `init`, `service ensure`, `service login`, and the host browser route below in that order. Keep the page open: SSE and heartbeat updates expose later revisions without normal re-navigation; navigate again only for connection or session recovery.
+
+If initialization, viewer ensure/login, or browser delivery fails, report the failed stage, exact result, and blocker. Never describe a proposal as an initialized or completed run. Continue an unfinished run already bound to the main conversation; if ownership is uncertain, pause before mutation. Record the run ID, revision, owner thread ID, and dashboard entry in the conversation.
+
+## Dashboard browser route
+
+For dashboard delivery and inspection, first inspect the current host's exposed browser capabilities. When running in ChatGPT Desktop or Codex Desktop, default to that host's available built-in browser. This dashboard-specific route takes precedence over the generic `$ego-browser` preference; it does not change the route for unrelated browser tasks. Read the exposed tool documentation and use its supported browser selection/opening interface rather than assuming a product name, browser ID or tool name proves availability.
+
+Open the single-use `service login` URL in that browser, then verify the intended run ID and current ledger revision from the rendered page. Keep the authenticated page open for updates. A successful open-tool response alone does not complete dashboard delivery. Protect the login URL as a credential.
+
+If the host exposes no usable built-in browser, record the missing capability and follow the permitted `$ego-browser` route. An opening or login failure requires diagnosis before fallback; do not silently switch browsers or reuse a consumed/expired login ticket. Obtain a fresh ticket for an authorized retry. Any Chrome or Computer Use escalation still follows `$gui-escalation-gate`, and real-program screenshots still require explicit target and scope approval. If no permitted browser can render the dashboard, report the browser-delivery blocker and stable run URL without claiming delivery succeeded.
+
+## Dev-plan integration
+
+New runs receive only this Skill's repository, delivery-unit, task, dependency, ownership and acceptance input. `init` rejects dev-plan-specific fields and does not expect a plan digest, handoff envelope, or external planning source. 任务 Agent（Task Agent） may invoke `$fast-flow` for its own direct PR, while the 主 Agent（main Agent） retains the graph, ledger, parent PR, and delivery-unit closeout responsibilities.
+
+Read `<skill>/../../skills/docs/vendor/dot-codex/specs/multi-task-flow/SPEC.md` and `<skill>/../../skills/docs/vendor/dot-codex/design/multi-task-flow/{orchestration,execution,data-and-scripts,web-template,plan-revision-and-change-audit}.md` in the dot-codex source installation for the model, contracts, and presentation requirements, not similarly named files in the target project. Use the installed Skill directory as `<skill>` in commands, never the candidate checkout unless explicitly testing it. Install dependencies with `bun install --frozen-lockfile` and build the local assets with `bun --no-install run build` from `<skill>`. Formal runs live at `~/.local/share/multi-task-flow/data/runs/`, independently of the Skill installation and `CODEX_HOME`. Read `references/shared-viewer.md` before viewer use or maintenance. Code upgrades never rewrite run data. Historical read-only runs do not require migration to upgrade the viewer; only a newly lost write capability requires exact compatibility-report approval. Owner-approved maintenance migration uses the separate service `ledger-maintenance-check` / `ledger-maintenance-apply` commands described in `references/shared-viewer.md`, retaining the original owner without impersonating it. Ordinary bound-main migration permissions are unchanged.
+
+## Plan and schedule
+
+Model atomic tasks and their predecessors first; each atomic task is indivisible for scheduling. Group sequential atoms into subtasks, then validate both graphs and explicit handoff facts. Plan one or more parent PR groups, group-specific post-merge release, deployment and verification tasks, and estimated intervals with sources and confidence. Default to three concurrent running tasks; waiting and blocked tasks release capacity. The owner approves the implementation plan once; that approval covers every action already represented by the plan, including planned repository writes. Only delivery-unit parent merges and release/deploy operations pause for a protected owner approval at their final target and evidence boundary. Do not infer dependency from group ordering or file overlap.
+
+Use the Bun CLI with one JSON object on stdin: `bun --no-install run <skill>/scripts/orchestrate.ts <command> --input -`. Its schema is in `lib/schema.ts`; the complete command and envelope contract is in the data design document. `init` is an owner-approved mutating command that binds the repository and the main conversation to a new run. It accepts only unbound `planned` groups/tasks and writes the initial ledger; it does not create group or task conversations. `migrate` is the only explicit schema v1 or schema v2/contract 1 to schema v2/contract 2 write path: it requires the bound main actor, exact run ID, request ID and expected revision, retains a complete backup, increments the ledger revision with its request record, and is idempotent only for identical canonical input. Read-only review, diagnosis, and planning must use source inspection or `show`/`view` and must not call `init` or a native conversation-creation tool. `show` reads a consistent snapshot. For each mutation supply a unique `request_id`, the current `expected_revision`, the bound actor and command payload. On conflict read the ledger and reconsider; replay the identical request ID only for the identical operation. Do not edit the ledger JSON manually. Agent-authored Markdown requirements are ordinary files under the run's `requirements/`.
+
+### Phase-aware plan revisions
+
+The Skill layout keeps executable command entrypoints in `scripts/`, reusable implementation modules in `lib/`, and regression tests in `tests/`; files in `scripts/` are the supported command surface, while `lib/` files are imported implementation details. The runtime contract in `lib/schema.ts` and its projection in `lib/contract.ts` are authoritative for plan revision semantics. The orchestration is in `planning` until the first real `task_started` event, then stays in `implementation`; dispatch claims, conversation creation, `starting` state and plan selection do not cross that boundary.
+
+Plan content is immutable after proposal. `active_plan_id` identifies the selected candidate, while `execution_plan_id` identifies the approved version that currently governs scheduling. Use `plan-propose` to submit a canonical candidate; the runtime derives `planning_revision`, `implementation_low_impact` or `implementation_high_impact`. Do not submit a self-declared change class. Planning revisions require a non-empty diff and fresh approval. Low-impact implementation revisions require a structured reason and are auto-approved. High-impact revisions require reason and evidence, keep the old execution pointer, hold only affected tasks and successors, and need `plan-approve` before scheduling under the new graph. Use `plan-abandon` to restore the old execution plan.
+
+Never rewrite a started task's boundary or runtime identity in a plan payload. Use `task-migrate` with a new planned task ID, structured reason and evidence; the old task remains in the ledger as `superseded` with its facts and events. The dashboard and `view` projection keep phase, lifecycle, candidate/execution plans, revision diff and hold reasons separate. Do not infer completion from a candidate ID, `starting`, dispatch claim or a terminal plan label.
+
+`examples/ledger-initialization/initial.json` is a synthetic, unapproved starting example, not an executable plan for a real project. Replace all example identities, dates and task details with verified facts before initialization. `examples/orchestration-viewer/ledger.ts` supplies a separate, richer synthetic dashboard example; see `examples/README.md` for the reproducible static preview and live demo.
+
+Record the run identity in the conversation. Formal data lives only at `~/.local/share/multi-task-flow/data/runs/<run-id>/`. Development and tests require an explicit isolated profile and root. Conversation IDs and run IDs are distinct. If a fork's relationship or control is uncertain, stop before dispatch, cut or merge and ask the owner when that binding is needed. An owner transfer requires an explicit owner decision, verified prior conversation state, and no unresolved operations. Never claim a second main controller based on a copied ID alone.
+
+Use `dispatch-group-claim` or `dispatch-claim`, then invoke `conversation-create` through this Skill’s CLI. The command binds the native request identity, creates and initializes the conversation through app-server, and resolves its real thread ID with the captured execution profile. An initial group/task thread ID is invalid, and an unknown result retains its claim and capacity; reconcile using actual native evidence before retrying, and ask the owner if the result cannot be established. Do not invent a thread ID or duplicate a creation. `task-update` records actual execution, waiting, blockers, and completion; `atom-update` records atoms sequentially. Ordinary blockers stay in the responsible conversation and ledger. Record key progress as a pending notification and deliver or acknowledge it using the permitted native communication tools; sent and acknowledged are distinct.
+
+An active delivery unit cannot be recorded as idle while it still has a ready, unbound contribution task; record running, waiting with task references, or blocked with a reason, then dispatch or reconcile the task.
+
+## 执行配置与 CLI 创建
+
+运行只有一个完整的 `config.execution_profile = { model, thinking }`。交付单元和任务独立覆盖；未覆盖时各自使用运行默认值。新对象按 `kind-v1` 推荐表物化配置，手动修改后保持原值；`execution-profile-recommend` 只在主人显式要求重新推荐时执行。创建后的对话内调整属于会话运行时，不回写账本，也不主动重设。
+
+使用 `execution-profile-update` 修改对象，payload 为 `{ target_type: "group" | "task", target_id, execution_profile: { model, thinking } | null }`；使用 `execution-profile-default-update` 修改默认值，payload 为 `{ execution_profile: { model, thinking } }`。所有写入带标准 owner/request/revision envelope，通过 app-server `model/list` 验证组合。认证网页复用相同 mutation contract，保留选择和 URL，并显示服务端错误。外部 source viewer 保持只读。
+
+`conversation-create` payload 为 `{ operation_id, title, prompt }`。CLI 使用参数数组和关闭的 stdin 启动 `codex exec -C <repository> --worktree --json -m <model> -c 'model_reasoning_effort="<thinking>"' <固定初始化提示词>`，完整透传已锁定配置；工作区由 Codex 创建，脚本不调用 `git worktree add`。`prompt` 是兼容保留的正式任务，只在成功结果的 `handoff.formal_prompt` 返回，首轮不执行它。收到 `thread.started` 立即记录身份；必须核验独立工作区、Codex 归属元数据、实际配置、初始 HEAD、初始化回合完成和进程正常退出后才能绑定。`project_id` 为空不单独失败。标题通过 `thread/name/set` 写入，不另开回合。绑定后创建正式派发通知并领取持久 attempt；主对话仅在 `handoff.should_send: true` 时调用内置 `send_message_to_thread`，使用返回的 `tool_request` 并对账平台回执。创建请求重放返回 `should_send: false`，不得再次派发。超时、创建后错误或证据冲突保留 unknown 和已知资源，先对账，不重复创建。只有没有已观察线程身份且回执明确 `process_started: false`、`resources_created: false` 的创建前失败才允许释放 claim；新 exec 请求不能使用历史 `thread/start` 失败回执。历史 `thread/start` 与 `create_thread` 证据继续读取，不重建已有线程或中断在途 CLI。
+
+native request ID 一旦绑定，完整创建参数（含 transport、cwd、prompt、title 和 execution_profile）即冻结；相同内容可再次绑定，不同内容复用 ID 必须拒绝。已知线程、工作区、初始 HEAD 和执行事实通过 `creation_observations` 单调保留，后续空 unknown 回执不能遗忘它们；failed 门禁不能依赖可变 transport。明确失败且已对账的请求才允许修正配置并重新 claim。未绑定 native request 的 claim 遇到配置变化会终止旧 claim，审计记录保留旧 profile、原因和新 claim 要求。
+
+旧账本缺少默认 profile 时保持只读。历史 `schema-2/contract-2` 账本若任务缺少 `execution_owner`、`conversation_policy` 或 `delivery_policy` 也保持只读，并在普通写入口返回 `HISTORICAL_LEDGER_READ_ONLY`；先用 `ledger-maintenance-check` / `ledger-maintenance-apply` 的 `action: "contract"` 仅补出缺失策略键的显式 `null`，再按需由绑定主会话显式调用 `execution-profile-migrate`，两项迁移分别携带 request ID、expected revision、源 SHA256、operation digest、维护身份、批准引用和完整备份。部分策略声明不自动补齐，PR、owner 和 lifecycle 事实也不由迁移推断。历史 `create_thread` 证据可读；新增创建通过 CLI 证据解析。
+
+## 主动通知闭环
+
+记账命令可以在 `payload.notification` 中提供 `{ "mode": "auto" | "deliver" | "none", "recipient": "owner" | { "thread_id": "..." } }`。`auto` 保留各命令现有的默认通知规则，`deliver` 明确创建主动投递意图，`none` 禁止主动投递；旧字段 `notify_main: true` 继续等价于向 `owner` 投递。
+
+记账命令先提交通知事实，再领取唯一持久 `delivery_attempt_id`，返回 `should_send`、`tool_request` 和回执身份。`notification-prepare` 与兼容名称 `notification-send` 都只领取意图，不调用 CLI `thread/resume + turn/start`。仅当 `should_send: true` 时，主对话调用内置 `send_message_to_thread`；随后用 `notification-reconcile` 写回真实平台结果，payload 包含 `notification_id`、相同 `delivery_attempt_id`、唯一 `reconciliation_id`、`outcome` 和 `provider_receipt: { provider: "codex-app-tools", evidence_ref, message_id?, recipient_thread_id, prompt_digest }`。新的原生 attempt 必须让收件线程和 prompt digest 与领取意图一致；没有回执保持 unknown，只有证实未投递才可记 failed。`codex-app-tools` 直接 `notification-deliver` 只允许领取 unknown，不能直接记录 sent/failed；兼容 `notification-sent` 不接受该 provider，原生对账必须匹配 attempt 和 provider，历史 provider attempt 不能直接套用原生回执。`sent` 表示平台接受，不能推断已读、处理或开工。
+
+相同请求重放返回 `should_send: false`，不能再发送。持久 unknown attempt 跨工具调用占用通知，不依赖常驻文件锁。并发领取或未解决 attempt 禁止再次发送；unknown 必须先对账。历史外部发送的文件锁仍保护其在途回合，遇到 `NOTIFICATION_IN_FLIGHT` 不得改写状态解锁。只有收件会话可调用 `notification-ack`，main 不能代确认。使用 `notification-reconcile --input -` 的查询形式恢复 pending、failed、unknown 和长期未确认的 sent；明确 failed 才可创建新 attempt。
+
+## 开工前基线
+
+创建时只记录 `native_evidence.initial_head`；它不是开发基线。正式派发包含 run/target、仓库、归属、范围、基线与验收要求。交付 Agent（Delivery Agent）必须 fetch 已核验远端的主干并记录真实 SHA 和 fetched_at，任务 Agent（Task Agent）继承所属交付单元当前父分支已核验 SHA。仅允许在本次新建、干净且 Codex 归属一致的工作区对齐并建立工作分支。fetch 失败、脏工作区或归属不明必须阻塞，不覆盖文件，不使用缓存替代 fetch。
+
+Agent 提供资源证据，由主对话 `resource-update` 注册 active worktree/branch；目标 owner 调用 `lifecycle-record` 的 `workspace_ready`，新 CLI dispatch 还需 `baseline: { sha, head, clean: true, source, fetched_at? }`，SHA 必须与 HEAD 相同，交付单元 fetched_at 不早于 dispatch，任务 SHA 必须匹配交付单元 current_sha。开发基线存于 dispatch 的 `development_baseline`，独立保留创建初始 HEAD。任务和交付单元协调进入 running 均受此门禁保护；历史已绑定对话不追加此要求。
+
+Contract-3 的开发基线由 `development-baseline-sync` 明确提交。首次同步使用 `mode: "initial"`，在 dispatch、native evidence、workspace、branch、owner、resource 和 lineage 均已核验后建立空 baseline；之后每次父分支 lineage 通过 `group-base-reconcile`、合并或 cut 推进，都先使用 `mode: "refresh"` 携带 previous receipt 和匹配的 lineage event，再重新调用 `lifecycle-record`。`initial_head` 只表示 native creation 时的初始 HEAD，development baseline receipt 表示本次 workspace evidence 已对应的可工作 SHA，二者不能互换。同步只记录 Agent 已完成的证据，不 fetch、reset、rebase、更新 provider、创建 PR、改变 owner、替代 task-base 或收口 cut。
+
+## PRs and cuts
+
+Before every PR merge performed by a task or group Agent, use `merge-claim`; verify the actual PR identity, target, current head/base, applicable checks and task-owned quality proof using the bound Git provider. Child PR merges are covered by the implementation approval. A delivery-unit parent PR merge requires a prior `protected-approve` for that exact delivery unit. A script input is an Agent's report, not independent provider evidence. After the external call, query the provider and use `merge-resolve` to record a matching receipt; if the result is uncertain use `unknown`, retain the occupation, and reconcile before any retry. Do not claim a failed operation from an unverified error. A task Agent owns its child PR quality proof and merge; the delivery coordinator owns only parent PR integration. When the original parent PR has already merged and a later mainline follow-up PR carries remaining delivery-unit changes, the coordinator uses `merge-claim` with `mode: "parent-followup"`, records the original parent PR and merge SHA, and resolves the follow-up PR against the integration branch; this advances the delivery-unit merge SHA without rewriting the original parent receipt.
+
+When a child PR has a conflict or failed checks, the task Agent must first determine whether its own changes caused the problem. Self-caused problems stay with the task Agent and must be fixed in the same task and PR. A confirmed external problem is escalated with diagnosis evidence, impact, and candidate orchestration changes to the main Agent; the main Agent asks the owner before creating a separate repair contribution task or changing dependencies. A changed base is always the task Agent's responsibility: rebase, revalidate, and refresh the task base evidence before retrying. Normal execution never transfers a task workspace or PR between Agents.
+
+For an approved dynamic cut, `cut-claim` fences new merges and waits for prior occupations, then `cut-apply` records the current verified parent SHA and assignment changes atomically. Finished development work stays in the cut delivery unit; unfinished development subtasks move to the next default delivery unit with their existing conversations. The original delivery unit's release, deployment and verification tasks remain there and run after its parent PR merges. The next parent branch must include the actual previous parent merge before its development PRs merge. Follow PRs stay attributed to their original delivery unit; refresh its current SHA and review/check evidence when its branch advances, without changing cut ownership. An external provider `update-branch` that advances an established parent branch is recorded only through `group-base-reconcile` with matching previous/new SHA, branch, parent PR, provider and explicit update-branch evidence; it is not a merge or follow PR. The 任务 Agent（Task Agent） owning the follow PR notifies the 主 Agent（main Agent）, who coordinates needed rebases with affected unfinished 任务 Agent（Task Agent）.
+
+A delivery unit closes only after its parent merge, CI on the merged SHA, planned post-merge tasks and known follow PRs complete. The 主 Agent（main Agent） may record `run-complete` only after all delivery units close and no operation or known follow PR remains unresolved. `resource-update` tracks each resource independently. Retain run data and any needed service until the owner confirms cleanup; resolve and clean only this run's exact resources.
+
+## Dashboard
+
+Use the installed user service through `bun --no-install run <skill>/scripts/service.ts <command> --input -`. Before viewer use, call `status`. If it reports `installed: false`, stop and guide the owner through approval: explain that installation writes the fixed user data root, reserves the configured loopback port, creates the user-level launchd service, and does not require administrator access; ask for explicit approval for this exact installation. Do not call `install` until that approval is received. After approval, build or select the verified bundle, show the exact source path, and call `install`; then call `ensure` with `{ "run_id": "<run-id>", "thread_id": "<main-thread-id>", "api_version": 1 }`. All projects and conversations share its stable `http://127.0.0.1:<configured-port>/runs/<run-id>/` entry. The CLI returns structured `ok/code/result`; `ensure` never builds, installs, upgrades or selects another port. Ordinary Agents may ensure, renew, release, inspect and obtain login entry points, but must not trigger installation, upgrade, rollback, credential maintenance or import without owner authorization. After `ensure`, call `login` and open its single-use URL using the Dashboard browser route when delivering or viewing a run.
+
+The user-level launchd service owns the background lifecycle independently of conversations, requires no administrator access, and does not start at login. Independent main-thread/run leases last 60 minutes; related successful orchestration commands renew usage. Explicitly renew during long waits. Connected browser pages renew every 60 seconds with a five-minute TTL. Release only this run's Agent lease at closeout; never stop the shared service or release other runs' leases. The final expired lease triggers exit without deleting data. Next `ensure` recovers crashes. An unfinished ledger does not keep a process alive.
+
+Use `login` with an optional `run_id` to obtain a single-use, 60-second browser entry. Treat that URL as a credential and do not put it into ordinary logs, ledgers or PRs. Stable run/plan links contain no credentials. Once logged in, `/` lists runs and `?plan=<plan-id>` selects a historical plan. The service validates Host/Origin and uses HttpOnly/SameSite browser sessions. For unavailable service links, call `ensure` first. Only currently subscribed runs hold filesystem watchers.
+
+Per-run custom HTML/CSS/JS remains supported under `data/runs/<run-id>/view/`. Include `view.manifest.json` with `{ "api_version": 1, "frontend_contract": 1 }`. Missing or incompatible declarations preserve files and fall back to the shared template with a warning. Relative API/resource paths stay within `/runs/<run-id>/`; this is one same-user trust domain. Keep dependency graph, planned/actual timelines, group attribution, state, blockers, PRs, requirements and real conversation links. Conversation links use real IDs and canonical `codex://threads/<thread-id>` anchors.
+
+For examples and external fixtures, use the generic read-only source-directory viewer. It accepts an absolute source run-data directory, validates its ledger and filesystem identity, assigns a random `view-<id>` presentation identity, and serves it through the same singleton. It reads the source in place, never publishes it under formal `data/runs`, never permits orchestration writes, and removes the mapping when its explicit browser view lease expires. Do not add an example-specific service mode or treat a source view as a real run.
+
+`serve.ts` remains an internal synthetic/legacy validation helper, not the formal run entry or an upgrade fallback. The explicitly installed shared user service uses the system-service exception for its background lifecycle. See `references/shared-viewer.md` for fixed-port ownership, compatibility, maintenance and migration recovery.