From d62e8f967ef0f6f97e073e0e09140412ff4b2e61 Mon Sep 17 00:00:00 2001 From: Anthony Franco Date: Wed, 27 May 2026 11:23:22 -0600 Subject: [PATCH 1/4] Oz design brief + ADR-0008: 5-section nav, runs/priorities folded into Dashboard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Correct the Oz control-plane IA to match the founder's stated layout: - Left nav is exactly five sections — Dashboard, Workspaces, CLIs, Personas, Settings. No standalone Runs or Priorities pages. - Dashboard is built around the Oz chat as the command center; priorities and runs are supporting panels inside it (Oz watches runs from the Dashboard). - Design prompt rewritten to design from the brief alone (don't reuse the current shipped oz-dashboard UI), which is what caused the prior drift. - ADR-0008: five surfaces + new decision on Dashboard composition; six-section layout recorded under rejected alternatives. v0.4 priority work items realigned. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../0008-oz-control-plane-architecture.md | 4 +- .../v0.4-oz-control-plane/README.md | 11 ++--- docs/oz-design-brief.md | 43 ++++++++++--------- 3 files changed, 32 insertions(+), 26 deletions(-) diff --git a/cocoder/decisions/0008-oz-control-plane-architecture.md b/cocoder/decisions/0008-oz-control-plane-architecture.md index 852fe5d..571e851 100644 --- a/cocoder/decisions/0008-oz-control-plane-architecture.md +++ b/cocoder/decisions/0008-oz-control-plane-architecture.md @@ -20,7 +20,8 @@ v0.1 ships CoCoder terminal-only, and the dogfood loop now works end to end: lau 4. **GUI ⇄ Oz parity.** Every GUI action (launch, reorder, edit) is also expressible as an Oz instruction, and the reverse; the two stay in sync (e.g. priorities are drag-reorderable in the GUI *and* reorderable by asking Oz). 5. **Orchestration sessions execute externally.** Oscar/Bob/etc. run in iTerm today (an embedded Electron terminal harness later). Oz observes and controls them — status, transcript, evidence, stop, attach — but does not embed the live terminals yet. 6. **Persona execution model.** Each persona binds to a **CLI (adapter) + model** (with a `default` option that defers to the CLI's own default); a persona may delegate to **sub-agents/services that each independently select CLI + model** (a configuration hierarchy); each persona has a **visible | headless** run mode. Oz itself is headless. -7. **Oz surfaces** (top-level navigation), never exposing raw JSON: **Dashboard** (workspace picker, Oz chat, priorities with drag-reorder + an "ad-hoc run" launcher above the list), **Workspaces** (roots + roles), **CLIs** (register + Test), **Personas** (CLI/model + sub-agent hierarchy + visible/headless + "new persona via priority"), **Runs** (list + detail), **Settings** (human-friendly forms only). +7. **Oz surfaces** — exactly **five** top-level navigation items, never exposing raw JSON: **Dashboard**, **Workspaces** (roots + roles), **CLIs** (register + Test), **Personas** (CLI/model + sub-agent hierarchy + visible/headless + "new persona via priority"), **Settings** (human-friendly forms only). There is no standalone Runs page and no standalone Priorities page. +8. **The Dashboard is the operator's hub, built around the Oz chat as the command center.** The Oz conversation is the primary surface; **priorities** (ordered list, drag-reorder, + an "ad-hoc run" launcher above the list) and **runs** (what's running now / recent, with run detail — transcript, evidence, status, stop, attach — opening in place) are **supporting panels inside the Dashboard**, not separate screens. This follows from Oz being the per-workspace watcher (decision 3): the founder watches and drives runs from the Dashboard, through Oz. ## Consequences @@ -34,3 +35,4 @@ v0.1 ships CoCoder terminal-only, and the dogfood loop now works end to end: lau - **Oz as a passive status board** (buttons only; chat advisory) — rejected; the founder chose chat-as-primary-command-interface. - **Embed live orchestration terminals in Oz now** — deferred to the Electron terminal harness; keeping sessions external in iTerm keeps v0.x shippable. - **Per-tool screens with no unifying control plane** — rejected; Oz is the single operator surface. +- **Six-section nav with standalone Runs + Priorities screens** (an earlier draft of this ADR / `docs/oz-design-brief.md`) — rejected; it mirrored the current shipped app rather than the founder's intent. Runs and Priorities are panels inside the Dashboard, because Oz watches runs and the founder works from the Dashboard conversation. diff --git a/cocoder/priorities/v0.4-oz-control-plane/README.md b/cocoder/priorities/v0.4-oz-control-plane/README.md index 0d8b6e9..d927634 100644 --- a/cocoder/priorities/v0.4-oz-control-plane/README.md +++ b/cocoder/priorities/v0.4-oz-control-plane/README.md @@ -10,19 +10,20 @@ Turn Oz into a real **operator control plane**: a per-workspace, in-dashboard he ## Architecture (decided) -- [ADR-0008](../../decisions/0008-oz-control-plane-architecture.md) — Oz control-plane architecture (Oz persona model, command + watch, GUI⇄Oz parity, external orchestration sessions, persona exec model incl. visible/headless, the six surfaces). +- [ADR-0008](../../decisions/0008-oz-control-plane-architecture.md) — Oz control-plane architecture (Oz persona model, command + watch, GUI⇄Oz parity, external orchestration sessions, persona exec model incl. visible/headless, the five surfaces with runs + priorities folded into the Dashboard). - [ADR-0007](../../decisions/0007-workspace-files-and-multiroot-description.md) (revised 2026-05-27) — root-role taxonomy primary / writable / read-only. - Screen/flow brief + design prompt: [`docs/oz-design-brief.md`](../../../docs/oz-design-brief.md) (intent; refined by the claude.ai/design output). ## Work items (provisional — refine after design output lands) -1. **Dashboard** — workspace picker, in-app Oz chat (primary command interface), priorities list with **drag-and-drop reorder** + an **ad-hoc "run without a priority"** launcher. +1. **Dashboard** — the operator's hub, built around the **Oz chat as the command center** (primary command interface). Supporting panels *inside* the Dashboard: **priorities** list with **drag-and-drop reorder** + an **ad-hoc "run without a priority"** launcher; **runs** (what's running now / recent) with run detail (live transcript / evidence / status / stop / attach) opening in place as Oz's window into externally-running iTerm sessions. No standalone Runs or Priorities pages. 2. **Workspaces** — add/edit workspaces (name + description) and roots with the three roles (primary / writable / read-only); plumb `role` as a first-class registry field (the registry entry schema already `.passthrough()`es — extends WS-DESC work). 3. **CLIs** — register adapters + a **Test** button returning success or the exact error. 4. **Personas** — per-persona **CLI + model** (with `default`), **sub-agent/service CLI+model hierarchy**, **visible/headless** run mode; list defaults incl. Oz; "create a new persona via a priority." -5. **Runs** — list + run detail (live transcript / evidence / status / stop / attach) as Oz's window into externally-running iTerm sessions. -6. **Oz oversight / debugger** — Oz as live watcher of all workspace runs; the Orchestrator Debugger surface (reference: CoBuilder `ORCH DEBUGGER`); terminal-state awareness (the daemon already refuses mutations on terminal runs — surface it). -7. **Settings** — human-friendly only, never JSON; extensible. +5. **Oz oversight / debugger** — Oz as live watcher of all workspace runs (surfaced in the Dashboard runs panel); the Orchestrator Debugger surface (reference: CoBuilder `ORCH DEBUGGER`); terminal-state awareness (the daemon already refuses mutations on terminal runs — surface it). +6. **Settings** — human-friendly only, never JSON; extensible. + +Note: the left nav is **five sections** — Dashboard, Workspaces, CLIs, Personas, Settings. Runs and Priorities are Dashboard panels, not top-level pages (corrects the earlier six-section draft). ## Open questions diff --git a/docs/oz-design-brief.md b/docs/oz-design-brief.md index ed984f6..7d5cc45 100644 --- a/docs/oz-design-brief.md +++ b/docs/oz-design-brief.md @@ -3,7 +3,7 @@ **Status:** intent — pending the claude.ai/design output, then implementation. **Decides nothing on its own:** the settled architecture is in [ADR-0008](../cocoder/decisions/0008-oz-control-plane-architecture.md) (Oz control-plane model) and [ADR-0007](../cocoder/decisions/0007-workspace-files-and-multiroot-description.md) (root roles). This file captures the **screen/flow brief** and the **verbatim design prompt** used to generate the Oz UI, so the intent is durable and feeds implementation under the `v0.4-oz-control-plane` priority. -Authored 2026-05-27. Audience: technical founder/operator. Visual styling is owned by the claude.ai/design system and is intentionally unspecified here. +Authored 2026-05-27. Revised 2026-05-27 to match the founder's stated layout: a **five-section** left nav (Dashboard · Workspaces · CLIs · Personas · Settings) with **runs and priorities folded into the Dashboard**, and the **Oz chat as the command center** — superseding the earlier six-section draft that mirrored the current app (standalone Runs + Priorities screens). Audience: technical founder/operator. Visual styling is owned by the claude.ai/design system and is intentionally unspecified here. --- @@ -12,7 +12,7 @@ Authored 2026-05-27. Audience: technical founder/operator. Visual styling is own ``` # Design brief: "Oz" — the control plane for CoCoder -You have NO prior context on CoCoder. Read this fully, then (1) map the user flows, (2) design each screen, (3) define states for each. Use your existing design system for all visual styling — this brief is about information architecture, flows, screens, components, and data, not aesthetics. +You have NO prior context on CoCoder, and you must NOT reuse any existing CoCoder UI as a reference — design from this brief alone. Read it fully, then (1) map the user flows, (2) design each screen, (3) define states for each. Use your existing design system for all visual styling — this brief is about information architecture, flows, screens, components, and data, not aesthetics. ## What CoCoder is CoCoder is a local, self-improving AI software-orchestration engine for a technical founder. Instead of coding directly, the founder directs a small team of AI "personas" (each backed by a coding CLI like Claude Code, Codex, or Cursor) that plan, build, test, and review software across one or more code repositories. Work is organized into prioritized units; the AI team executes them as "runs" the founder supervises. @@ -20,6 +20,10 @@ CoCoder is a local, self-improving AI software-orchestration engine for a techni ## What you're designing: Oz Oz is the control plane — the single app where the founder runs the whole operation. The audience is a technical founder/operator comfortable with terms like run, persona, CLI, root, priority. Design it as a desktop-class web app (persistent left-side navigation; will later be wrapped in Electron). Never show raw JSON anywhere — always human-friendly forms, tables, and controls. +## Navigation — exactly five top-level sections +The left nav has FIVE items and only these: Dashboard, Workspaces, CLIs, Personas, Settings. +- There is NO standalone "Runs" section and NO standalone "Priorities" section. Both live INSIDE the Dashboard (see below). Do not invent a separate Runs page or Priorities page. + ## Core concepts (the data model you're designing around) - Workspace — a named, described project context. It bundles one or more root folders. Everything in Oz is scoped to the currently selected workspace. There can be many workspaces. - Root folder — a directory in a workspace. Each root has: Name, Path, and a Role: @@ -33,23 +37,25 @@ Oz is the control plane — the single app where the founder runs the whole oper - Oz — itself a headless persona: the in-app chatbot + watcher described below. ## The Oz interaction model (important) -- Oz is an in-dashboard, headless chatbot and the primary command interface: the founder converses with Oz to do everything — launch runs, add/reorder priorities, kick off ad-hoc tasks (code reviews, refactors, research), and ask for status. GUI controls (buttons, drag-drop) are shortcuts for the same actions Oz can take — both must exist and stay in sync. -- Oz is also the primary watcher/interface for all runs in the selected workspace: it monitors every run and surfaces progress, decisions it needs from the founder, and results — all inside Oz. +- Oz is an in-dashboard, headless chatbot and THE primary command interface: the founder converses with Oz to do everything — launch runs, add/reorder priorities, kick off ad-hoc tasks (code reviews, refactors, research), and ask for status. GUI controls (buttons, drag-drop) are shortcuts for the same actions Oz can take — both must exist and stay in sync. +- Oz is also the primary watcher/interface for all runs in the selected workspace: it monitors every run and surfaces progress, decisions it needs from the founder, and results — all inside the Dashboard. - There is one Oz per workspace. Switching the workspace switches the Oz conversation, its priorities, and its runs. - The actual orchestration sessions execute externally (today in iTerm terminal windows; later an embedded Electron terminal). Oz does not embed those live terminals — it observes/controls them and shows their transcript/evidence/status. Design run views as Oz's window into externally-running sessions. ## Your task -1. User flows first. Before screens, map the key flows and include them: e.g., "first-time setup → add a CLI → test it → create a workspace → add roots → set personas → launch the first run"; "daily: pick workspace → talk to Oz / pick a priority → launch → watch the run → review result"; "ad-hoc: launch a run with no priority to do a refactor/review/research." +1. User flows first. Before screens, map the key flows and include them: e.g., "first-time setup → add a CLI → test it → create a workspace → add roots → set personas → launch the first run"; "daily: pick workspace → talk to Oz / pick a priority → launch → watch the run in the Dashboard → review result"; "ad-hoc: launch a run with no priority to do a refactor/review/research." 2. Design each screen below with its component breakdown. 3. Define states for each screen: empty (nothing configured yet), loading, active/live, and error. ## Screens -### 1. Dashboard (per selected workspace) -- Workspace picker at the top — switches the entire context (Oz conversation, priorities, runs). -- Oz Terminal — the chatbot conversation with this workspace's Oz: the primary place to issue commands and watch runs. Show conversation history, an input, and inline run/status updates Oz surfaces. Make clear this is a live, working conversation, not a help bot. -- Priorities — the workspace's ordered priority list, reorderable by drag-and-drop (top = next up). Each priority shows its name/summary/status and a Launch action. At the top of the list, an "Launch a run without a priority" action: lets the founder describe an ad-hoc task for the orchestrator to run (e.g., add new priorities, code review, refactor, research) without it being a formal priority. -- Should give an at-a-glance sense of what's running now and what's next. +### 1. Dashboard (the operator's home; per selected workspace) +This is the operational hub. It is built AROUND the Oz conversation; priorities and runs are supporting panels, not separate pages. +- Workspace picker at the top — switches the entire context (which Oz, its priorities, its runs). +- Oz Terminal — THE command center and the primary surface of the whole app. It is the chat conversation with this workspace's headless Oz persona: the founder types here to launch runs, add/reorder priorities, start ad-hoc tasks, and ask for status. Show conversation history, an input, and inline run/status updates Oz surfaces. Make clear this is a live, working conversation that drives the system, not a help bot. Everything else on the Dashboard is a supporting panel that mirrors actions Oz can also take by chat. +- Priorities (supporting panel — lives here, not its own page) — the workspace's ordered priority list, reorderable by drag-and-drop (top = next up). Each priority shows its name/summary/status and a Launch action. At the top of the list, a "Launch a run without a priority" action: lets the founder describe an ad-hoc task for the orchestrator to run (e.g., add new priorities, code review, refactor, research) without it being a formal priority. +- Runs (supporting panel — lives here, not its own page) — Oz is the watcher for every run in this workspace. Show what's running now and recent runs with status, what they worked on, and timing. Selecting a run opens its detail in place (drawer/inspector within the Dashboard): live read-only transcript, evidence/results, status, and controls (stop, attach / copy-attach-command). Remember: the live session runs externally (iTerm today, embedded Electron terminal later) — this is Oz's window into it, never an embedded live terminal. +- Overall, the Dashboard should give an at-a-glance sense of what's running now and what's next, with the Oz conversation front and center. ### 2. Workspaces - List of workspaces (name + description); create/edit/delete. @@ -69,32 +75,29 @@ Oz is the control plane — the single app where the founder runs the whole oper - Sub-agents / services — a persona may delegate specific tasks to sub-agents/services; each sub-agent also gets its own CLI + Model selection, so the UI must express a hierarchy (persona → its sub-agents, each independently configurable). - A way to craft a priority that creates a new persona — i.e., starting "make a new persona" enqueues it as a workspace priority for the AI team to build, rather than a raw form. -### 5. Runs (per selected workspace) -- Workspace picker at the top (same pattern as Dashboard). -- A list of runs with status, what they worked on, and timing. -- A run detail view: live read-only transcript, evidence/results, status, and controls (stop, attach/copy-attach-command). Remember: the live session runs externally (iTerm) — this is Oz's view into it. - -### 6. Settings +### 5. Settings - Human-friendly configuration only — never raw JSON. Use forms/toggles. Treat the exact contents as flexible; design a clean, extensible settings layout (e.g., defaults, global preferences) that can grow. ## Global rules +- Exactly five top-level nav items: Dashboard, Workspaces, CLIs, Personas, Settings. Runs and Priorities are panels inside the Dashboard, never top-level pages. +- The Oz chat is the command center — the Dashboard is organized around it; other Dashboard panels are shortcuts for things the founder could also ask Oz to do. - Never expose JSON — everything is forms, tables, selectors, status chips. -- Workspace context is pervasive (Dashboard + Runs have the picker); make the active workspace obvious everywhere. +- Workspace context is pervasive (the Dashboard picker switches Oz, priorities, and runs together); make the active workspace obvious everywhere. - GUI ⇄ Oz parity — anything the founder can do via a button, they can also ask Oz to do; keep them consistent. - Use precise, technical terminology (run, persona, root, priority, CLI). -- Left-nav top level: Dashboard, Workspaces, CLIs, Personas, Runs, Settings. ## Deliverables - A user-flow map (the flows above). - Each screen designed with component breakdown and empty/loading/active/error states. -- The navigation/IA structure tying it together. +- The navigation/IA structure tying it together (five-section nav; runs + priorities inside the Dashboard). ``` --- ## Open items to resolve from the design output +- The **Dashboard composition** — Oz chat is the command center with priorities and runs as supporting panels; confirm the design keeps the conversation primary and doesn't regress runs/priorities into separate pages. - The **CLI + Model hierarchy** (persona → CLI → model, and sub-agent → CLI → model) is the trickiest interaction — confirm the design handles nesting cleanly. - **Settings** contents are intentionally loose; the design should be extensible without inventing final contents. - How the **ad-hoc "run without a priority"** capture maps to an actual run + (optionally) a new priority. -- The seam where the external iTerm session is later replaced by an **embedded Electron terminal** — keep the run-detail "window into the session" contract stable across that swap. +- The seam where the external iTerm session is later replaced by an **embedded Electron terminal** — keep the run-detail "window into the session" contract (the in-Dashboard run inspector) stable across that swap. From f83110a10c55eae5c267412d59f1ba7357ab3178 Mon Sep 17 00:00:00 2001 From: Anthony Franco Date: Wed, 27 May 2026 19:11:25 -0600 Subject: [PATCH 2/4] v0.1-publish: branch off main for clean v0.1.0 ship MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Founder chose Option A (disentangle): ship v0.1 from a clean branch off main so the v0.1.0 tag contains only v0.1 work, not the v0.4 control-plane design that accumulated on oz-control-plane-design. main already carries the full v0.1 product baseline (A/B/C/E/F + cross-link docs + README/ARCHITECTURE/ci.yml/LICENSE/NOTICE). This commit carries the Oscar-boundary v0.1 delta: current v0.1-foundation plan/README + the ADR-0001 §6 .command footnote fix (D-M1.9). The 6 D-M1 docs and the remaining D atoms (D-M1.7/1.8/2.1/D-S2) land next via Bob. Co-Authored-By: Claude Opus 4.7 (1M context) --- cocoder/decisions/0001-storage-and-license.md | 4 +- cocoder/priorities/v0.1-foundation/README.md | 10 +-- .../plans/2026-05-21-docs-publish.plan.md | 65 ++++++++++++------- 3 files changed, 50 insertions(+), 29 deletions(-) diff --git a/cocoder/decisions/0001-storage-and-license.md b/cocoder/decisions/0001-storage-and-license.md index d6e55c0..32b4717 100644 --- a/cocoder/decisions/0001-storage-and-license.md +++ b/cocoder/decisions/0001-storage-and-license.md @@ -23,7 +23,7 @@ CoCoder must be public OSS with user preferences that survive upstream updates, 5. **Oz:** Master orchestration persona; no separate brand. UI uses Fusion design tokens only. -6. **Platform v0.1:** macOS-first (iTerm2 + `.command` wrappers); git clone + pnpm distribution. +6. **Platform v0.1:** macOS-first (iTerm2 + `.command` wrappers); git clone + pnpm distribution.[^platform-v01-update] 7. **Multi-workspace:** Per-workspace tmux socket namespace, managed by Oz registry. @@ -34,3 +34,5 @@ CoCoder must be public OSS with user preferences that survive upstream updates, - Document multi-machine sync of `local/` via filesystem sync, not git. - MPL/custom license FAQ deferred; Apache FAQ covers commercial use of CoCoder as a tool. - Talia/Quinn split documented in ADR-0002 (persona boundaries). + +[^platform-v01-update]: **Updated 2026-05-27 (D-M1.9; founder chose option (i) — inline footnote, not a new ADR amendment).** The `.command` wrapper mechanism in decision 6 above was retired per ticket [`0001-cocoder-command-wrapper-decision`](../tickets/closed/0001-cocoder-command-wrapper-decision.md) (Path B). v0.1 launch surfaces are terminal-only: the `cocoder` CLI plus the Oz orchestration launcher. macOS-first and git-clone/pnpm distribution are unchanged. diff --git a/cocoder/priorities/v0.1-foundation/README.md b/cocoder/priorities/v0.1-foundation/README.md index 15be5f2..05da055 100644 --- a/cocoder/priorities/v0.1-foundation/README.md +++ b/cocoder/priorities/v0.1-foundation/README.md @@ -317,9 +317,9 @@ Tracked in [`pending-decisions.md`](./pending-decisions.md). **All resolved 2026 ## Progress -**Last worked:** 2026-05-24 (Sub-Playbook D activated — Witness/Interrogate/Solve-target authored) -**Current Canon:** v0.1 completion phase. Sub-Playbook F Complete. B/C Expand merged — Refines parallel-tracked (founder). **Sub-Playbook D Active — Solve pending.** Test count: **335 / 335 / 0 fail / 0 skipped** (+ oz-dashboard **8/8**). -**Next action:** D Solve (D-S2 CI gates, then Expand doc batches, then D-S1 internal proxy). B/C Refines remain founder-only parallel tracks. +**Last worked:** 2026-05-27 (run zx0s33ag — Sub-Playbook D Milestone 1 docs completed; external stranger test removed from scope) +**Current Canon:** v0.1 completion phase. Sub-Playbook F + E Complete. B/C Expand merged — Refines parallel-tracked (founder). **Sub-Playbook D Active — Milestone 1 docs COMPLETE; remaining = repo-root README/ARCHITECTURE + CI gates + internal proxy + tag.** Test count: **335 / 335 / 0 fail / 0 skipped** (+ oz-dashboard **8/8**). +**Next action (needs a wider write boundary):** D-M1.7 ARCHITECTURE verify + D-M1.8 README adopter rewrite (repo-root), then D-M2.1 dogfood-evidence, D-S2 CI gates (`.github/`), D-S1 internal proxy, then `v0.1.0` tag. External stranger test removed (PD-Q1 revised). B/C Refines remain founder-only parallel tracks. ### Sub-Playbook status @@ -330,7 +330,7 @@ Tracked in [`pending-decisions.md`](./pending-decisions.md). **All resolved 2026 | B. Personas + workspace template | **Active — Expand merged (`9bf2433`); Refine pending (founder)** | PR #33 merged; PB-Q1..PB-Q4 answered; B-S1..B-M3 green; suite 265/265 | B Refine (founder) | [`2026-05-21-personas-template.plan.md`](./plans/2026-05-21-personas-template.plan.md) | | **F. Structural cleanup** | **Complete (2026-05-23)** | Final Check closed; PR #28 merged `58e1fe2`; suite 249/249; compose-launch diff clean | — | [`2026-05-23-structural-cleanup.plan.md`](./plans/2026-05-23-structural-cleanup.plan.md) | | **C. Oz MVP** | **Active — Expand complete (2026-05-23); Refine pending (founder)** | C-M1..C-M3 green (PRs #42–#47 → `f46dcff`); suite 335/335 + dashboard 8/8 | C Refine (founder) | [`2026-05-21-oz-mvp.plan.md`](./plans/2026-05-21-oz-mvp.plan.md) | -| **D. Docs + dogfood + publish** | **Active — Witness/Interrogate/Solve-target authored (2026-05-24); Solve pending** | PD-Q1..PD-Q7 answered; suite 335/335 + dashboard 8/8 | D Solve (D-S2 gates → Expand docs → D-S1 proxy) | [`2026-05-21-docs-publish.plan.md`](./plans/2026-05-21-docs-publish.plan.md) | +| **D. Docs + dogfood + publish** | **Active — Milestone 1 docs COMPLETE (2026-05-27, run zx0s33ag); repo-root surfaces + gates + tag remain** | All 6 D-M1 docs authored + ADR-0001 §6 fixed (D-M1.9); external stranger test removed (PD-Q1 revised); suite 335/335 + dashboard 8/8 | D-M1.7/1.8 (repo-root, needs wider boundary) → D-M2.1 → D-S2 (`.github/`) → D-S1 → `v0.1.0` tag | [`2026-05-21-docs-publish.plan.md`](./plans/2026-05-21-docs-publish.plan.md) | | **v0.1 Completion Plan** (cross-cuts A, B, ticket 0001) | **Active** | Items 1 + 2 CLOSED; Item 2.5 F Complete; Item 3 W/I/S authored | PB-Q1..PB-Q4 + B Solve | [`2026-05-23-v0.1-completion.plan.md`](./plans/2026-05-23-v0.1-completion.plan.md) | ### Canon roll-up (Master only) @@ -349,7 +349,7 @@ Tracked in [`pending-decisions.md`](./pending-decisions.md). **All resolved 2026 ## Success Criteria - [ ] All four sub-Playbooks reach Status: Complete -- [ ] Stranger test (P-R2) passes: external dev clones, inits, launches in ≤30 minutes without founder help +- [ ] Stranger test (P-R2) passes: **internal proxy** (PD-Q1 revised 2026-05-27 — external recruit removed from v0.1) clones, inits, launches in ≤30 minutes without doc-clarifying questions - [ ] Two-workspace concurrency test (P-R1) passes without tmux collision - [ ] Recovery test (P-R3) passes after `local/` deletion and Syncthing restore - [ ] All public-readiness gates green on the commit tagged `v0.1.0` diff --git a/cocoder/priorities/v0.1-foundation/plans/2026-05-21-docs-publish.plan.md b/cocoder/priorities/v0.1-foundation/plans/2026-05-21-docs-publish.plan.md index 34dee55..952143b 100644 --- a/cocoder/priorities/v0.1-foundation/plans/2026-05-21-docs-publish.plan.md +++ b/cocoder/priorities/v0.1-foundation/plans/2026-05-21-docs-publish.plan.md @@ -126,7 +126,7 @@ A public CoCoder release at which: | ID | Question | Blocks | Recommended default | Answer (2026-05-24) | ADR / HOLD FOR GO | |---|---|---|---|---|---| -| **PD-Q1** | Stranger test (P-R2) execution model: **(A)** recruited external dev only; **(B)** internal proxy dry-run in **Solve** proves doc readiness; external recruit mandatory in **Refine/Final Check**; **(C)** founder-as-stranger after time gap counts as P-R2. | D-S1, D Refine M3 | **B — Internal proxy in Solve; external recruit in Refine.** | **B (founder-approved 2026-05-24)** | No | +| **PD-Q1** | Stranger test (P-R2) execution model: **(A)** recruited external dev only; **(B)** internal proxy dry-run in **Solve** proves doc readiness; external recruit mandatory in **Refine/Final Check**; **(C)** founder-as-stranger after time gap counts as P-R2. | D-S1, D Refine M3 | **B — Internal proxy in Solve; external recruit in Refine.** | ~~B (2026-05-24)~~ **REVISED 2026-05-27 (run zx0s33ag): external recruit is NOT a v0.1 requirement (founder: "no external stranger test — never should have been a requirement"). Internal-proxy dry-run (D-S1) retained as the readiness check; Milestone 3 external recruit (D-M3.1–D-M3.3) removed from v0.1 scope.** | No | | **PD-Q2** | `README.md` depth at `v0.1.0`: **(A)** full pitch + quick-start (remove "not yet usable" banner); **(B)** minimal pointer to `docs/getting-started.md` only. | D-M1.8, tag | **A — Full pitch + quick-start.** | **A (founder-approved 2026-05-24)** | No | | **PD-Q3** | `NOTICE` maintenance: **(A)** hand-authored (current); **(B)** auto-generated from dependency license scan each release. | D-M4.3 | **A — Hand-authored for v0.1.** | **A (founder-approved 2026-05-24)** | No | | **PD-Q4** | `faq.md` commercial-use scope: **(A)** minimal — Apache-2.0 commercial use, tool vs name/trademark note, commit guidance; **(B)** extended legal FAQ (CoBuilder relationship, redistribution essay). | D-M1.5 | **A — Minimal FAQ.** | **A (founder-approved 2026-05-24)** | **ADR-graduating if B** | @@ -198,25 +198,27 @@ A public CoCoder release at which: ### Milestone 1 — Documentation -- [ ] **D-M1.1** Extend `docs/getting-started.md` to full ≤30 min stranger-test path: install → init out-of-tree workspace → first launch (CLI or Oz). Include labeled diagram: install-level `/local/` vs workspace-level `/cocoder/local/`. -- [ ] **D-M1.2** `docs/orchestration.md` — tmux model, runs, evidence, session wrap (cross-link configuration + custom-personas). -- [ ] **D-M1.3** `docs/personas.md` — who does what, dispatch rules, custom persona ergonomics (cross-link `docs/custom-personas.md`). -- [ ] **D-M1.4** `docs/oz.md` — Oz overview, security model summary, troubleshooting; **cross-link** `docs/oz-launch.md` and `docs/oz-security-checklist.md` (do not duplicate C Expand content). -- [ ] **D-M1.5** `docs/faq.md` — minimal commercial use (PD-Q4=A), what to commit vs not, trademark/name note, zero telemetry (PD-Q5=A), Syncthing secrets warning. -- [ ] **D-M1.6** `docs/freshness-policy.md` — ADR/ARCHITECTURE verification stamps + doc audit cadence; Oz freshness panel deferred v0.2. +- [x] **D-M1.1** Extend `docs/getting-started.md` to full ≤30 min stranger-test path: install → init out-of-tree workspace → first launch (CLI or Oz). Include labeled diagram: install-level `/local/` vs workspace-level `/cocoder/local/`. **(Authored 2026-05-27, run suesc2sq — clean-clone→init→compose-launch→CLI launch + Oz launch path, storage-zone diagram, cross-links to `oz-launch.md`/`oz-security-checklist.md`. The ≤30-min readiness *proof* is D-S1 internal-proxy, still deferred — authoring done, not yet stranger-validated.)** +- [x] **D-M1.2** `docs/orchestration.md` — tmux model, runs, evidence, session wrap (cross-link configuration + custom-personas). **(Authored 2026-05-27, run zx0s33ag — Bob; `check-doc-refs` 0 missing refs.)** +- [x] **D-M1.3** `docs/personas.md` — who does what, dispatch rules, custom persona ergonomics (cross-link `docs/custom-personas.md`). **(Authored 2026-05-27, run zx0s33ag — Bob; `check-doc-refs` 0 missing refs.)** +- [x] **D-M1.4** `docs/oz.md` — Oz overview, security model summary, troubleshooting; **cross-link** `docs/oz-launch.md` and `docs/oz-security-checklist.md` (do not duplicate C Expand content). **(Authored 2026-05-27, run zx0s33ag — Bob; summary-plus-pointers, no C-Expand duplication; `check-doc-refs` 0 missing refs.)** +- [x] **D-M1.5** `docs/faq.md` — minimal commercial use (PD-Q4=A), what to commit vs not, trademark/name note, zero telemetry (PD-Q5=A), Syncthing secrets warning. **(Authored 2026-05-27, run suesc2sq — minimal PD-Q4=A scope; all five required topics present; link-checked via `check-doc-refs` 0 missing refs.)** +- [x] **D-M1.6** `docs/freshness-policy.md` — ADR/ARCHITECTURE verification stamps + doc audit cadence; Oz freshness panel deferred v0.2. **(Authored 2026-05-27, run zx0s33ag — Bob; Oz freshness panel explicitly marked deferred-to-v0.2; `check-doc-refs` 0 missing refs.)** - [ ] **D-M1.7** Mermaid diagram(s) in `ARCHITECTURE.md` verified for clarity (update stamps if edited). - [ ] **D-M1.8** **`README.md` adopter-ready rewrite (PD-Q2=A).** Remove "not yet usable by adopters" banner; replace stale Sub-Playbook A progress text with v0.1 pitch + quick-start pointer to `docs/getting-started.md`. -- [ ] **D-M1.9** **ADR-0001 §6 stale `.command` reference — founder process gate.** Line 26 still says "iTerm2 + `.command` wrappers"; retired per ticket 0001 Path B. **Blocked until founder picks:** **(i)** inline "Updated 2026-05-24" footnote in ADR-0001 noting terminal-only + Oz launch surface, or **(ii)** graduate new ADR amending §6. Do not silently edit accepted decision text without recording which option was chosen. +- [x] **D-M1.9** **ADR-0001 §6 stale `.command` reference — founder process gate.** ~~Line 26 still says "iTerm2 + `.command` wrappers"; retired per ticket 0001 Path B.~~ **Resolved 2026-05-27, run zx0s33ag (Oscar): founder chose option (i) — inline footnote.** ADR-0001 decision 6 now carries a dated `[^platform-v01-update]` footnote noting the `.command` retirement (ticket 0001 Path B) and terminal-only CLI + Oz launch surfaces; accepted decision text preserved, no new ADR graduated. ### Milestone 2 — Dogfood evidence (PD-Q7=A) - [ ] **D-M2.1** Author `docs/dogfood-evidence.md` summarizing Sub-Playbook E orchestrated runs + Oz observability (C Expand). No mandatory new Oscar polish session. -### Milestone 3 — Refine: stranger test (external recruit) +### Milestone 3 — Refine: stranger test (external recruit) — ❌ REMOVED FROM v0.1 SCOPE (2026-05-27, run zx0s33ag) -- [ ] **D-M3.1** Recruit external developer (not familiar with CoCoder or CoBuilder; not the internal proxy from D-S1). -- [ ] **D-M3.2** Time the run from `git clone` to first `cocoder launch` (target: ≤30 min; hard cap: 60 min before pause for diagnosis). -- [ ] **D-M3.3** Capture every clarifying question as a doc task; iterate until run completes cleanly (binary green/red for Final Check). +> **Founder decision 2026-05-27:** the external stranger-test recruit is not a v0.1 requirement and never should have been (PD-Q1 revised). v0.1 doc-readiness is proven by the **internal-proxy dry-run (D-S1)** only. The items below are retained struck-through for history; they do not gate v0.1. + +- [~] ~~**D-M3.1** Recruit external developer (not familiar with CoCoder or CoBuilder; not the internal proxy from D-S1).~~ **Removed from v0.1 scope.** +- [~] ~~**D-M3.2** Time the run from `git clone` to first `cocoder launch` (target: ≤30 min; hard cap: 60 min before pause for diagnosis).~~ **Removed from v0.1 scope.** +- [~] ~~**D-M3.3** Capture every clarifying question as a doc task; iterate until run completes cleanly (binary green/red for Final Check).~~ **Removed from v0.1 scope.** ### Milestone 4 — Publish @@ -281,26 +283,43 @@ A public CoCoder release at which: ## Resume Instructions -1. Confirm PD-Q1..PD-Q7 answers recorded above (all approved 2026-05-24). -2. Read Master Playbook Final Check §public-readiness gates + this Sub-Playbook Witness inventory. -3. Execute **D Solve** (D-S2 gates first if doc Expand not ready; D-S1 after getting-started extension lands). -4. Do not schedule external stranger test until D-S1 internal proxy is green. -5. Do not tag `v0.1.0` until D Refine + Final Check complete. +### Next Session Start Here + +**Recommended next atom:** D-M1.7+D-M1.8 -- ARCHITECTURE.md verification + README.md adopter-ready rewrite (the repo-root publish surfaces that gate the `v0.1.0` tag). + +- **Route / topology:** `oscar-lead` (Oscar lead + Bob builder), same as run zx0s33ag. +- **Required personas:** Oscar (orchestrator), Bob (builder). Strict substitution. +- **Required write boundary (MUST widen vs zx0s33ag):** repo-root `README.md` + `ARCHITECTURE.md` (for D-M1.7/D-M1.8), `.github/workflows/ci.yml` (for D-S2 gates), and `docs/` (for D-M2.1). The zx0s33ag run could not touch any of these — that is the only reason these items are still open. +- **Stop conditions:** do NOT tag `v0.1.0` until D-S1 internal-proxy is green AND README/ARCHITECTURE landed AND D-S2 CI gates exit 0. Do NOT self-archive — archival is a founder confirmation. +- **Required tests/checks:** full suite stays **335/335** + oz-dashboard **8/8**; `check-doc-refs` 0 missing on any new/edited doc; D-S2 CI gate steps exit 0 on `main`; D-S1 internal-proxy completes clean-clone → `cocoder init` → first launch without doc-clarifying questions. +- **Explicit founder decisions:** external stranger test is REMOVED from v0.1 (PD-Q1 revised 2026-05-27). The `v0.1.0` tag + release notes (PD-Q6=A, semver) remain a founder release action. + +### Remaining v0.1 work items +1. **D-M1.7** ARCHITECTURE.md Mermaid verification (repo-root). +2. **D-M1.8** README.md adopter rewrite — remove "not yet usable by adopters" banner + stale Sub-Playbook A text (PD-Q2=A; repo-root). +3. **D-M2.1** `docs/dogfood-evidence.md` (Bob, `docs/`). +4. **D-S1** internal-proxy stranger readiness (the retained doc-readiness proof). +5. **D-S2** public-readiness CI gates — gitleaks + LICENSE/NOTICE + faq (`.github/workflows/ci.yml`). +6. **`v0.1.0` tag** + release notes (founder action). + +### History +- D-M1.1–D-M1.6 + D-M1.9 complete (getting-started, faq in run suesc2sq; orchestration, personas, oz, freshness-policy + ADR-0001 footnote in run zx0s33ag). +- Do not tag `v0.1.0` until the stop conditions above are met. --- ## Progress -**Last worked:** 2026-05-24 (Activated — Witness/Interrogate/Solve-target authored) -**Current Canon:** Active — Witness/Interrogate complete; Solve not started -**Next action:** D Solve — wire `gitleaks` + FAQ/LICENSE gates in CI (D-S2); then Expand doc batches; then D-S1 internal proxy. +**Last worked:** 2026-05-27 (run zx0s33ag — D-M1.2/1.3/1.4/1.6 docs + D-M1.9 ADR fix; external stranger test removed from scope) +**Current Canon:** Active — Expand. D Milestone 1 docs COMPLETE; remaining = repo-root publish surfaces + CI gates + internal proxy + tag. +**Next action:** D-M1.7 ARCHITECTURE verify + D-M1.8 README rewrite (repo-root — needs wider write boundary), then D-M2.1 dogfood-evidence, D-S2 CI gates (`.github/`), D-S1 internal proxy, then `v0.1.0` tag. See "Next Session Start Here" above. | Canon | Items | Done | Status | |---|---|---|---| | Witness | 1 audit table + objective + scope + current state | 4 | **Complete (2026-05-24)** | -| Interrogate | 7 PD-Q + 9 risks + reuse check | 7 + 9 + 5 | **Complete (2026-05-24)** — PD-Q1..PD-Q7 all-A/B per table | -| Solve | 2 (D-S1, D-S2) | 0 | Not started | -| Expand | M1: 9 · M2: 1 · M3: 3 · M4: 3 | 0 | Not started (gated on Solve checkpoint for sequencing; doc batches may overlap) | +| Interrogate | 7 PD-Q + 9 risks + reuse check | 7 + 9 + 5 | **Complete (2026-05-24)** — PD-Q1 revised 2026-05-27 (external stranger test removed) | +| Solve | 2 (D-S1, D-S2) | 0 | Not started (D-S2 needs `.github/` boundary; D-S1 needs proxy actor) | +| Expand | M1: 9 (incl. D-M1.9) · M2: 1 · ~~M3: 3~~ removed · M4: 3 | M1: 7 of 9 | **M1 docs done** (D-M1.1–1.6, 1.9); open: D-M1.7/1.8 (repo-root). M3 external recruit removed from scope. | | Refine | 4 | 0 | Not started | | Final Check | 8 | 0 | Not started | From 68feb24ca581b2b690111d22da5d03d327273c7d Mon Sep 17 00:00:00 2001 From: Anthony Franco Date: Wed, 27 May 2026 19:19:07 -0600 Subject: [PATCH 3/4] Prepare v0.1 publish surfaces --- .github/workflows/ci.yml | 14 +- ARCHITECTURE.md | 30 +-- README.md | 81 +++++++-- docs/dogfood-evidence.md | 49 +++++ docs/faq.md | 56 ++++++ docs/freshness-policy.md | 66 +++++++ docs/getting-started.md | 171 +++++++++++++++--- docs/orchestration.md | 75 ++++++++ docs/oz.md | 76 ++++++++ docs/personas.md | 59 ++++++ .../schemas/test/workspaces-registry.test.ts | 2 +- 11 files changed, 615 insertions(+), 64 deletions(-) create mode 100644 docs/dogfood-evidence.md create mode 100644 docs/faq.md create mode 100644 docs/freshness-policy.md create mode 100644 docs/orchestration.md create mode 100644 docs/oz.md create mode 100644 docs/personas.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 23ec316..2ee982c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,12 +25,16 @@ jobs: # had landed undetected through PRs #8 and #9. - name: Install ripgrep (for stale-reference gate) run: brew install ripgrep + - name: Install gitleaks (for public-readiness gate) + run: brew install gitleaks - run: pnpm -F schemas build - run: git diff --exit-code -- packages/schemas/dist/ - run: pnpm typecheck - run: pnpm -r test - run: pnpm -F core test config-resolver - run: node packages/core/cli.mjs validate-contracts + - name: Secret scan (gitleaks full history) + run: gitleaks detect --no-banner --source . --log-opts="--all" # Documented-invocation parity smoke test. The 2026-05-22 cocoder-cli # bin-symlink miss surfaced post-merge because the documented # `pnpm exec cocoder ...` form was never CI-tested — the previous @@ -70,5 +74,11 @@ jobs: fi - name: Public readiness placeholder run: | - test -f LICENSE - test -f NOTICE + set -e + test -s LICENSE + test -s NOTICE + grep -qi 'CoBuilder' NOTICE + grep -qi 'extract' NOTICE + test -s docs/faq.md + grep -qi 'commercial use' docs/faq.md + grep -Eqi 'zero (analytics|telemetry)|no telemetry' docs/faq.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index b66ab52..fc3952a 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,7 +1,7 @@ -# CoCoder Architecture (Draft) +# CoCoder Architecture -**Status:** Draft — Refine (Sub-Playbook A audit remediation in flight; Sub-Playbook E dogfood ramp proven end-to-end) -**Last verified:** 2026-05-22 (Sub-Playbook E exercised the four-zone storage model, multi-workspace concurrency, and config-resolver semantics across 4 autonomous orchestrated runs; 110/110 tests pass; repo published to `BadGuyFranco/cocoder`) +**Status:** v0.1 release candidate +**Last verified:** 2026-05-28 (Mermaid storage-zone diagram reviewed for render clarity; public doc references rechecked in Sub-Playbook D publish pass) ## Mental Model @@ -9,33 +9,37 @@ CoCoder has **four storage zones** that must never be conflated. Two live in the ```mermaid flowchart TB - subgraph install ["CoCoder install (git repo — tracked)"] + subgraph install ["CoCoder install repo (tracked)"] Core[packages/core — CLI, contracts, launch] Dash[packages/oz-dashboard] + Docs[docs/] Tpl[templates/workspace-cocoder] end - subgraph installLocal ["CoCoder/local/ — GITIGNORED"] + subgraph installLocal ["CoCoder/local/ (gitignored)"] Oz[Oz state + workspaces registry] Wsps[workspaces/ — per-ws install-side state] Prefs[Models, accounts, secrets, audit, roots] end - subgraph wsA ["Workspace A repo"] - CA[cocoder/ — priorities, memory, ADRs] - CALA[cocoder/local/ — GITIGNORED] + subgraph wsA ["Application workspace A"] + CA[cocoder/ — tracked governance] + CALA[cocoder/local/ — gitignored overrides] end - subgraph wsB ["Workspace B repo"] - CB[cocoder/] - CBLB[cocoder/local/] + subgraph wsB ["Application workspace B"] + CB[cocoder/ — tracked governance] + CBLB[cocoder/local/ — gitignored overrides] end + Dash --> Oz Oz --> Core Core --> CA Core --> CB Prefs --> Oz Prefs --> Core + Tpl --> CA + Tpl --> CB ``` | Zone | Location | Tracked in git? | Purpose | @@ -243,8 +247,8 @@ Normal adopters get workspace customization by default. CoCoder product improvem ## References -- CoBuilder orchestration: `infrastructure/cobuilder-build/orchestration/ARCHITECTURE.md` -- Design language: `marketing/brand/design-brief.md` (Fusion palette — adapt for CoCoder branding) +- CoBuilder orchestration: historical upstream extraction reference retained in `NOTICE` +- Design language: [`docs/oz-design-brief.md`](./docs/oz-design-brief.md) - ADR index: `cocoder/decisions/README.md` - Dogfood meta-project: `cocoder/AGENTS.md` - Active priorities: `cocoder/PRIORITIES.md` diff --git a/README.md b/README.md index 828f673..6e3165f 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,51 @@ # CoCoder -> **Status:** v0.1 in progress — **not yet usable by adopters.** Foundation, dogfood orchestration, and audit-finding remediation are landing first; full personas, workspace template, Oz dashboard, and onboarding docs follow in Sub-Playbooks B, C, and D. See [`cocoder/PRIORITIES.md`](./cocoder/PRIORITIES.md) for the live state. +CoCoder is an open, local-first AI coding orchestration framework for solo builders and small teams. It packages the proven CoBuilder orchestration runtime as a reusable CLI, workspace template, persona contract system, and local Oz dashboard. -CoCoder is an open, local-first AI coding orchestration framework for solo builders and small teams. It extracts the proven CoBuilder orchestration runtime into a reusable CLI, workspace structure, and local control plane. +Use it when you want AI coding sessions to start from explicit priorities, bounded write scopes, durable evidence, and repeatable result artifacts instead of ad hoc chat threads. + +## What v0.1 includes + +- A `cocoder` CLI for workspace setup, launch composition, lane startup, contract validation, and local audit checks. +- A tracked `cocoder/` workspace structure for priorities, session logs, ADRs, tickets, memory, standards, routes, profiles, and personas. +- A workspace template created by `cocoder init`. +- Oz, a loopback-only browser dashboard for workspace registration, priority launch, run listing, and run inspection. +- Public docs for first launch, orchestration, personas, configuration, Oz, freshness policy, and FAQ. +- Apache-2.0 licensing with CoBuilder extraction attribution in `NOTICE`. + +## Requirements + +- macOS first for v0.1 +- Node.js version from `.nvmrc` +- pnpm 10.x +- tmux +- At least one configured model CLI adapter named by the selected profile + +## Quick Start + +Install CoCoder: + +```sh +git clone ~/dev/CoCoder +cd ~/dev/CoCoder +pnpm install +pnpm -F cocoder-cli build +pnpm exec cocoder validate-contracts +export COCODER_HOME="$PWD" +``` + +Initialize an application workspace outside the CoCoder install: + +```sh +mkdir -p ~/dev/my-app +cd ~/dev/my-app +git init +pnpm --dir "$COCODER_HOME" exec cocoder init \ + --workspace-root "$PWD" \ + --cocoder-home "$COCODER_HOME" +``` + +Then follow [`docs/getting-started.md`](./docs/getting-started.md) for the full path from clean clone to first CLI or Oz launch. ## Mental Model @@ -10,22 +53,23 @@ CoCoder has two public surfaces and two private surfaces: - The CoCoder install repo contains the engine, schemas, templates, docs, and dashboard source. - `/local/` stores install-private preferences, workspace registry data, audit logs, and secrets. -- Each application repo gets a tracked `cocoder/` workspace folder for priorities, ADRs, tickets, memory, and standards. -- Each application repo also gets ignored `cocoder/local/` overrides for machine-local settings. +- Each application repo gets a tracked `cocoder/` workspace folder for priorities, ADRs, tickets, memory, standards, and persona contracts. +- Each application repo also gets ignored `cocoder/local/` overrides for machine-local settings and secrets. -Git updates the engine and templates. Ignored `local/` directories preserve user preferences. +Git updates the engine and templates. Ignored `local/` directories preserve operator preferences and run records. -## Requirements - -- macOS first for v0.1 -- Node 20 LTS -- pnpm -- tmux and iTerm2 for orchestrated sessions -- User-installed model CLIs such as Codex, Claude, Grok, Gemini, or Kimi +For the full storage-zone model, see [`ARCHITECTURE.md`](./ARCHITECTURE.md). For commercial use, telemetry, trademark, and sync guidance, see [`docs/faq.md`](./docs/faq.md). -## Current Build Status +## Documentation -The active build is tracked in [cocoder/PRIORITIES.md](./cocoder/PRIORITIES.md). Sub-Playbook A is implementing the foundation: monorepo scaffold, config resolver, path portability, install preferences, and the extracted core baseline. +- [`docs/getting-started.md`](./docs/getting-started.md) - clean-clone to first launch. +- [`docs/orchestration.md`](./docs/orchestration.md) - runs, dispatch, evidence, and result artifacts. +- [`docs/personas.md`](./docs/personas.md) - core role contracts and write capability. +- [`docs/configuration.md`](./docs/configuration.md) - install/workspace config, path resolution, and terminal invocation. +- [`docs/oz.md`](./docs/oz.md) - dashboard overview and troubleshooting. +- [`docs/oz-launch.md`](./docs/oz-launch.md) - command-by-command Oz launch flow. +- [`docs/oz-security-checklist.md`](./docs/oz-security-checklist.md) - local daemon security checklist. +- [`docs/freshness-policy.md`](./docs/freshness-policy.md) - doc verification stamps and release-candidate audit cadence. ## Local Development @@ -33,22 +77,23 @@ The active build is tracked in [cocoder/PRIORITIES.md](./cocoder/PRIORITIES.md). pnpm install pnpm -F schemas build pnpm -F core test -node packages/core/cli.mjs validate-contracts +pnpm -F oz-dashboard test +pnpm exec cocoder validate-contracts ``` The public CLI package builds a `cocoder` binary: ```sh pnpm -F cocoder-cli build -packages/cocoder-cli/bin/cocoder config get +pnpm exec cocoder config get ``` ## Contributing -CoCoder is solo-maintained early-stage OSS. Outside contributions are welcome on the terms documented in [`CONTRIBUTING.md`](./CONTRIBUTING.md). For open-ended questions and design discussions use [Discussions](https://github.com/BadGuyFranco/cocoder/discussions); for bugs and concrete proposals use [Issues](https://github.com/BadGuyFranco/cocoder/issues). For security reports see [`SECURITY.md`](./SECURITY.md) — never file a public issue for a vulnerability. +CoCoder is solo-maintained early-stage OSS. Outside contributions are welcome on the terms documented in [`CONTRIBUTING.md`](./CONTRIBUTING.md). For open-ended questions and design discussions use [Discussions](https://github.com/BadGuyFranco/cocoder/discussions); for bugs and concrete proposals use [Issues](https://github.com/BadGuyFranco/cocoder/issues). For security reports see [`SECURITY.md`](./SECURITY.md) - never file a public issue for a vulnerability. Behavior expectations: [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md). ## License -Apache-2.0. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE). The orchestration core under `packages/core/` is mechanically extracted from upstream CoBuilder (independent OSS); attribution requirements live in `NOTICE`. +Apache-2.0. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE). The orchestration core under `packages/core/` is mechanically extracted from upstream CoBuilder; attribution requirements live in `NOTICE`. diff --git a/docs/dogfood-evidence.md b/docs/dogfood-evidence.md new file mode 100644 index 0000000..c2ecb44 --- /dev/null +++ b/docs/dogfood-evidence.md @@ -0,0 +1,49 @@ +# Dogfood Evidence + +**Status:** Draft, implemented by Sub-Playbook D Solve +**Last verified:** 2026-05-28 (summarized from tracked session log, architecture notes, docs, and tests; no new polish session run) + +CoCoder v0.1 was built through its own orchestration loop before the public publish pass. This page summarizes the evidence that the core run model, workspace boundaries, and Oz observability surfaces have already been exercised inside the CoCoder dogfood workspace. + +## Sub-Playbook E orchestration runs + +Sub-Playbook E proved that CoCoder could compose, launch, dispatch, verify, and close real work against the CoCoder repository itself. + +Evidence from `cocoder/SESSION_LOG.md` records: + +- First end-to-end dogfood execution, `run-20260522T133403Z-rwrkcfcg`: Talia ported `core.test.mjs`; Bob independently audited and accepted; full core suite reached 75/75 passing. +- Reproducibility run, `run-20260522T135126Z-t4rnd35z`: Talia ported `dispatch.test.mjs`; both lanes returned `PASS`; full core suite reached 86/86 passing. +- Chained autonomous runs, `run-20260522T160453Z-nsluixnb` and `run-20260522T161135Z-i3wg7ti9`: additional adapter and composition ports moved the suite to 110/110 passing, with run-local result artifacts and boundary notes. +- Sub-Playbook E final closure on 2026-05-23: the dogfood loop became the reusable basis for persona identity regression coverage and workspace-template validation. + +Those runs also surfaced and pinned real orchestration defects: model-role null handling, `iso-datetime` schema validation, private legacy pattern false positives, workspace-slug path parsing, and lead-lane sandbox requirements. + +## Boundary evidence + +The dogfood workspace exercises the same four-zone model documented in [`ARCHITECTURE.md`](../ARCHITECTURE.md): + +- tracked install surfaces under `packages/`, `docs/`, `templates/`, and root project files +- ignored install-local run records under `/local/workspaces//` +- tracked workspace governance under `/cocoder/` +- ignored workspace-local overrides under `/cocoder/local/` + +Regression coverage now includes workspace artifact paths, nested workspace refusal, persona prompt identity, template/dogfood drift, and orchestrator commit boundary behavior. + +## Oz observability + +Sub-Playbook C expanded Oz from security and registry primitives into the v0.1 operator surface: + +- PR #42: workspace registry HTTP CRUD plus auth bootstrap; core suite 322/322. +- PR #43: runs API, evidence endpoint, multiplexer observer, and launch/stop subprocess path; core suite 328/328. +- PR #45: dashboard scaffold, Workspaces page, Settings page, and dashboard tests; core suite 330/330 plus dashboard 5/5. +- PR #47: Priorities, Runs, Run Inspector, polling behavior, and end-to-end Oz coverage; core suite 335/335 plus dashboard 8/8. + +The public operator docs intentionally summarize rather than duplicate the C Expand implementation details: + +- [`docs/oz.md`](./oz.md) +- [`docs/oz-launch.md`](./oz-launch.md) +- [`docs/oz-security-checklist.md`](./oz-security-checklist.md) + +## Current limitation + +This is release-candidate evidence, not a fresh external user study. The v0.1 publish bar keeps the internal-proxy dry run as the remaining readiness check before the founder tags `v0.1.0`. diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..be4d718 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,56 @@ +# CoCoder FAQ + +## Can I use CoCoder commercially? + +Yes. CoCoder's code is licensed under Apache-2.0, which permits commercial use, modification, distribution, and private use subject to the license terms. + +The license covers the tool and code. It does not grant rights to imply endorsement, sponsorship, or ownership of the "CoCoder" name, logo, or product identity. If you fork or ship a derivative, make the product name and provenance clear. + +Commit guidance: + +- Keep Apache-2.0 license notices and required attribution intact. +- Commit your workspace's public governance files under `cocoder/` when they are part of the project. +- Do not commit private secrets, local credentials, or machine-specific overrides. + +## What should I commit? + +Commit shared project state: + +- `cocoder/PRIORITIES.md` +- `cocoder/SESSION_LOG.md` +- `cocoder/decisions/` +- `cocoder/memory/` +- Public routes, profiles, priority boundaries, persona contracts, and prompt fragments you intentionally maintain for the workspace + +Do not commit private or generated state: + +- `/local/` +- `/cocoder/local/` +- Secret files, tokens, API keys, `.env*`, and private playbooks +- `node_modules/`, `dist/`, `.turbo/`, and other dependency, build, or cache artifacts + +See [`getting-started.md`](./getting-started.md) for the install-level and workspace-level storage diagram. + +## Can I use the CoCoder name? + +Use the name "CoCoder" to identify the upstream project and to preserve attribution. Do not use it to brand a fork, hosted service, plugin, or integration in a way that suggests official status unless you have permission from the project owner. + +For derivatives, choose a distinct name and state that it is based on CoCoder. + +## Does CoCoder collect telemetry? + +No. CoCoder v0.1 collects zero analytics and ships no telemetry. Local commands may write local run records, audit files, and result artifacts under ignored `local/` paths so the operator can inspect what happened on that machine. + +## Can I sync CoCoder with Syncthing or another file sync tool? + +Be careful. Syncing tracked project files is fine, but do not sync `local/` secrets broadly across machines. In particular: + +- Do not sync `/local/secrets/`. +- Do not sync `/cocoder/local/secrets/`. +- Review any sync rule that includes `local/`, run transcripts, or private playbooks. + +If you need multi-machine setup, copy only the tracked repo state first, then recreate secrets and machine-local config on each machine. + +## Where do I learn the first launch flow? + +Start with [`getting-started.md`](./getting-started.md). For the Oz browser launch surface, see [`oz-launch.md`](./oz-launch.md). For local daemon security checks, see [`oz-security-checklist.md`](./oz-security-checklist.md). diff --git a/docs/freshness-policy.md b/docs/freshness-policy.md new file mode 100644 index 0000000..04bd76a --- /dev/null +++ b/docs/freshness-policy.md @@ -0,0 +1,66 @@ +# Documentation Freshness Policy + +**Status:** Draft, implemented by Sub-Playbook D Solve +**Last verified:** 2026-05-27 (policy authored; no automated freshness gate added in this run) + +CoCoder docs should say when they were last checked against the implementation. Freshness stamps do not prove correctness by themselves, but they make stale claims visible during review. + +## Stamp format + +Use a short stamp near the top of durable architecture, ADR, and public docs: + +```markdown +**Status:** Draft, Active, Accepted, Superseded, or Archived +**Last verified:** YYYY-MM-DD (short evidence note) +``` + +The evidence note should name the strongest check available: a command, test suite, audit run, founder review, or targeted manual verification. + +## Architecture verification + +[`ARCHITECTURE.md`](../ARCHITECTURE.md) is the public system map. Update its verification stamp when a change alters storage zones, launch flow, security boundaries, package layout, or public-facing architecture claims. + +An architecture stamp should cite evidence such as: + +- a passing focused test or package suite +- a launch or compose dry run +- a doc-reference audit +- a founder-approved architecture review + +Do not update the stamp for unrelated wording-only edits unless the reviewer actually re-checked the architectural claims. + +## ADR verification + +ADRs under [`cocoder/decisions/`](../cocoder/decisions/) record decisions, not task notes. When implementation catches up to an ADR, or when behavior changes away from it, update the ADR status and verification stamp in the same review window. + +Recommended ADR states: + +- **Proposed** - not ratified yet. +- **Accepted** - ratified and current. +- **Implemented** - ratified and verified in code or docs. +- **Superseded** - replaced by a newer ADR. + +If an ADR is superseded, link the replacement decision and avoid editing old rationale except for the status note. + +## Public doc audit cadence + +Run a lightweight doc audit during each release-candidate pass and after any change that touches: + +- launch commands or tmux behavior +- workspace storage zones +- Oz security or launch behavior +- persona, route, or profile contracts +- public onboarding instructions + +Minimum local checks: + +```bash +pnpm exec cocoder check-doc-refs --root "$COCODER_HOME" --workspace-root "$COCODER_HOME" +pnpm exec cocoder validate-contracts +``` + +For docs that describe an operator path, pair static checks with a real or dry-run command and record the limitation in the `Last verified` note. + +## Deferred Oz freshness panel + +The Oz freshness panel is deferred to v0.2. In v0.1, freshness remains a documentation and review discipline enforced by stamps, check commands, and release closeout notes. diff --git a/docs/getting-started.md b/docs/getting-started.md index 4c34ccc..d8840aa 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,67 +1,178 @@ # Getting started with CoCoder -Minimal path from install to first workspace init. Sub-Playbook D extends this into a full stranger-test doc set. +This is the shortest v0.1 path from a clean clone to a first orchestrated launch. It assumes you want to run CoCoder against an application repository that lives outside the CoCoder install tree. -## 1. Install +Target time: 30 minutes or less on a machine that already has Node.js and pnpm. -Prerequisites: Node.js version from `.nvmrc`, pnpm 10.x. +## 1. Install CoCoder + +Prerequisites: + +- Node.js version from `.nvmrc` +- pnpm 10.x +- tmux +- At least one configured CLI adapter named by the selected profile ```bash -git clone -cd CoCoder +git clone ~/dev/CoCoder +cd ~/dev/CoCoder pnpm install pnpm -F cocoder-cli build +pnpm exec cocoder validate-contracts ``` -Verify: +Keep the install path handy: ```bash -pnpm exec cocoder validate-contracts +export COCODER_HOME="$PWD" +``` + +## 2. Choose an out-of-tree workspace + +Do not initialize a normal application workspace inside the CoCoder install. The install repo already contains its own dogfood workspace at `/cocoder/`; your app should be elsewhere. + +Example: + +```bash +mkdir -p ~/dev/my-app +cd ~/dev/my-app +git init +``` + +## 3. Initialize CoCoder in the workspace + +Run `cocoder init` from the application repo root: + +```bash +pnpm --dir "$COCODER_HOME" exec cocoder init \ + --workspace-root "$PWD" \ + --cocoder-home "$COCODER_HOME" +``` + +This creates `/cocoder/` from `templates/workspace-cocoder/`. Re-run with `--merge true` after CoCoder updates; user-edited tracked files are preserved. + +Storage zones: + +```text +CoCoder install repo + / + packages/ tracked engine code + docs/ tracked public docs + templates/ tracked workspace templates + local/ ignored install-level state + workspaces/ Oz registry, run records, audit files + secrets/ install-level private secrets + +Application workspace + / + cocoder/ tracked workspace governance + PRIORITIES.md priorities you can launch + SESSION_LOG.md recent run notes + decisions/ workspace decisions + memory/ onboarding notes and codebase map + local/ ignored workspace-local state + config.yaml private per-workspace config + playbooks/ private operator notes + secrets/ do not commit or sync broadly ``` -## 2. Initialize a workspace +Commit the tracked workspace governance files. Do not commit either `local/` zone. -From **your application repository** (not inside the CoCoder install tree): +## 4. Run the workspace audit stubs ```bash -cd /path/to/your-app -pnpm exec cocoder init --workspace-root . --cocoder-home /path/to/CoCoder +pnpm --dir "$COCODER_HOME" exec cocoder audit-workspace --workspace-root "$PWD" +pnpm --dir "$COCODER_HOME" exec cocoder refresh-memory --workspace-root "$PWD" +``` + +Read and edit the generated memory files enough that a first run has context: + +- the onboarding questions file under `cocoder/memory/` +- `cocoder/memory/codebase-map.md` +- `cocoder/memory/tech-stack.md` + +Full stack detection is v0.2 scope; in v0.1 these are starter files for the operator to refine. + +## 5. Add a first launch priority + +For the first v0.1 smoke launch, add an active priority row to `cocoder/PRIORITIES.md` using the starter route's supported slug: + +```markdown +| v0.1-foundation | First CoCoder launch smoke test | Active | Oscar | ``` -This materializes `cocoder/` from `templates/workspace-cocoder/`. Re-run with `--merge true` after CoCoder updates; user-edited tracked files are preserved. +After your own routes and priority boundaries exist, replace this with project-specific slugs. See [`custom-personas.md`](./custom-personas.md) for route and persona extension conventions. -## 3. Audit stub (optional) +## 6. Dry-run composition + +From the application workspace root: ```bash -pnpm exec cocoder audit-workspace --workspace-root . -pnpm exec cocoder refresh-memory --workspace-root . +pnpm --dir "$COCODER_HOME" exec cocoder compose-launch \ + --profile "$COCODER_HOME/cocoder/profiles/cocoder-oscar.profile.json" \ + --route "$COCODER_HOME/cocoder/routes/oscar-lead.json" \ + --priority-slug v0.1-foundation \ + --priority-file "$PWD/cocoder/PRIORITIES.md" \ + --session-log "$PWD/cocoder/SESSION_LOG.md" \ + --workspace-root "$PWD" \ + --workspace-slug my-app ``` -Read `cocoder/memory/onboarding-questions.md` and `cocoder/memory/codebase-map.md`. Full stack detection is v0.2 scope. +The dry run should return `"ok": true`. Fix validation errors before launching. Common causes are a missing active priority row, an unavailable adapter, or a route/profile mismatch. -## 4. First persona launch (outline) +## 7. First launch from CLI -1. Add a priority to `cocoder/PRIORITIES.md`. -2. Copy or author `profiles/`, `routes/`, and `priority-boundaries/` (see dogfood files in the CoCoder install or `examples/personas/phil-primitive-builder/`). -3. Dry-run composition: +Start a visible terminal launch: ```bash -pnpm exec cocoder compose-launch \ - --profile cocoder/profiles/your.profile.json \ - --route cocoder/routes/your.route.json \ - --priority-slug your-slug +pnpm --dir "$COCODER_HOME" exec cocoder launch \ + --profile "$COCODER_HOME/cocoder/profiles/cocoder-oscar.profile.json" \ + --route "$COCODER_HOME/cocoder/routes/oscar-lead.json" \ + --priority-slug v0.1-foundation \ + --priority-file "$PWD/cocoder/PRIORITIES.md" \ + --session-log "$PWD/cocoder/SESSION_LOG.md" \ + --workspace-root "$PWD" \ + --workspace-slug my-app \ + --socket-name cocoder-my-app \ + --execute true \ + --attach iterm ``` -4. Inspect the JSON output; fix validation errors before `launch --execute true`. +`--attach iterm` is best-effort on macOS. If no GUI terminal opens, use the `attachCommands` in the JSON output to attach to the tmux sessions manually. -See `docs/custom-personas.md` for custom persona authoring and `templates/playbooks/new-workspace-setup.md` for a first-week operator playbook. +The first run is successful when the launcher creates a run directory under `/local/workspaces/my-app/runs/` and both lanes receive their launch prompts. If a lane reports a blocker, keep the result artifacts and use the reported evidence instead of deleting the run directory. -## 5. Oz dashboard (optional) +## 8. First launch from Oz -For a browser UI to register workspaces, scan priorities, launch runs, and inspect evidence: +Oz is the browser launch surface for v0.1. ```bash -pnpm exec cocoder oz start +pnpm --dir "$COCODER_HOME" exec cocoder oz start --cocoder-home "$COCODER_HOME" +pnpm --dir "$COCODER_HOME" exec cocoder oz register \ + --id my-app \ + --workspace-root "$PWD" \ + --tmux-socket cocoder-my-app \ + --cocoder-home "$COCODER_HOME" ``` -Open `http://127.0.0.1:7878/`. See [`docs/oz-launch.md`](./oz-launch.md) for the full Oz operator flow (replaces retired `.command` double-click wrappers). +Open `http://127.0.0.1:7878/`, then use **Priorities** to launch the active priority for `my-app`. The dashboard launch path opens visible panes by default when possible. + +For the full dashboard operator flow, see [`oz-launch.md`](./oz-launch.md). For local daemon security expectations before regular use, see [`oz-security-checklist.md`](./oz-security-checklist.md). + +## 9. What to commit + +Commit: + +- `/cocoder/PRIORITIES.md` +- `/cocoder/SESSION_LOG.md` +- `/cocoder/decisions/` +- `/cocoder/memory/` +- Public persona, route, boundary, and prompt files you intentionally add under `/cocoder/` + +Do not commit: + +- `/local/` +- `/cocoder/local/` +- Secret files, `.env*`, run transcripts containing private material, or generated dependency/build/cache directories + +See [`faq.md`](./faq.md) for commercial-use, trademark, telemetry, and sync cautions. diff --git a/docs/orchestration.md b/docs/orchestration.md new file mode 100644 index 0000000..d40ad7b --- /dev/null +++ b/docs/orchestration.md @@ -0,0 +1,75 @@ +# CoCoder Orchestration + +**Status:** Draft, implemented by Sub-Playbook D Solve +**Last verified:** 2026-05-27 (docs pass only; no runtime behavior changed) + +CoCoder launches visible, bounded agent lanes around one selected priority. A run is a working record: launch prompt, startup packet, lane panes, evidence paths, and result artifacts. + +## Tmux model + +Each lane runs in its own tmux session. The launch command creates the sessions, writes lane prompts under the run directory, and starts the configured adapter in each pane. + +Common shapes: + +- **Lead lane** - usually Oscar. Reconciles priority fit, dispatches bounded packets, and owns closeout status updates. +- **Builder lane** - usually Bob. Edits files only inside its write boundary, verifies the packet, then writes result artifacts. +- **Verifier or QA lanes** - optional route members for test building, browser automation, or review. + +Detached runs are normal. Use the launch output's attach commands, or `--attach iterm`, to open panes for a human operator. See [`oz-launch.md`](./oz-launch.md) for the dashboard launch path. + +## Runs + +A run directory lives under the install-local workspace registry: + +```text +/local/workspaces//runs// + startup-packet.json + events.jsonl + jobs//prompt.md + jobs//result.json + jobs//result.md + send-to-.sh + watch--completion.sh +``` + +The startup packet is orientation, not a work order. In `wait-for-lead-dispatch` mode, teammate lanes load the prompt and packet, then stay idle until the lead sends a concrete dispatch. + +Configuration resolution, workspace roots, and private `local/` overrides are described in [`configuration.md`](./configuration.md). + +## Dispatch rules + +The lead dispatch should state: + +- the priority and plan slice +- files or directories in scope +- files or directories out of scope +- required verification +- result expectations when they add detail beyond the lane launch prompt + +Lane launch prompts remain authoritative for identity fields such as persona, adapter, write capability, and result paths. If a later dispatch conflicts with those fields, the lane should follow the launch prompt and report the conflict. + +## Evidence capture + +Evidence belongs in the run result, not only in chat. A useful result names the command, file, report path, screenshot, or diff that supports the claim and states its limitation. + +Evidence classes: + +- **Class A** - founder-pristine, packaged, staging, production, or real user-path proof. +- **Class B** - local, mocked, dry-run, static, or dev-path proof. + +Most v0.1 builder checks are Class B unless they exercise a real operator path from a clean or founder-controlled environment. + +## Session-wrap flow + +When a lane finishes its packet: + +1. Run the required checks, or state why they could not run. +2. Write `jobs//result.json` using the launch prompt's result contract. +3. Write `jobs//result.md` with the same closeout in human-readable form. +4. Stop work for that packet. + +Result artifacts close the lane for the current run. Do not delete, rename, or overwrite them to accept another packet; start a fresh run until packet ledgers are first-class. + +## Extension points + +Routes, profiles, personas, prompt fragments, and priority boundaries define who can join a run and what they may write. See [`custom-personas.md`](./custom-personas.md) for the public extension conventions. diff --git a/docs/oz.md b/docs/oz.md new file mode 100644 index 0000000..0afe7db --- /dev/null +++ b/docs/oz.md @@ -0,0 +1,76 @@ +# Oz + +**Status:** Draft, implemented by Sub-Playbook D Solve +**Last verified:** 2026-05-27 (docs pass only; no runtime behavior changed) + +Oz is CoCoder's local browser control surface. In v0.1 it helps an operator register workspaces, inspect priorities, launch runs, watch run status, and stop runs without hand-copying long CLI commands. + +For the command-by-command launch flow, see [`oz-launch.md`](./oz-launch.md). For the local daemon hardening checklist, see [`oz-security-checklist.md`](./oz-security-checklist.md). + +## What Oz does + +Oz sits on top of the same CLI contracts as terminal launches. It does not replace routes, profiles, priority boundaries, startup packets, or lane result contracts. + +The v0.1 dashboard covers: + +- workspace registration +- priority selection +- run launch through `cocoder launch` +- run listing and stop actions +- a run inspector with minimum viable evidence paths +- settings surfaced through the shared configuration resolver + +Use Oz when you want repeatable launches across multiple workspaces. Use the CLI directly when debugging launch composition or working in a terminal-only environment. + +## Security model summary + +Oz is designed as a local operator daemon, not an internet service. The v0.1 security posture is: + +- loopback-only binding +- bearer token on state-changing routes +- strict Host and Origin checks +- CSRF token on mutating requests +- settings responses that preserve secret references instead of resolved secret values +- audit log entries for launch and stop actions +- argv subprocess execution instead of shell-string interpolation + +This is only a summary. Use [`oz-security-checklist.md`](./oz-security-checklist.md) for the actual operator checklist and sign-off surface. + +## Troubleshooting + +### Oz will not start + +Confirm dependencies are installed and the core package is built: + +```bash +pnpm install +pnpm -F cocoder-cli build +pnpm exec cocoder oz start +``` + +If the default port is occupied, set `COCODER_OZ_PORT` and restart. + +### Dashboard cannot see a workspace + +Register the workspace with the install-local registry: + +```bash +pnpm exec cocoder oz register \ + --id my-app \ + --path /path/to/my-app \ + --tmux-socket cocoder-my-app +``` + +Then refresh the Workspaces or Priorities page. + +### Launch starts but no terminal opens + +Visible panes are best-effort. If macOS does not open iTerm2 or Terminal.app, use the attach commands from the launch output or inspect the run directory under `/local/workspaces//runs/`. + +### Mutating requests return 401 or 403 + +Restart the dashboard session so it can refresh the loopback auth session. If using a custom client, confirm it sends the bearer token and CSRF token exactly as returned by Oz. + +### Run stop does not remove evidence + +That is expected. Stop actions should leave run directories, event logs, and lane result artifacts intact so the lead can audit what happened. diff --git a/docs/personas.md b/docs/personas.md new file mode 100644 index 0000000..bc15ac9 --- /dev/null +++ b/docs/personas.md @@ -0,0 +1,59 @@ +# CoCoder Personas + +**Status:** Draft, implemented by Sub-Playbook D Solve +**Last verified:** 2026-05-27 (docs pass only; no runtime behavior changed) + +Personas are role contracts for orchestration lanes. They describe what a lane is responsible for, how it receives work, what evidence it must return, and whether it can write. + +## Core personas + +| Persona | Role | +|---|---| +| Oscar | Lead orchestrator. Selects the bounded packet, reconciles route fit, dispatches teammates, and owns priority closeout. | +| Bob | Primary builder and architect. Implements scoped changes, keeps docs and behavior aligned, and reports verification evidence. | +| Talia | Automated test builder and runner. Owns unit and integration test construction inside the assigned boundary. | +| Quinn | User-interaction QA. Exercises browser, terminal, and IDE paths where scripted interaction is the right evidence. | +| Ian | Operations orchestrator. Handles CRM, copy, and integration work outside product-code implementation. | +| Oz | Global orchestration overseer. Provides the multi-workspace dashboard and control-plane surface. | + +Routes decide which personas are active in a run. A persona listed in the library does nothing until a route and profile assign it to a lane. + +## Dispatch rules + +The lead lane should dispatch work as a concrete packet, not as a vague phase label. A good packet includes the task, scope, write boundary, exclusions, verification command, and result expectations. + +Teammate lanes should: + +- treat the launch prompt as authoritative for persona, adapter, write capability, and result paths +- obey the startup packet's write boundary +- preserve unrelated worktree changes +- stop when a requested edit crosses the lane boundary +- write result artifacts only when the packet is complete + +The route's substitution policy matters. If a route requires Bob as a builder, a planning or verifier lane does not silently satisfy that role. + +## Write capability + +Write access is lane-specific. A persona can be capable in one route and read-only in another, depending on the selected profile and priority boundary. + +Common policies: + +- **read-only** - inspect and report, but do not edit. +- **task-scoped** - write only the packet's files or directories. +- **bounded-writer** - write within a declared priority boundary, still preserving unrelated changes. + +When a packet asks for a wider edit than the boundary allows, report the conflict instead of expanding scope locally. + +## Results + +Every active lane returns the result contract named in its launch prompt, usually `job-result`. At minimum, closeout should include status, files changed, findings, evidence, residual risk, and the next action. + +Evidence should be concrete enough for the lead to audit without reading the whole chat transcript. Prefer command outputs, report paths, screenshots, diffs, and named files over narrative confidence. + +## Custom-persona ergonomics + +Custom personas are tracked workspace artifacts, not private prompt hacks. A good custom persona adds a focused role, a validated contract, prompt fragments, route eligibility, and an evidence checklist. + +Use custom personas when a recurring job needs a different skill boundary than Bob, Talia, or Quinn. Do not create one for a one-off packet that the existing route can dispatch clearly. + +See [`custom-personas.md`](./custom-personas.md) for schema requirements, directory conventions, prompt manifests, validation commands, and review gates. diff --git a/packages/schemas/test/workspaces-registry.test.ts b/packages/schemas/test/workspaces-registry.test.ts index dd717c7..eaf4546 100644 --- a/packages/schemas/test/workspaces-registry.test.ts +++ b/packages/schemas/test/workspaces-registry.test.ts @@ -16,7 +16,7 @@ describe("workspaceRegistryEntrySchema", () => { it("accepts entries without a description for backward compatibility", () => { const parsed = workspaceRegistryEntrySchema.parse({ id: "cocoder", - path: "/Volumes/NAS LOCAL/CoCoder" + path: "/Users/example/CoCoder" }); expect(parsed.description).toBeUndefined(); From 0482a1593c638bb46f2613dc975e73d12a597d59 Mon Sep 17 00:00:00 2001 From: Anthony Franco Date: Wed, 27 May 2026 19:29:41 -0600 Subject: [PATCH 4/4] v0.1 wrap (run 1wna3uxq): D doc/gate authoring complete on v0.1-publish; D-S1 descoped Reconcile Sub-Playbook D after Bob landed D-M1.7/D-M1.8/D-M2.1/D-S2 (68feb24): - Mark D-M1.7 (ARCHITECTURE verify), D-M1.8 (README adopter rewrite), D-M2.1 (dogfood-evidence), D-S2 (CI gates) complete on branch v0.1-publish. - Record founder removal of D-S1 internal-proxy from v0.1 scope (dogfoods own projects post-ship); v0.1 Solve is now D-S2 only. - Rewrite next-start brief: next step is the founder release sequence (review v0.1-publish -> merge to main -> CI green = D-S2 Class A -> tag v0.1.0), not a fresh build run. - Update PRIORITIES.md row + Status block + SESSION_LOG newest-first entry. Co-Authored-By: Claude Opus 4.7 (1M context) --- cocoder/PRIORITIES.md | 4 +- cocoder/SESSION_LOG.md | 14 ++++ cocoder/priorities/v0.1-foundation/README.md | 8 +- .../plans/2026-05-21-docs-publish.plan.md | 73 +++++++++---------- 4 files changed, 56 insertions(+), 43 deletions(-) diff --git a/cocoder/PRIORITIES.md b/cocoder/PRIORITIES.md index 2c7622a..d68ce15 100644 --- a/cocoder/PRIORITIES.md +++ b/cocoder/PRIORITIES.md @@ -15,7 +15,7 @@ Slim index of active and archived priorities. Open a priority's folder for detai | Slug | Description | Status | Canon | Owner | Blocked on | |---|---|---|---|---|---| -| [`v0.1-foundation`](./priorities/v0.1-foundation/README.md) | Ship CoCoder v0.1 — extraction, Oz MVP, docs, public publish | Active | Expand — **Sub-Playbook D activated**; D Solve next. Suite **335/335** (+ dashboard 8/8). | Bob + founder | **Next:** D Solve. B/C Refines parallel (founder). | +| [`v0.1-foundation`](./priorities/v0.1-foundation/README.md) | Ship CoCoder v0.1 — extraction, Oz MVP, docs, public publish | Active | Expand — **Sub-Playbook D doc + CI-gate authoring COMPLETE on branch `v0.1-publish`** (run 1wna3uxq). Only founder release (merge → CI → `v0.1.0` tag) remains. | Bob + founder | **Next (founder):** review `v0.1-publish` → merge to `main` (CI = D-S2 Class A) → tag `v0.1.0`. B/C Refines parallel (founder). | ## Draft @@ -46,7 +46,7 @@ Slim index of active and archived priorities. Open a priority's folder for detai 3. **Sub-Playbook B activation** — Witness/Interrogate/Solve-target for adopter onboarding (workspace template + `cocoder init` + getting-started doc). Multi-session work; the marquee remaining v0.1 deliverable. **Recommended next-session ordering:** Item 1 → Item 2 (in batches) → Item 3 (Witness/Interrogate only). The completion plan has an appendix with a verbatim resume prompt for fresh-session pickup. **Done = ticket 0001 closed, M4 free-wins all `[x]` or marked deferred-to-v0.2, Sub-Playbook B Witness populated + Status flipped to Active.** -**Status:** Active — Refine. Sub-Playbook F Complete 2026-05-23. Sub-Playbook B Expand merged (PR #33 → `9bf2433`). Sub-Playbook C Expand complete 2026-05-23 (PRs #42–#47 → `f46dcff`). **Sub-Playbook D activated 2026-05-24** (Witness/Interrogate/Solve-target). B/C Refines parallel-tracked (founder). Suite **335/335** (+ oz-dashboard **8/8**). See [`priorities/v0.1-foundation/README.md`](./priorities/v0.1-foundation/README.md). +**Status:** Active — Refine. Sub-Playbook F Complete 2026-05-23. Sub-Playbook B Expand merged (PR #33 → `9bf2433`). Sub-Playbook C Expand complete 2026-05-23 (PRs #42–#47 → `f46dcff`). **Sub-Playbook D doc + CI-gate authoring COMPLETE 2026-05-27 (run 1wna3uxq) on branch `v0.1-publish`** (off `main`, Option A disentangle): D-M1.7 ARCHITECTURE verify, D-M1.8 README adopter rewrite, D-M2.1 dogfood-evidence, D-S2 CI gates (gitleaks + LICENSE/NOTICE + faq) all landed; D-S1 internal-proxy + external stranger test both removed from v0.1 scope (founder). **Only the founder release remains:** review `v0.1-publish` → merge to `main` (triggers CI = D-S2 Class A) → tag `v0.1.0` + release notes (PD-Q6=A). v0.4 control-plane work stays on `oz-control-plane-design`. Local Class B checks green; Class A pending CI on `main`. B/C Refines parallel-tracked (founder). See [`priorities/v0.1-foundation/README.md`](./priorities/v0.1-foundation/README.md). ### [v0.2-adapter-extensibility](./priorities/v0.2-adapter-extensibility/README.md) **Owner:** Bob + founder diff --git a/cocoder/SESSION_LOG.md b/cocoder/SESSION_LOG.md index d51ccb0..43d9c12 100644 --- a/cocoder/SESSION_LOG.md +++ b/cocoder/SESSION_LOG.md @@ -14,6 +14,20 @@ Append-only log of work sessions. New entries at the **top**. One entry per mean --- +## 2026-05-27 — **v0.1 publish surfaces complete on clean branch `v0.1-publish` (Option A disentangle); D-S1 removed; ready for founder release** + +**Persona:** Oscar (lead) + Bob (builder, codex) | **Priority:** v0.1-foundation | **Plan:** [`plans/2026-05-21-docs-publish.plan.md`](./priorities/v0.1-foundation/plans/2026-05-21-docs-publish.plan.md) | **Run:** 1wna3uxq + +**Outcomes:** +- **Founder chose Option A (disentangle):** ship v0.1 from a clean branch off `main` so the `v0.1.0` tag contains only v0.1, not the v0.4 control-plane work entangled on `oz-control-plane-design`. Verified the split is clean — `main` already holds the full v0.1 product baseline (A/B/C/E/F + cross-link docs + README/ARCHITECTURE/ci.yml/LICENSE/NOTICE); the only delta was the 6 D-M1 docs + ADR-0001 §6 fix + remaining D work. +- Created **`v0.1-publish`** off `main`. Oscar carried governance + the ADR-0001 §6 fix (`f83110a`); Bob brought the 6 authored D-M1 docs over (byte-identical to source, verified) and landed **D-M1.7** (ARCHITECTURE verify), **D-M1.8** (README adopter rewrite, banner removed), **D-M2.1** (`docs/dogfood-evidence.md`), **D-S2** (ci.yml gitleaks + LICENSE/NOTICE + faq gates) as `68feb24`. Also scrubbed one machine-specific `/Volumes/...` literal from a schemas test fixture to keep the stale-ref gate green. +- **Founder scope decisions this run:** D-S1 internal-proxy readiness **removed** from v0.1 ("I'll dogfood on my own projects — not a v0.1 concern"); `v0.1.0` tag stays a founder release action. D-S2 green-on-main is Class A only after CI runs; local Class B (gitleaks 104-commit clean, `check-doc-refs` 0 missing, public-readiness-ok) all pass. One sandbox socket-bind `EPERM` blocks full-suite Class A locally. +- Unrelated dirty `packages/oz-dashboard/src/pages/PrioritiesPage.tsx` preserved untouched/unstaged throughout. + +**Next:** **Founder release sequence** — review `v0.1-publish`, merge to `main` (triggers CI = D-S2 Class A proof), then tag `v0.1.0` + release notes (PD-Q6=A). Merging `v0.1-publish` then later `oz-control-plane-design` to `main` will need governance-file (PRIORITIES.md/SESSION_LOG) conflict resolution — expected cost of the disentangle. + +--- + ## 2026-05-24 — **Sub-Playbook D activated (Witness/Interrogate/Solve-target); PD-Q1..PD-Q7 answered** **Persona:** AI (Bob) | **Priority:** v0.1-foundation | **Plan:** [`priorities/v0.1-foundation/plans/2026-05-21-docs-publish.plan.md`](./priorities/v0.1-foundation/plans/2026-05-21-docs-publish.plan.md) diff --git a/cocoder/priorities/v0.1-foundation/README.md b/cocoder/priorities/v0.1-foundation/README.md index 05da055..563f1df 100644 --- a/cocoder/priorities/v0.1-foundation/README.md +++ b/cocoder/priorities/v0.1-foundation/README.md @@ -317,9 +317,9 @@ Tracked in [`pending-decisions.md`](./pending-decisions.md). **All resolved 2026 ## Progress -**Last worked:** 2026-05-27 (run zx0s33ag — Sub-Playbook D Milestone 1 docs completed; external stranger test removed from scope) -**Current Canon:** v0.1 completion phase. Sub-Playbook F + E Complete. B/C Expand merged — Refines parallel-tracked (founder). **Sub-Playbook D Active — Milestone 1 docs COMPLETE; remaining = repo-root README/ARCHITECTURE + CI gates + internal proxy + tag.** Test count: **335 / 335 / 0 fail / 0 skipped** (+ oz-dashboard **8/8**). -**Next action (needs a wider write boundary):** D-M1.7 ARCHITECTURE verify + D-M1.8 README adopter rewrite (repo-root), then D-M2.1 dogfood-evidence, D-S2 CI gates (`.github/`), D-S1 internal proxy, then `v0.1.0` tag. External stranger test removed (PD-Q1 revised). B/C Refines remain founder-only parallel tracks. +**Last worked:** 2026-05-27 (run 1wna3uxq — Sub-Playbook D doc/gate authoring COMPLETE on branch `v0.1-publish`; D-S1 removed from v0.1 scope) +**Current Canon:** v0.1 completion phase. Sub-Playbook F + E Complete. B/C Expand merged — Refines parallel-tracked (founder). **Sub-Playbook D — all doc + CI-gate authoring COMPLETE on branch `v0.1-publish` (off `main`, Option A disentangle); only the founder release sequence remains.** Local Class B checks pass; full-suite + D-S2 gates need a CI run on `main` for Class A. +**Next action (founder release):** review branch `v0.1-publish` → merge to `main` (triggers CI = D-S2 Class A proof) → tag `v0.1.0` + release notes (PD-Q6=A). External stranger test removed (PD-Q1); **D-S1 internal proxy removed (founder 2026-05-27)**. B/C Refines remain founder-only parallel tracks. v0.4 control-plane work stays on `oz-control-plane-design`. ### Sub-Playbook status @@ -330,7 +330,7 @@ Tracked in [`pending-decisions.md`](./pending-decisions.md). **All resolved 2026 | B. Personas + workspace template | **Active — Expand merged (`9bf2433`); Refine pending (founder)** | PR #33 merged; PB-Q1..PB-Q4 answered; B-S1..B-M3 green; suite 265/265 | B Refine (founder) | [`2026-05-21-personas-template.plan.md`](./plans/2026-05-21-personas-template.plan.md) | | **F. Structural cleanup** | **Complete (2026-05-23)** | Final Check closed; PR #28 merged `58e1fe2`; suite 249/249; compose-launch diff clean | — | [`2026-05-23-structural-cleanup.plan.md`](./plans/2026-05-23-structural-cleanup.plan.md) | | **C. Oz MVP** | **Active — Expand complete (2026-05-23); Refine pending (founder)** | C-M1..C-M3 green (PRs #42–#47 → `f46dcff`); suite 335/335 + dashboard 8/8 | C Refine (founder) | [`2026-05-21-oz-mvp.plan.md`](./plans/2026-05-21-oz-mvp.plan.md) | -| **D. Docs + dogfood + publish** | **Active — Milestone 1 docs COMPLETE (2026-05-27, run zx0s33ag); repo-root surfaces + gates + tag remain** | All 6 D-M1 docs authored + ADR-0001 §6 fixed (D-M1.9); external stranger test removed (PD-Q1 revised); suite 335/335 + dashboard 8/8 | D-M1.7/1.8 (repo-root, needs wider boundary) → D-M2.1 → D-S2 (`.github/`) → D-S1 → `v0.1.0` tag | [`2026-05-21-docs-publish.plan.md`](./plans/2026-05-21-docs-publish.plan.md) | +| **D. Docs + dogfood + publish** | **Active — all doc/gate authoring COMPLETE on branch `v0.1-publish` (2026-05-27, run 1wna3uxq); founder release sequence remains** | D-M1.1–1.9 docs + ADR-0001 §6 fix + D-M2.1 dogfood-evidence + D-S2 CI gates all landed on `v0.1-publish`; D-S1 + external stranger test removed from scope (founder); local Class B green, D-S2/full-suite Class A pending CI on `main` | **Founder:** review `v0.1-publish` → merge to `main` (CI = D-S2 Class A) → tag `v0.1.0` | [`2026-05-21-docs-publish.plan.md`](./plans/2026-05-21-docs-publish.plan.md) | | **v0.1 Completion Plan** (cross-cuts A, B, ticket 0001) | **Active** | Items 1 + 2 CLOSED; Item 2.5 F Complete; Item 3 W/I/S authored | PB-Q1..PB-Q4 + B Solve | [`2026-05-23-v0.1-completion.plan.md`](./plans/2026-05-23-v0.1-completion.plan.md) | ### Canon roll-up (Master only) diff --git a/cocoder/priorities/v0.1-foundation/plans/2026-05-21-docs-publish.plan.md b/cocoder/priorities/v0.1-foundation/plans/2026-05-21-docs-publish.plan.md index 952143b..7e498c0 100644 --- a/cocoder/priorities/v0.1-foundation/plans/2026-05-21-docs-publish.plan.md +++ b/cocoder/priorities/v0.1-foundation/plans/2026-05-21-docs-publish.plan.md @@ -164,31 +164,28 @@ A public CoCoder release at which: ## Solve -*Sub-Playbook D has **two** Solve invariants — stranger-test readiness (internal proxy) and public-readiness gates green. Refine executes the external recruit; Final Check is the binary ship gate.* +*Sub-Playbook D Solve is now a **single** invariant — public-readiness gates green (D-S2). The stranger-test readiness invariant (D-S1) was removed from v0.1 scope by the founder on 2026-05-27 (run 1wna3uxq); founder real-project dogfooding validates readiness post-ship. Final Check is the binary ship gate.* **Riskiest piece (D-side):** -1. **Stranger-test readiness (D-S1)** — internal proxy (not the founder, not yet the external recruit) completes the `docs/getting-started.md` path from clean clone → `cocoder init` → first `cocoder launch` (or documented Oz equivalent) in **≤30 minutes** without doc-clarifying questions. Proves the doc set *can* pass P-R2 before scheduling a real person's time. +1. ~~**Stranger-test readiness (D-S1)**~~ — **removed from v0.1 scope** (founder, 2026-05-27). 2. **Public-readiness gates green (D-S2)** — all Master Final Check §5 items enforced via CI on every push to `main`. ### Tasks -- [ ] **D-S1** **Stranger-test readiness (internal proxy).** - - **Implementation shape:** after Expand doc authoring lands (or against interim getting-started if run incrementally), a person other than the founder (internal proxy — e.g., team member, contractor) executes the getting-started path from a clean clone on a machine without CoCoder context. Founder observes without intervening except to note confusion points. - - **Test shape:** timed run ≤30 min; zero doc-clarifying questions required to complete init + first launch; gaps captured as doc fix tasks before external recruit is scheduled. - - **Phase:** Solve proves readiness; Refine (D-M3) runs recruited external dev per Master P-R2. +- [~] ~~**D-S1** **Stranger-test readiness (internal proxy).**~~ **❌ REMOVED FROM v0.1 SCOPE (founder, 2026-05-27, run 1wna3uxq):** "I have projects I will use CoCoder on myself — this is not a v0.1 concern." The founder's own real-project dogfooding is the readiness validation and it happens *after* ship, not as a pre-tag gate. Mirrors the 2026-05-27 removal of the external stranger recruit (D-M3). v0.1 doc-readiness is no longer gated by a proxy dry-run; the docs ship on their authored + `check-doc-refs`-clean state. Retained struck-through for history. -- [ ] **D-S2** **Public-readiness gates green in CI.** +- [x] **D-S2** **Public-readiness gates green in CI.** **(Authored 2026-05-27, run 1wna3uxq — Bob, on branch `v0.1-publish`. All four sub-gates wired into `.github/workflows/ci.yml` in place. Local Class B equivalents pass; the "exit 0 on `main`" bar is Class A and only provable once CI runs at/after merge.)** - **Implementation shape:** extend `.github/workflows/ci.yml` (no parallel `scripts/gates/` directory): - - **D-S2a** `gitleaks detect --no-banner` on full history (install `gitleaks` on macOS runner same as `rg`). - - **D-S2b** Retain existing stale-reference gate block ( `/Volumes/`, `cobuilder`, private playbook paths ) — verify still green after doc Expand. - - **D-S2c** LICENSE + NOTICE presence **and** minimal content checks (non-empty; NOTICE mentions CoBuilder extraction attribution). - - **D-S2d** `docs/faq.md` exists and contains commercial-use + telemetry-zero statements (PD-Q4=A, PD-Q5=A). + - [x] **D-S2a** `gitleaks detect --no-banner` on full history (install `gitleaks` on macOS runner same as `rg`). *(Local: `gitleaks detect --no-banner --source . --log-opts="--all"` → 104 commits scanned, no leaks. Class B.)* + - [x] **D-S2b** Retain existing stale-reference gate block ( `/Volumes/`, `cobuilder`, private playbook paths ) — verify still green after doc Expand. *(Green; required removing one machine-specific `/Volumes/...` literal from `packages/schemas/test/workspaces-registry.test.ts` fixture → `/Users/example/CoCoder`, assertion unchanged.)* + - [x] **D-S2c** LICENSE + NOTICE presence **and** minimal content checks (non-empty; NOTICE mentions CoBuilder extraction attribution). *(Local checks → `public-readiness-ok`. Class B.)* + - [x] **D-S2d** `docs/faq.md` exists and contains commercial-use + telemetry-zero statements (PD-Q4=A, PD-Q5=A). *(Local grep passes. Class B.)* - **Test shape:** CI job fails if any gate fails; local reproduction documented in D plan Progress when landed. -**Pass threshold:** D-S1 internal proxy completes without doc-clarifying questions; D-S2 all CI gate steps exit 0 on `main`. +**Pass threshold (revised 2026-05-27):** D-S2 all CI gate steps exit 0 on `main` (Class A — proven when CI runs after merge of `v0.1-publish`). ~~D-S1 internal proxy~~ removed from v0.1 scope. -**Checkpoint:** [ ] Stranger-test readiness proven; public-readiness gates green. External stranger test can be scheduled for Refine. +**Checkpoint:** [ ] Public-readiness gates green on `main` (D-S2 Class A). ~~Stranger-test readiness~~ no longer a v0.1 gate. --- @@ -204,13 +201,13 @@ A public CoCoder release at which: - [x] **D-M1.4** `docs/oz.md` — Oz overview, security model summary, troubleshooting; **cross-link** `docs/oz-launch.md` and `docs/oz-security-checklist.md` (do not duplicate C Expand content). **(Authored 2026-05-27, run zx0s33ag — Bob; summary-plus-pointers, no C-Expand duplication; `check-doc-refs` 0 missing refs.)** - [x] **D-M1.5** `docs/faq.md` — minimal commercial use (PD-Q4=A), what to commit vs not, trademark/name note, zero telemetry (PD-Q5=A), Syncthing secrets warning. **(Authored 2026-05-27, run suesc2sq — minimal PD-Q4=A scope; all five required topics present; link-checked via `check-doc-refs` 0 missing refs.)** - [x] **D-M1.6** `docs/freshness-policy.md` — ADR/ARCHITECTURE verification stamps + doc audit cadence; Oz freshness panel deferred v0.2. **(Authored 2026-05-27, run zx0s33ag — Bob; Oz freshness panel explicitly marked deferred-to-v0.2; `check-doc-refs` 0 missing refs.)** -- [ ] **D-M1.7** Mermaid diagram(s) in `ARCHITECTURE.md` verified for clarity (update stamps if edited). -- [ ] **D-M1.8** **`README.md` adopter-ready rewrite (PD-Q2=A).** Remove "not yet usable by adopters" banner; replace stale Sub-Playbook A progress text with v0.1 pitch + quick-start pointer to `docs/getting-started.md`. +- [x] **D-M1.7** Mermaid diagram(s) in `ARCHITECTURE.md` verified for clarity (update stamps if edited). **(Done 2026-05-27, run 1wna3uxq — Bob, on branch `v0.1-publish`; verification stamp refreshed + storage-zone Mermaid clarified. Static/manual clarity review — `mmdc` not installed locally, so render-verification is Class B.)** +- [x] **D-M1.8** **`README.md` adopter-ready rewrite (PD-Q2=A).** Remove "not yet usable by adopters" banner; replace stale Sub-Playbook A progress text with v0.1 pitch + quick-start pointer to `docs/getting-started.md`. **(Done 2026-05-27, run 1wna3uxq — Bob; "not yet usable" banner removed, "What v0.1 includes" + "Quick Start" → `docs/getting-started.md` added.)** - [x] **D-M1.9** **ADR-0001 §6 stale `.command` reference — founder process gate.** ~~Line 26 still says "iTerm2 + `.command` wrappers"; retired per ticket 0001 Path B.~~ **Resolved 2026-05-27, run zx0s33ag (Oscar): founder chose option (i) — inline footnote.** ADR-0001 decision 6 now carries a dated `[^platform-v01-update]` footnote noting the `.command` retirement (ticket 0001 Path B) and terminal-only CLI + Oz launch surfaces; accepted decision text preserved, no new ADR graduated. ### Milestone 2 — Dogfood evidence (PD-Q7=A) -- [ ] **D-M2.1** Author `docs/dogfood-evidence.md` summarizing Sub-Playbook E orchestrated runs + Oz observability (C Expand). No mandatory new Oscar polish session. +- [x] **D-M2.1** Author `docs/dogfood-evidence.md` summarizing Sub-Playbook E orchestrated runs + Oz observability (C Expand). No mandatory new Oscar polish session. **(Done 2026-05-27, run 1wna3uxq — Bob, on branch `v0.1-publish`; `check-doc-refs` 0 missing refs.)** ### Milestone 3 — Refine: stranger test (external recruit) — ❌ REMOVED FROM v0.1 SCOPE (2026-05-27, run zx0s33ag) @@ -285,43 +282,45 @@ A public CoCoder release at which: ### Next Session Start Here -**Recommended next atom:** D-M1.7+D-M1.8 -- ARCHITECTURE.md verification + README.md adopter-ready rewrite (the repo-root publish surfaces that gate the `v0.1.0` tag). +**All D authoring atoms are complete. The next step is a FOUNDER RELEASE sequence, not a fresh Oscar/Bob build run.** -- **Route / topology:** `oscar-lead` (Oscar lead + Bob builder), same as run zx0s33ag. -- **Required personas:** Oscar (orchestrator), Bob (builder). Strict substitution. -- **Required write boundary (MUST widen vs zx0s33ag):** repo-root `README.md` + `ARCHITECTURE.md` (for D-M1.7/D-M1.8), `.github/workflows/ci.yml` (for D-S2 gates), and `docs/` (for D-M2.1). The zx0s33ag run could not touch any of these — that is the only reason these items are still open. -- **Stop conditions:** do NOT tag `v0.1.0` until D-S1 internal-proxy is green AND README/ARCHITECTURE landed AND D-S2 CI gates exit 0. Do NOT self-archive — archival is a founder confirmation. -- **Required tests/checks:** full suite stays **335/335** + oz-dashboard **8/8**; `check-doc-refs` 0 missing on any new/edited doc; D-S2 CI gate steps exit 0 on `main`; D-S1 internal-proxy completes clean-clone → `cocoder init` → first launch without doc-clarifying questions. -- **Explicit founder decisions:** external stranger test is REMOVED from v0.1 (PD-Q1 revised 2026-05-27). The `v0.1.0` tag + release notes (PD-Q6=A, semver) remain a founder release action. +**Recommended next atom:** D-RELEASE -- founder reviews branch `v0.1-publish`, merges it to `main` (PR), confirms CI is green (closes D-S2 Class A), then tags `v0.1.0`. + +- **Branch state:** all v0.1 publish surfaces live on **`v0.1-publish`** (off `main`; commits `f83110a` Oscar governance + ADR-0001 §6 fix, `68feb24` Bob docs/README/ARCHITECTURE/ci.yml). The v0.4 control-plane work stays on `oz-control-plane-design`. This split was the founder's Option A (disentangle so `v0.1.0` contains only v0.1). +- **Release sequence (founder-gated):** + 1. Review `v0.1-publish` (diff vs `main`: 6 D docs + README rewrite + ARCHITECTURE verify + `docs/dogfood-evidence.md` + ci.yml gates + ADR-0001 §6 footnote + governance). + 2. Merge `v0.1-publish` → `main` (PR or fast-forward). **This triggers CI**, which runs the D-S2 gates and is the **Class A** proof that the gates exit 0 on `main`. + 3. If CI green → tag `v0.1.0` + semver release notes (PD-Q6=A). **Tag/publish is a human action (Master Authority).** +- **Stop conditions:** do NOT tag `v0.1.0` until D-S2 CI gates are green on `main`. Do NOT self-archive — archival is a founder confirmation. +- **Required checks already done (Class B):** `check-doc-refs` 0 missing on every edited doc; gitleaks full-history clean (104 commits); stale-ref gate green; LICENSE/NOTICE/FAQ public-readiness checks `ok`; core/schemas/oz-dashboard/oz-daemon tests pass except one socket-bind `EPERM` that is a sandbox limitation (re-run in a socket-capable env / CI for full-suite Class A). +- **Explicit founder decisions on record:** external stranger test REMOVED (PD-Q1, 2026-05-27); **D-S1 internal-proxy REMOVED** from v0.1 scope (2026-05-27, run 1wna3uxq — founder dogfoods own projects post-ship); README depth = full pitch + quick-start (PD-Q2=A); `v0.1.0` tag + release notes remain a founder release action. +- **Awareness (not a blocker):** `main` already carries forward-looking design that predates the branch — ADR-0008 (Oz architecture) + a v0.4 roadmap stub. These ship inside `v0.1.0` as roadmap/design, which is normal. The heavy v0.4 prototype tree (`docs/oz-control-plane-design/`), ADR-0010/0012, and designer-notes are correctly excluded. ### Remaining v0.1 work items -1. **D-M1.7** ARCHITECTURE.md Mermaid verification (repo-root). -2. **D-M1.8** README.md adopter rewrite — remove "not yet usable by adopters" banner + stale Sub-Playbook A text (PD-Q2=A; repo-root). -3. **D-M2.1** `docs/dogfood-evidence.md` (Bob, `docs/`). -4. **D-S1** internal-proxy stranger readiness (the retained doc-readiness proof). -5. **D-S2** public-readiness CI gates — gitleaks + LICENSE/NOTICE + faq (`.github/workflows/ci.yml`). -6. **`v0.1.0` tag** + release notes (founder action). +1. ~~D-M1.7 / D-M1.8 / D-M2.1 / D-S2 authoring~~ — **DONE (run 1wna3uxq, on `v0.1-publish`).** +2. **D-RELEASE (founder):** review `v0.1-publish` → merge to `main` → confirm CI green (D-S2 Class A) → tag `v0.1.0` + release notes. ### History - D-M1.1–D-M1.6 + D-M1.9 complete (getting-started, faq in run suesc2sq; orchestration, personas, oz, freshness-policy + ADR-0001 footnote in run zx0s33ag). -- Do not tag `v0.1.0` until the stop conditions above are met. +- D-M1.7, D-M1.8, D-M2.1, D-S2 complete on branch `v0.1-publish` (run 1wna3uxq). +- Do not tag `v0.1.0` until D-S2 CI gates are green on `main`. --- ## Progress -**Last worked:** 2026-05-27 (run zx0s33ag — D-M1.2/1.3/1.4/1.6 docs + D-M1.9 ADR fix; external stranger test removed from scope) -**Current Canon:** Active — Expand. D Milestone 1 docs COMPLETE; remaining = repo-root publish surfaces + CI gates + internal proxy + tag. -**Next action:** D-M1.7 ARCHITECTURE verify + D-M1.8 README rewrite (repo-root — needs wider write boundary), then D-M2.1 dogfood-evidence, D-S2 CI gates (`.github/`), D-S1 internal proxy, then `v0.1.0` tag. See "Next Session Start Here" above. +**Last worked:** 2026-05-27 (run 1wna3uxq — D-M1.7/1.8/2.1 + D-S2 authored on branch `v0.1-publish`; D-S1 removed from v0.1 scope) +**Current Canon:** Active — Expand + Solve authoring COMPLETE on branch `v0.1-publish`. All D doc/gate atoms done; only the founder release sequence (merge → CI-green → `v0.1.0` tag) remains. +**Next action:** **D-RELEASE (founder):** review `v0.1-publish`, merge to `main` (triggers CI = D-S2 Class A proof), tag `v0.1.0` + release notes. See "Next Session Start Here" above. | Canon | Items | Done | Status | |---|---|---|---| | Witness | 1 audit table + objective + scope + current state | 4 | **Complete (2026-05-24)** | | Interrogate | 7 PD-Q + 9 risks + reuse check | 7 + 9 + 5 | **Complete (2026-05-24)** — PD-Q1 revised 2026-05-27 (external stranger test removed) | -| Solve | 2 (D-S1, D-S2) | 0 | Not started (D-S2 needs `.github/` boundary; D-S1 needs proxy actor) | -| Expand | M1: 9 (incl. D-M1.9) · M2: 1 · ~~M3: 3~~ removed · M4: 3 | M1: 7 of 9 | **M1 docs done** (D-M1.1–1.6, 1.9); open: D-M1.7/1.8 (repo-root). M3 external recruit removed from scope. | -| Refine | 4 | 0 | Not started | -| Final Check | 8 | 0 | Not started | +| Solve | ~~2~~ → **1 (D-S2)** | D-S2 authored | **Authored (run 1wna3uxq)** — local Class B passes; Class A (CI green on `main`) pending merge. **D-S1 removed from v0.1 scope (founder 2026-05-27).** | +| Expand | M1: 9 (incl. D-M1.9) · M2: 1 · ~~M3: 3~~ removed · M4: 3 | M1: 9 of 9 · M2: 1 of 1 | **M1 + M2 COMPLETE** (D-M1.1–1.9, D-M2.1 — run 1wna3uxq closed D-M1.7/1.8/2.1). M3 external recruit removed. M4 = founder release. | +| Refine | 4 | 0 | Not started (Master-level; founder) | +| Final Check | 8 | 0 | Founder release sequence (merge → CI green → tag) | ---