taskchef 8.7.0 → 9.0.0

package/docs/dashboard-ui.md

@@ -1,40 +0,0 @@
-# Dashboard UI baseline
-
-Board and List are the visual baseline for dashboard pages. New pages should
-inherit the Mantine theme in `src/dashboard/react/App.tsx` and the shared CSS
-properties in `src/dashboard/react/styles.css` before adding page-specific
-rules.
-
-- Use `--taskchef-page-max-width`, `--taskchef-page-gutter`, and the
-  `.taskchef-main` shell for the outer page. Use `.taskchef-content` for
-  readable single-column content; Board may use the full shell width for its
-  horizontal lanes.
-- Use Mantine `h5`, `sm`, and `xs` sizes for section headings, body text, and
-  supporting text. Reserve larger headings for views that establish a distinct
-  document hierarchy.
-- Selects inherit the compact `xs` dashboard size from the shared Mantine
-  theme. New pages get the same 30 px control height and 12 px control text
-  without page-specific selectors. Keep short, related selects in one compact
-  row when they remain readable at narrow widths; give the field with longer
-  values the larger share of the row.
-- Use `.taskchef-section`, `p="sm"`, and `gap="sm"` for bordered page sections.
-  Keep intentional Board and List differences, such as lane width and card
-  excerpts, in their existing component classes.
-
-Check a dashboard page at desktop and narrow widths. Confirm keyboard focus,
-control operation, reachable overflow, and a clean browser console.
-
-### Latest-turn request and response
-
-Running local Codex cards show the current request. Other cards show the latest
-turn's response. Cards use a plain two-line preview without request bubbles.
-Details pairs the same turn's request and response, each initially capped at
-three lines with a Show more control. The request uses a right-aligned bubble.
-Actual scheduled requests show their recorded instructions with a clock;
-human follow-ups in scheduled chats use the normal request bubble.
-Quoted selections render as Markdown quotes. File and image references show
-attachment names, while generated request headings and context metadata are
-removed from the display. Recorded input remains unchanged.
-
-Earlier-turn PR fallbacks remain separate from this content: the status popup
-shows `(Earlier turn PR)` below the PR link, aligned with the other row text.

package/docs/firstmate-taskchef-comparison.md

