let-them-talk 5.2.5 → 5.4.0

package/data-dir.js

@@ -0,0 +1,58 @@
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_DATA_DIR_NAME = '.agent-bridge';
+const DEFAULT_MARKDOWN_WORKSPACE_DIR_NAME = '.agent-bridge-markdown';
+const DATA_DIR_ENV_KEYS = Object.freeze(['AGENT_BRIDGE_DATA_DIR', 'AGENT_BRIDGE_DATA']);
+
+function resolveExplicitDataDir(env = process.env) {
+  for (const key of DATA_DIR_ENV_KEYS) {
+    const value = env[key];
+    if (typeof value === 'string' && value.trim()) return value;
+  }
+  return null;
+}
+
+function isWithinDir(parentDir, childDir) {
+  const relative = path.relative(parentDir, childDir);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function resolveRepoRootForLocalDev(moduleDir = __dirname) {
+  const packageDir = path.resolve(moduleDir);
+  const repoRoot = path.resolve(packageDir, '..');
+
+  if (path.basename(packageDir) !== 'agent-bridge') return null;
+  if (path.resolve(repoRoot, 'agent-bridge') !== packageDir) return null;
+
+  const packageJson = path.join(packageDir, 'package.json');
+  const rootPackageJson = path.join(repoRoot, 'package.json');
+  if (!fs.existsSync(packageJson) || !fs.existsSync(rootPackageJson)) return null;
+
+  return repoRoot;
+}
+
+function resolveDefaultDataRoot({ cwd = process.cwd(), moduleDir = __dirname } = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const packageDir = path.resolve(moduleDir);
+  const repoRoot = resolveRepoRootForLocalDev(moduleDir);
+
+  if (repoRoot && isWithinDir(packageDir, resolvedCwd)) {
+    return repoRoot;
+  }
+
+  return resolvedCwd;
+}
+
+function resolveDataDir({ env = process.env, cwd = process.cwd(), moduleDir = __dirname } = {}) {
+  return resolveExplicitDataDir(env) || path.join(resolveDefaultDataRoot({ cwd, moduleDir }), DEFAULT_DATA_DIR_NAME);
+}
+
+module.exports = {
+  DEFAULT_DATA_DIR_NAME,
+  DEFAULT_MARKDOWN_WORKSPACE_DIR_NAME,
+  isWithinDir,
+  resolveExplicitDataDir,
+  resolveDefaultDataRoot,
+  resolveDataDir,
+};

package/docs/architecture/branch-semantics.md

@@ -0,0 +1,157 @@
+<!-- Generated from ../docs/architecture/branch-semantics.md by scripts/sync-packaged-docs.js for published package consumers. -->
+
+# LetThemTalk Branch Semantics Reference
+
+Status: normative current-runtime branch reference  
+Normative parent: `docs/architecture/runtime-contract.md`  
+Schema companion: `docs/architecture/canonical-event-schema.md`  
+Current-code anchors: `server.js`, `state/canonical.js`, `state/tasks-workflows.js`, `state/agents.js`, `dashboard.js`  
+Last updated: 2026-04-17
+
+This document freezes the implementation-driving meaning of the runtime-contract rule that a branch is a full-context namespace. It reflects the shipped runtime after the branch-local isolation work for delivery and read state, conversation control, non-general channels, workspaces, tasks, workflows, governance surfaces, sessions, and evidence.
+
+Legacy compatibility filenames remain implementation details during migration. They are not a third semantic bucket, and they do not change the rule that agent-visible collaboration state belongs to the branch-local bucket.
+
+## Two-bucket scope model
+
+### Runtime-global bucket
+
+Runtime-global state is the small set that describes the shared local runtime or shared working tree rather than branch reasoning state.
+
+Canonical runtime-global state:
+- agent registry, liveness, heartbeat, branch pointer, and session/branch discovery indexes,
+- profiles,
+- file locks,
+- branch registry plus runtime manifest/migration metadata.
+
+Runtime-owned but non-canonical shared state:
+- plugin registry/code,
+- dashboard discovery, LAN/auth/operator settings, and project lists,
+- temp files, lock files, migration backups, and similar operational artifacts.
+
+Forking or switching branches MUST NOT clone, fork, or reinterpret this bucket.
+
+### Branch-local bucket
+
+Branch-local state is every agent-visible collaboration or reasoning surface.
+
+Shipped branch-local state today:
+- messages/history and canonical branch message events,
+- delivery/read state such as consumed offsets, acknowledgements, read receipts, and compressed history,
+- conversation mode, managed-floor state, phase state, and non-general channel state,
+- workspaces,
+- decisions, KB, reviews, dependencies, votes, rules, and progress,
+- sessions and evidence,
+- tasks and workflows.
+
+Derived branch-local read models:
+- channel projections and other per-branch read models derived from branch-local events.
+
+Switching branches MUST replace the whole migrated branch-local bucket at once. It MUST NOT switch only message/history while leaving the rest shared. The shipped runtime already does that for the branch-local domains above.
+
+## Fork-time snapshot semantics
+
+### Inherited branch-local state
+
+Branch creation snapshots the migrated branch-local state that the current fork implementation explicitly copies from the source branch at the fork point. Snapshot inheritance is copy-on-fork, not a live overlay.
+
+The inherited snapshot includes:
+- visible messages/history at the fork point,
+- delivery/read state and channel projections needed to preserve what each agent had already consumed, acknowledged, or read at the fork point,
+- conversation metadata and non-general channel state,
+- governance state such as decisions, KB, reviews, dependencies, votes, rules, and progress,
+- task/workflow state,
+- historical evidence context relevant to the copied branch-local state, including preserved session references inside copied evidence.
+
+Implementations may materialize the snapshot eagerly or lazily, but reads in the new branch MUST behave as if this full snapshot existed from branch creation onward.
+
+### Non-inherited / shared runtime state
+
+The runtime-global bucket remains shared across branches and is not copied into a new namespace. That includes agent liveness, profiles, locks, branch registry, manifest/migration state, and runtime-owned operator/discovery files.
+
+File locks stay global because the working tree is shared. Lock records may carry branch/session metadata for audit or UI explanation, but the lock scope itself is runtime-global.
+
+### Session and evidence snapshot rules
+
+Historical evidence records are inherited as branch-local context. Active sessions do not stay live across a fork, and the target branch does not start with copied session manifests or cloned live execution.
+
+The first post-fork action on the target branch MUST create or resume a distinct branch-scoped session. After the fork, new evidence recorded in one branch MUST NOT appear in the other branch unless a later explicit cross-branch feature is introduced.
+
+## Branch-local read/write resolution
+
+### Read resolution
+
+A branch-local read resolves against exactly one branch namespace.
+
+Resolution order:
+1. explicit `branch_id`, if provided;
+2. otherwise the caller's active session branch;
+3. otherwise reject the read as under-scoped.
+
+A branch-local read MUST NOT fall back to another branch, to `main`, or to a shared global collaboration file. If a projection is missing or stale, the runtime rebuilds it from the target branch snapshot/events for that same branch.
+
+### Write resolution
+
+A branch-local write resolves against exactly one target branch.
+
+Rules:
+- mutating collaboration commands write to the caller's explicit `branch_id` or active session branch,
+- the write appends canonical events and/or updates projections for that branch only,
+- branch-local writes in branch `B` MUST NOT mutate branch `A`,
+- compatibility-shared legacy filenames during migration are leak points, not semantic exceptions.
+
+Runtime-global writes ignore branch switching for scope purposes, although they may record origin branch/session metadata when that helps explain the action.
+
+### Missing projection / rebuild behavior
+
+Projection absence does not widen scope. Missing branch-local projections are rebuilt from the target branch snapshot and subsequent branch-local events. They are never reconstructed by reading another branch's projection or by treating a global legacy file as the branch source of truth.
+
+## Domain matrix
+
+| Domain | Current storage/runtime reality | Frozen target scope | Fork-time inheritance | Read/write resolution | Migration priority |
+| --- | --- | --- | --- | --- | --- |
+| Messages / history / canonical message events | `server.js` and `state/canonical.js` resolve branch-specific message/history files and branch-local canonical message events | Branch-local | Snapshot visible conversation at fork point, then diverge independently | Read/write only against the selected branch stream/projections | Shipped |
+| Delivery/read markers (`consumed-*`, acknowledgements, read receipts, compressed history) | `state/canonical.js` resolves branch-specific `acks.json`, `read_receipts.json`, `compressed.json`, and `consumed-*` files | Branch-local derived state | Snapshot marker state at fork point | Resolve inside the active branch namespace; no cross-branch fallback | Shipped |
+| Conversation metadata and non-general channels | `state/canonical.js` resolves branch-specific `config.json`, `channels.json`, and non-general channel message/history files | Branch-local | Snapshot mode, phase, manager/floor, membership, and channel history state | Branch switch flips the whole conversation namespace at once | Shipped |
+| Tasks | `state/tasks-workflows.js` and `state/canonical.js` resolve `tasks.json` on `main` and `branch-<branch>-tasks.json` elsewhere through branch-aware mutators and dashboard reads | Branch-local | Snapshot copied at fork point | Read/write only inside target branch | Shipped |
+| Workflows | `state/tasks-workflows.js`, `state/canonical.js`, and `dashboard.js` resolve branch-specific workflow files and branch-aware plan reads | Branch-local | Snapshot copied at fork point | Read/write only inside target branch | Shipped |
+| Workspaces | `state/canonical.js`, `server.js`, and `dashboard.js` resolve `workspaces/<agent>.json` on `main` and `branch-<branch>-workspaces/<agent>.json` elsewhere through branch-aware reads, writes, and export paths | Branch-local per-agent state | Snapshot copied at fork point | Read/write only inside the selected branch workspace namespace | Shipped |
+| Decisions / KB / reviews / dependencies / votes / rules / progress | `state/canonical.js`, `server.js`, `dashboard.js`, and markdown/export validators resolve branch-specific governance projections through canonical branch-aware helpers (`decisions.json` on `main`, `branch-<branch>-*.json` elsewhere) | Branch-local | Snapshot copied at fork point | Read/write only inside target branch; cross-branch summaries iterate branch-local views explicitly | Shipped |
+| Sessions / evidence | Runtime branch session manifests live under `.agent-bridge/runtime/branches/<branch>/sessions/`, with a runtime-global `sessions-index.json` plus branch-specific evidence stores | Branch-local with a runtime-global discovery index | Historical evidence context copies; live sessions do not stay active in the forked branch, and session manifests are not fork-copied | Branch switch suspends one branch session and creates/resumes another | Shipped |
+| Agent registry / profiles | `state/agents.js` persists shared `agents.json`, `profiles.json`, and heartbeat files | Runtime-global | Shared, not copied | Branch switch updates discovery metadata, not branch-local collaboration state | Stay global |
+| Locks / branch registry / manifest / migration metadata | Shared working-tree/runtime surfaces | Runtime-global | Shared, not copied | Never branch-local | Stay global |
+
+## Current leak points / migration-first priorities
+
+### Former P0 leaks now closed
+
+The following Task 4 P0 leak statements are historical reference points now, not current runtime truth:
+
+1. Delivery/read state is still effectively global.
+2. Conversation control and non-general channels still leak.
+3. Forking is still message-centric.
+
+The shipped runtime now isolates those domains with branch-scoped files and branch-aware reads. `check-branch-isolation.js` is the current proof surface for that shipped behavior.
+
+### Remaining compatibility-shared gaps
+
+There are no remaining agent-visible collaboration surfaces that intentionally resolve through shared compatibility governance files in the shipped runtime.
+
+### Next domains to move branch-local
+
+Tasks, workflows, delivery/read state, conversation control, non-general channels, workspaces, governance surfaces, sessions, and evidence are already in the shipped branch-local slice. Future branch work can focus on new features rather than finishing compatibility-shared governance migration.
+
+## Validation path
+
+Run the Task 4A checker with:
+
+```bash
+node scripts/check-branch-semantics.js
+```
+
+That validator proves the reference still contains:
+- the two-bucket model,
+- fork-time snapshot rules,
+- branch-local read/write resolution rules,
+- the domain matrix,
+- the named closed P0 leaks, remaining compatibility gaps, and migration priorities.

package/docs/architecture/canonical-event-schema.md

@@ -0,0 +1,88 @@
+<!-- Generated from ../docs/architecture/canonical-event-schema.md by scripts/sync-packaged-docs.js for published package consumers. -->
+
+# Canonical Event Schema Reference
+
+Status: Task 3A schema-first reference  
+Normative source: `docs/architecture/runtime-contract.md`  
+Code source: `events/schema.js`
+
+This page freezes the first explicit canonical event layer for LetThemTalk without introducing replay or projection rebuilding yet.
+
+## Shared event envelope
+
+All canonical events use one shared envelope shape across both streams.
+
+Required envelope fields:
+
+- `event_id`
+- `stream`
+- `branch_id`
+- `seq`
+- `type`
+- `occurred_at`
+- `schema_version`
+- `actor_agent`
+- `session_id`
+- `command_id`
+- `causation_id`
+- `correlation_id`
+- `payload`
+
+Task 3A keeps one envelope for both streams and allows `branch_id` / `session_id` to be present with `null` when they do not apply yet. Unknown fields are allowed so later replay/projection work can preserve forward-compatible data.
+
+## Scope split
+
+The stream split is explicit in code:
+
+- runtime-global exceptions: `agent.*`, `profile.*`, `lock.*`, `branch.*`, `migration.*`
+- branch-local default for collaboration state: `session.*`, `conversation.*`, `message.*`, `task.*`, `workflow.*`, `workspace.*`, `decision.*`, `kb.*`, `review.*`, `dependency.*`, `vote.*`, `rule.*`, `progress.*`, `evidence.*`
+
+This mirrors the runtime contract rule that shared local-runtime metadata stays global while collaboration-shaped state is branch-local.
+
+## Branch semantics companion
+
+This schema reference freezes which families belong to which stream. Task 4A freezes the rest of the branch contract in `docs/architecture/branch-semantics.md`: the two-bucket model, fork snapshot inheritance, branch-local read/write resolution, and the rule that derived delivery/read state (consumed offsets, acknowledgements, read receipts, compressed history, and non-general channel projections) follows the branch-local message/conversation namespace even before those surfaces are fully rewired.
+
+## Seed family/type registry
+
+The first registry is intentionally small and grounded in current runtime surfaces:
+
+| Family | Stream | Seed event types | Projection targets |
+| --- | --- | --- | --- |
+| `agent` | `runtime` | `agent.registered`, `agent.unregistered`, `agent.status_updated`, `agent.heartbeat_recorded`, `agent.branch_assigned`, `agent.listening_updated` | `agents-index`, `sessions-index` |
+| `profile` | `runtime` | `profile.updated` | `profiles` |
+| `lock` | `runtime` | `lock.acquired`, `lock.released` | `locks` |
+| `branch` | `runtime` | `branch.created` | `branch-index` |
+| `migration` | `runtime` | `migration.started`, `migration.completed`, `migration.failed` | `manifest` |
+| `session` | `branch` | `session.started`, `session.resumed`, `session.interrupted`, `session.completed`, `session.failed`, `session.abandoned` | `sessions`, `sessions-index` |
+| `conversation` | `branch` | `conversation.mode_updated`, `conversation.channel_joined`, `conversation.channel_left`, `conversation.manager_claimed`, `conversation.phase_updated`, `conversation.floor_yielded` | `conversation` |
+| `message` | `branch` | `message.sent`, `message.corrected`, `message.redacted` | `messages`, `history` |
+| `task` | `branch` | `task.created`, `task.updated`, `task.claimed`, `task.completed` | `tasks` |
+| `workflow` | `branch` | `workflow.created`, `workflow.step_started`, `workflow.step_completed`, `workflow.step_reassigned`, `workflow.completed`, `workflow.paused`, `workflow.resumed`, `workflow.stopped` | `workflows` |
+| `workspace` | `branch` | `workspace.written` | `workspaces` |
+| `decision` | `branch` | `decision.logged` | `decisions` |
+| `kb` | `branch` | `kb.written` | `kb` |
+| `review` | `branch` | `review.requested`, `review.submitted` | `reviews` |
+| `dependency` | `branch` | `dependency.declared`, `dependency.resolved` | `dependencies` |
+| `vote` | `branch` | `vote.called`, `vote.cast`, `vote.resolved` | `votes` |
+| `rule` | `branch` | `rule.added`, `rule.toggled`, `rule.removed` | `rules` |
+| `progress` | `branch` | `progress.updated` | `progress` |
+| `evidence` | `branch` | `evidence.recorded` | `evidence` |
+
+These types are the Task 3A seed set for later replay/projection work. They are not a full migration of writes yet.
+
+## Validation path
+
+Run the narrow schema check with:
+
+```bash
+node scripts/check-event-schema.js
+```
+
+That validator proves:
+
+- the shared envelope fields exist,
+- the required family registry exists,
+- the runtime-vs-branch split is encoded,
+- the Task 3A seed event types are registered,
+- sample canonical events validate against the shared envelope.

package/docs/architecture/markdown-workspace.md

@@ -0,0 +1,183 @@
+<!-- Generated from ../docs/architecture/markdown-workspace.md by scripts/sync-packaged-docs.js for published package consumers. -->
+
+# Markdown Workspace Reference
+
+Status: Task 9A projection-first reference  
+Normative parents: `docs/architecture/runtime-contract.md`, `docs/architecture/branch-semantics.md`  
+Schema companion: `docs/architecture/canonical-event-schema.md`  
+Current code anchors: `state/canonical.js`, `state/dashboard-queries.js`, `dashboard.js`, `dashboard.html`  
+Last updated: 2026-04-17
+
+This document freezes the first markdown-workspace contract for LetThemTalk. It is intentionally narrow and implementation-driving for Task 9B: it defines the generated markdown workspace structure, the authority boundary between markdown and runtime state, the current export-source mapping, and the minimum validation markers that must stay true after the branch-local workflow and plan-view export work.
+
+This slice does **not** implement write-back, live sync, watcher loops, or markdown import.
+
+## Non-authoritative authority model
+
+Markdown files are rebuilt from canonical and legacy-compat read models and never treated as runtime inputs.
+
+Authority is frozen as follows:
+
+- Canonical runtime truth remains the broker-owned event/projection model defined in `docs/architecture/runtime-contract.md`.
+- Markdown export is one-way by default: runtime -> markdown workspace.
+- Every exported markdown file MUST set `authoritative: false` in frontmatter.
+- Task 9B MUST NOT implement write-back or live sync loops.
+- The dashboard, CLI, or broker MUST NOT watch markdown edits and reinterpret them as canonical updates.
+- Any future import must be explicit and broker-mediated.
+- Missing, stale, deleted, or manually edited markdown files MUST NOT change runtime behavior.
+
+## Workspace root / layout
+
+Default export root: `<repo>/.agent-bridge-markdown/`
+
+The first safe workspace root lives outside `.agent-bridge/` so runtime storage and markdown projections stay visibly separate.
+
+```text
+.agent-bridge-markdown/
+  README.md
+  branches/
+    index.md
+    <branch>/
+      metadata.md
+      conversations/
+        index.md
+        channels/
+          general.md
+          <channel>.md
+      decisions/
+        index.md
+      sessions/
+        index.md
+        <session-id>.md
+      evidence/
+        index.md
+      workspaces/
+        index.md
+        agents/
+          <agent>.md
+      plans/
+        status.md
+        report.md
+  project/
+    notes/
+      project-notes.md
+      team-notes.md
+```
+
+Required meaning of the first safe structure:
+
+- `README.md` is the generated workspace landing page and repeats the non-authoritative rule.
+- `branches/index.md` lists known branches and points at `branches/<branch>/metadata.md`.
+- `branches/<branch>/metadata.md` is the first branch metadata page.
+- `conversations/` is the conversation export area for that branch.
+- `decisions/`, `sessions/`, `evidence/`, `workspaces/`, and `plans/` are exported from branch-local read surfaces for every branch.
+- `project/notes/project-notes.md` and `project/notes/team-notes.md` are generated cross-branch summaries built from branch-local governance surfaces, not editable runtime inputs.
+
+## Required generated frontmatter
+
+### Common frontmatter
+
+Every exported markdown file MUST carry this minimum frontmatter contract:
+
+```yaml
+ltt_schema: markdown-workspace/v1
+doc_kind: <kind>
+authoritative: false
+branch: <branch-id-or-null>
+projection_of: <domain-or-view>
+source_surface: <read-surface>
+source_scope: <branch_local|runtime_global|compatibility_shared|main_branch_only>
+source_sequence: <stream-seq-or-null>
+generated_at: <iso-timestamp>
+generated_by: let-them-talk-markdown-export
+```
+
+The key meanings are frozen:
+
+- `doc_kind` identifies the page role.
+- `projection_of` names the runtime domain or export view being projected.
+- `source_surface` names the read seam used to build the file.
+- `source_scope` states whether the source is already branch-local or still compatibility-shared.
+- `source_sequence` records the event-stream or projection sequence the markdown snapshot was generated from when one exists.
+
+### Kind-specific frontmatter
+
+Task 9B MUST add the following kind-specific keys on the first safe pages:
+
+| File kind | Required extra keys |
+| --- | --- |
+| `branch-metadata` | `branch_parent`, `branch_source` |
+| `conversation-index` | `channel_count`, `message_count` |
+| `conversation-transcript` | `channel`, `message_count` |
+| `decision-index` | `decision_count` |
+| `session-index` | `session_count` |
+| `session-detail` | `session_id`, `session_state` |
+| `evidence-index` | `evidence_count` |
+| `workspace-index` | `agent_count` |
+| `workspace-agent` | `agent`, `key_count` |
+| `plan-status` | `workflow_id`, `workflow_status` |
+| `plan-report` | `workflow_id`, `workflow_status` |
+| `project-note` | `note_scope` |
+| `team-note` | `note_scope` |
+
+For aggregated plan pages that summarize more than one workflow, `workflow_id` and `workflow_status` MAY be `null`.
+
+## Export-source mapping
+
+Task 9B should assemble markdown through `state/canonical.js` and add thin read-only wrappers there for domains that still live in legacy compatibility files today.
+
+| Markdown output | Current source surface | Current scope rule | Task 9B note |
+| --- | --- | --- | --- |
+| `branches/index.md` | `.agent-bridge/branches.json` plus branch directories under `.agent-bridge/runtime/branches/` | runtime-global branch registry | Build one branch registry page; do not infer hidden branches. |
+| `branches/<branch>/metadata.md` | `.agent-bridge/branches.json` plus branch runtime presence | runtime-global branch registry with branch identity | Safe for every known branch. |
+| `branches/<branch>/conversations/index.md` and `branches/<branch>/conversations/channels/*.md` | `createCanonicalState().getConversationMessages({ branch })`, `getHistoryView({ branch })`, `getChannelsView({ branch })` | branch-local | Use the selected branch only. |
+| `branches/<branch>/decisions/index.md` | `createCanonicalState().listDecisions({ branch })` | branch-local | Export the selected branch decision log only. |
+| `branches/<branch>/sessions/index.md` and `branches/<branch>/sessions/<session-id>.md` | `.agent-bridge/runtime/projections/sessions-index.json` and `.agent-bridge/runtime/branches/<branch>/sessions/*.json` | branch-local with runtime-global discovery index | Index pages summarize branch-local sessions; detail pages point at branch session manifests. |
+| `branches/<branch>/evidence/index.md` | `createCanonicalState().readEvidence(branch)` plus `projectEvidence(...)` enrichment | branch-local | Export evidence indexes from the branch evidence store only. |
+| `branches/<branch>/workspaces/index.md` and `branches/<branch>/workspaces/agents/<agent>.md` | `createCanonicalState().listWorkspaces({ branch })` over `workspaces/<agent>.json` on `main` and `branch-<branch>-workspaces/<agent>.json` elsewhere | branch-local | Export workspace pages for the selected branch only. |
+| `branches/<branch>/plans/status.md` | `createCanonicalState().getPlanStatusView({ branch })` | branch-local | Build the plan status page from the selected branch workflow view. Do not treat this surface as `main`-only anymore. |
+| `branches/<branch>/plans/report.md` | `createCanonicalState().getPlanReportView({ branch })` | branch-local | Build the plan report page from the selected branch workflow report view. Do not treat this surface as `main`-only anymore. |
+| `project/notes/project-notes.md` | `createCanonicalState().listMarkdownBranches()` + `createCanonicalState().getProjectNotesView({ branch })` | runtime-global summary over branch-local sources | Summarize branch-local project guidance across all exported branches without claiming runtime authority. |
+| `project/notes/team-notes.md` | `createCanonicalState().listMarkdownBranches()` + `createCanonicalState().getTeamNotesView({ branch })` | runtime-global summary over branch-local sources | Summarize branch-local collaboration governance across all exported branches without inventing shared copies. |
+
+## Branch and compatibility safety rules
+
+Task 9B MUST follow these safety guards when the markdown workspace is generated:
+
+- Branch-local pages MUST be generated from the selected branch only.
+- Governance pages and cross-branch note summaries MUST read branch-local governance views; they MUST NOT fall back to shared legacy governance files.
+- Branch-local workspace pages MUST read `listWorkspaces({ branch })` for the selected branch. They are no longer part of the compatibility-shared or `main`-only bucket.
+- Branch-local plan pages MUST read `getPlanStatusView({ branch })` and `getPlanReportView({ branch })` for the selected branch. They are no longer part of the shared or `main`-only bucket.
+- Project and team notes may summarize multiple branch-local surfaces at once, but they MUST keep `authoritative: false` and a truthful `source_scope` value.
+- Re-export MAY replace previously generated markdown files. Preservation of manual edits is not part of this contract slice.
+- Markdown export failure MUST NOT block canonical runtime writes.
+
+## Task 9B implementation seam
+
+The best low-churn export assembly point is `state/canonical.js`.
+
+The best outward-facing seam is the existing dashboard export family (`/api/export-json`, `/api/export`, and `/api/export-replay`), not a watcher loop.
+
+Task 9B should therefore:
+
+- add read-only markdown-export helpers or wrappers to `createCanonicalState(...)`,
+- reuse the existing dashboard export shape conventions for branch/version/exported-at metadata,
+- treat the current `dashboard.html` markdown export as conversation-only compatibility behavior rather than the authority model for the workspace,
+- avoid introducing a second side channel that bypasses broker-owned read surfaces.
+
+## Validation path
+
+Run the Task 9A checker with:
+
+```bash
+node scripts/check-markdown-workspace.js
+```
+
+That validator proves the reference still contains:
+
+- the non-authoritative markdown rule,
+- the default workspace root and first safe layout,
+- the required frontmatter contract,
+- the export-source mapping,
+- the branch/main-only compatibility safety rules,
+- the Task 9B implementation seam.