@@ -1,283 +0,0 @@
-# FirstMate and TaskChef: architecture and fit
-
-> **Research, not contract.** This document compares two version-scoped
-> implementations. It does not define TaskChef behavior; the normative source
-> is the [TaskChef specification](spec.md). Recheck the linked sources before relying on these
-> conclusions after the access date.
-
-For TaskChef installation and everyday use, start with the
-[README](../README.md). For its current implementation flow, see
-[TaskChef workflows](workflows.md).
-
-## Scope and sources
-
-**Access date:** 2026-08-25
-
-**TaskChef scope:** the TaskChef 7 contract in this repository revision.
-Current behavior was verified against the [specification](spec.md),
-[workflows](workflows.md), packaged skills,
-[MCP implementation](https://github.com/favoyang/taskchef/blob/main/src/mcp.js),
-[workspace implementation](https://github.com/favoyang/taskchef/blob/main/src/workspace.js),
-CLI, dashboard, and tests.
-
-**FirstMate scope:**
-[`kunchenguid/firstmate`](https://github.com/kunchenguid/firstmate) at commit
-[`038d0f7`](https://github.com/kunchenguid/firstmate/tree/038d0f7ec6ba7238a151722931434dcf06ff37c4),
-the tip of its official `main` branch when accessed. Repository history already
-identified Kunchenguid's project as the intended FirstMate; no competing local
-reference pointed to another project.
-
-Primary FirstMate sources:
-
-- [README](https://github.com/kunchenguid/firstmate/blob/038d0f7ec6ba7238a151722931434dcf06ff37c4/README.md)
-  for product goals, installation, features, and supported harnesses;
-- [AGENTS.md](https://github.com/kunchenguid/firstmate/blob/038d0f7ec6ba7238a151722931434dcf06ff37c4/AGENTS.md)
-  for the coordinator's operating contract, authority, delegation, supervision,
-  and delivery rules;
-- [Architecture](https://github.com/kunchenguid/firstmate/blob/038d0f7ec6ba7238a151722931434dcf06ff37c4/docs/architecture.md)
-  for watcher, session backend, worktree, state, and recovery mechanics;
-- [Configuration](https://github.com/kunchenguid/firstmate/blob/038d0f7ec6ba7238a151722931434dcf06ff37c4/docs/configuration.md)
-  for operational-home state, project modes, profiles, and extension settings;
-- [Codex App boundary](https://github.com/kunchenguid/firstmate/blob/038d0f7ec6ba7238a151722931434dcf06ff37c4/docs/codex-app-backend.md)
-  for the current limit that Codex desktop is not a selectable FirstMate runtime
-  backend;
-- [Vision](https://github.com/kunchenguid/firstmate/blob/038d0f7ec6ba7238a151722931434dcf06ff37c4/VISION.md)
-  for the intended single-liaison, durable-fleet experience.
-
-Unless labeled **Inference** or **Recommendation**, statements below are facts
-supported by those version-scoped sources or the TaskChef 7 codebase.
-
-## Executive comparison
-
-**Fact:** TaskChef is a Codex-native dispatch and task-index layer. It routes a
-request to visible Codex tasks, returns immediately, and lets the user work with
-each executor directly. It stores one latest task snapshot and offers read-only
-reports and a local dashboard.
-
-**Fact:** FirstMate is an agent distribution for running a supervised crew. The
-user talks to one primary coordinator, which dispatches workers into isolated
-worktrees and visible session backends, watches meaningful state, escalates
-decisions, follows configured delivery modes, and reconciles durable fleet state
-after restart.
-
-**Inference:** The products overlap at intake, project routing, parallel task
-creation, and observability. Their central responsibility boundary differs:
-TaskChef hands control to native Codex tasks; FirstMate retains coordination
-responsibility until an outcome is landed, transferred, or safely preserved.
-
-## Architecture at a glance
-
-| Dimension | TaskChef 7 | FirstMate at `038d0f7` |
-| --- | --- | --- |
-| Primary goal | Put multi-project work into the right visible Codex task and make it findable later. | Let one person direct a supervised crew across projects through one liaison. |
-| Product form | Codex plugin: five skills, local MCP server, data CLI, and loopback dashboard. | Cloneable agent distribution: instructions, internal skills, scripts, policies, and private on-disk state. |
-| Runtime | Native Codex desktop tasks are the executors and live source of truth. | Harness-driven workers in tmux by default, with documented alternative session backends; Codex can be a harness, but Codex desktop is not a runtime backend. |
-| Coordinator lifetime | Dispatcher returns immediately and does not supervise. | First mate remains active and uses watcher/guard mechanisms to supervise meaningful events. |
-| Project isolation | Delegates to the configured Codex project; isolation follows native Codex/project behavior. | Ship and scout workers require separate Treehouse- or backend-managed worktrees. |
-| Durable state | `taskchef.json` plus latest snapshots in `tasks.jsonl`. | Backlog, briefs, reports, task metadata, status-event logs, decisions, endpoint records, and configuration under an operational home. |
-
-## Goals and user experience
-
-### TaskChef
-
-**Fact:** The user submits work in the dispatcher or explicitly invokes
-`$taskchef-delegate` elsewhere. TaskChef creates independently openable Codex
-tasks and returns links. The user opens those tasks for questions, approvals,
-follow-ups, and delivery.
-
-**Strength:** This preserves the familiar Codex task model and makes delegation
-transparent. There is little new runtime or policy to learn.
-
-**Limitation:** Several active executors still mean several conversations. A
-dispatcher report reduces search cost but does not own supervision or recovery.
-
-### FirstMate
-
-**Fact:** The user talks to the first mate as the single liaison. Crewmates do
-project work; the first mate reads projects, supervises the fleet, reconciles
-direct user intervention, brings forward decisions, and reports outcomes.
-
-**Strength:** The user can look away while one coordinator retains context and
-responsibility across a larger fleet.
-
-**Limitation:** The experience requires more local tooling, state, policy, and
-operational machinery than a simple dispatcher. The coordinator's summaries
-also insert an interpretation layer between user and worker.
-
-## Task identity and persistence
-
-### TaskChef
-
-**Fact:** `prepare_dispatch` allocates a TaskChef UUID and exact correlation
-marker. `record_task` persists the marked instruction before native task
-creation. The executor then reads its own `CODEX_THREAD_ID` and calls
-`link_task`; the dispatcher neither searches recent tasks nor repairs identity.
-The task record keeps one immutable intent/project snapshot plus the latest
-identity and semantic result fields.
-
-**Fact:** Linking accepts one atomic null-to-canonical-Codex-UUIDv7 transition.
-Exact retries are idempotent, conflicts fail, and link interruption remains
-visibly pending. Schema 9 lifecycle callbacks use a required `turnRef`: the
-native Codex turn ID when available, or a retained UUID with `turnId: null`.
-
-### FirstMate
-
-**Fact:** FirstMate assigns a task identity used across backlog entries, briefs,
-worker endpoint metadata, worktrees, status events, reports, and delivery
-artifacts. Durable disk records plus live backend state allow session-start and
-watcher reconciliation.
-
-**Inference:** TaskChef's identity model is narrower and easier to audit because
-it binds one record to one native executor. FirstMate's richer identity graph is
-necessary for supervision and recovery, but creates more reconciliation paths
-and invariants.
-
-## Delegation and concurrency
-
-### TaskChef
-
-**Fact:** The delegation skill splits only independently useful outcomes,
-routes each to exactly one configured project, records before one native
-creation call, and returns immediately. Multiple dispatchers and executors may
-share the workspace; locking and atomic JSONL replacement serialize mutations.
-
-**Fact:** TaskChef itself does not allocate worktrees, choose worker models,
-schedule dependencies, retry failed execution, or enforce a repository delivery
-mode. Those belong to Codex and each target project's instructions.
-
-### FirstMate
-
-**Fact:** FirstMate distinguishes ship work from scout investigation, prepares
-durable task material, selects a configured harness/profile, and spawns workers
-in isolated worktrees. Independent work may run concurrently; dependencies and
-unsafe shared state can hold work back.
-
-**Fact:** Supported runtime backends and harness adapters are explicit
-extension surfaces. The reference path uses tmux, while other documented
-backends have different verification or experimental status.
-
-## Status and results
-
-### TaskChef
-
-**Fact:** Persisted statuses are `working`, `needs_input`, `completed`, and
-`failed`. Executors report
-`working` at turn start and a semantic state before ending. Schema 9 preserves
-the paired turn timeline and semantic-only compatibility results while a newer
-turn is working. If a terminal report is lost, the next valid working start
-closes the predecessor with a timeline-only `interrupted` outcome rather than
-semantic `failed`.
-`needs_input` is reserved for a real semantic decision, not a native approval
-prompt.
-
-**Fact:** The copilot skill explains normalized cached briefs by default and
-uses live Codex metadata only for an explicit fresh/live request or a focused
-meaningful contradiction. It recommends safe next actions, never polls, and
-never writes inferred state.
-
-### FirstMate
-
-**Fact:** FirstMate combines durable task/backlog state, append-only status
-events, live backend evidence, validation/delivery artifacts, and watcher wake
-records. Its supervision path distinguishes historical event logs from current
-worker state and escalates meaningful decisions, failures, stalls, and delivery
-milestones.
-
-**Inference:** TaskChef optimizes for a small truthful cache and bounded reads;
-FirstMate optimizes for continuity and active coordination. Neither data model
-can be substituted for the other without changing product responsibility.
-
-## UI and observability
-
-### TaskChef
-
-**Fact:** The loopback dashboard watches `tasks.jsonl`, streams stable validated
-snapshots, filters and orders tasks, shows notifications and details, and opens
-a task directly in Codex when its stored thread ID has a supported UUID shape.
-This navigation check does not prove schema 4 or 5 self-link provenance. The
-dashboard does not refresh native task state, submit replies, or show
-transcripts or token usage.
-
-**Fact:** The user can also ask TaskChef copilot for a concise cached brief or
-focused live verification, or inspect the data CLI. Executor work remains
-visible in normal Codex desktop tasks.
-
-### FirstMate
-
-**Fact:** Workers run in visible session backends that the user can inspect or
-intervene in, while the first mate remains the primary interface. Fleet views,
-durable status/decision records, and watcher-driven wakes provide the
-coordinator's operational observability.
-
-**Fact:** FirstMate currently documents Codex desktop as an integration
-boundary, not a selectable worker backend. Codex CLI can participate through a
-harness adapter.
-
-## Integrations and extension model
-
-| Area | TaskChef | FirstMate |
-| --- | --- | --- |
-| Codex | Built around native Codex projects, tasks, thread reads, and desktop deep links. | Codex is one verified harness; desktop tasks are not its worker runtime. |
-| GitHub | Configured repository URLs aid routing; delivery remains the executor project's concern. | GitHub CLI, PR state, and configured delivery modes are part of supervised shipping workflows. |
-| Skills | Five plugin skills with narrow bootstrap, dashboard recovery, delegate, executor, and conversational coordination responsibilities. | Internal firstmate-only skills plus standalone public skills; AGENTS.md routes conditional procedures. |
-| MCP | Four primary local TaskChef tools plus one deprecated compatibility alias own deterministic identity and state writes. | FirstMate describes itself as an agent distribution rather than an MCP product; deterministic behavior lives largely in scripts. |
-| Runtime extensions | Extend plugin skills/MCP/CLI/dashboard or compose native Codex capabilities. | Add or verify harness adapters, session backends, dispatch profiles, operational scripts, and optional integrations. |
-
-## Trust and security boundaries
-
-### TaskChef
-
-**Fact:** The MCP server is local and does not receive transport-authenticated
-Codex caller identity. Executor thread and turn IDs are cooperative assertions.
-Validation prevents accidental parent/provisional identity capture, duplicate
-identity use, stale-turn replacement, and malformed record mutation; it does
-not resist a deliberately forged local MCP caller.
-
-**Fact:** The dashboard binds to loopback, has no browser authentication, and
-uses Host/Origin checks for open-in-Codex actions. It must not be exposed
-through a proxy or tunnel. Workspace mutation uses one lock and atomic writes.
-
-### FirstMate
-
-**Fact:** The first mate is normally read-only over project clones; crewmates
-make project changes in isolated worktrees. Merge, destructive action, and
-standing autonomy are governed by explicit captain authority and per-project
-delivery modes. Scripts validate task endpoints, homes, worktrees, and state
-before sensitive lifecycle actions.
-
-**Inference:** TaskChef has a smaller local attack and failure surface but
-delegates repository safety to Codex and project policy. FirstMate explicitly
-owns more delivery and process safety, which improves centralized control while
-expanding the trusted script, state, backend, and credential surface.
-
-## Strengths, limitations, and best fit
-
-| Product | Strongest when | Less suitable when |
-| --- | --- | --- |
-| TaskChef | You already use Codex desktop; want one multi-project inbox; prefer direct executor conversations; value a small inspectable history; want minimal runtime machinery. | You want one liaison to supervise, recover, coordinate decisions, enforce delivery modes, or return only consolidated outcomes. |
-| FirstMate | You want one coordinator to run many visible workers; need isolated worktrees, durable fleet recovery, proactive supervision, and consistent delivery policy across projects. | You want native Codex desktop tasks as the core UI; prefer minimal setup and state; or want to interact directly with every executor without a coordinator layer. |
-
-## Recommendations
-
-**Recommendation:** Choose TaskChef when the problem is routing and task
-findability. Choose FirstMate when the problem is sustained supervisory
-attention and delivery coordination.
-
-**Recommendation:** Do not casually nest the systems. A FirstMate coordinator
-behind every TaskChef executor, or TaskChef dispatch inside every FirstMate
-worker, adds identity, authority, and recovery boundaries without a clear owner.
-If composition is necessary, define exactly one supervisory layer and treat the
-other as a leaf runtime or intake adapter.
-
-**Recommendation:** TaskChef can borrow outcome-oriented reporting ideas
-without becoming a supervisory runtime. Useful candidates are clearer
-completion summaries and an explicit user-approved result-to-follow-up handoff.
-They should preserve native Codex task ownership, bounded reads, and the absence
-of background supervision.
-
-**Inference:** Reproducing FirstMate's restart-proof crew management inside
-TaskChef would not be a small feature. It would require new durable state,
-worker liveness contracts, worktree ownership, decision queues, delivery
-authority, retry/recovery policy, and a continuously supervised runtime. That
-would change TaskChef's product category and should be evaluated as a separate
-architecture rather than an incremental dashboard enhancement.