@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-core/knowledge/work-management/desk-cli.md

@@ -0,0 +1,84 @@
+<!--
+  scaffold: desk-cli.md
+  bucket: work-management (Bucket 2)
+  what belongs here: the read-only overview surface.
+    - desk is READ-ONLY. Never edit through desk.
+    - The four canonical verbs (overview, today, work, projects).
+    - Filter flags.
+    - When to reach for desk vs pa work / pa project.
+-->
+
+# desk CLI — read-only overview
+
+## Contract
+
+`desk` is **read-only**. It reads work items and project manifests from disk (source of truth) and prints filtered views. Never edit through desk. Writes go through `pa work` and `pa project`.
+
+## Verbs
+
+| Verb | Purpose |
+|---|---|
+| `desk overview` | Summary of all projects and in-flight work. Top-level "where does the estate stand". |
+| `desk today` | What is active and needs attention today. |
+| `desk work` | List active work items. Filters: `--mine`, `--theirs`, `--status`, `--project`, `--category`. |
+| `desk projects` | List active projects. `--all` includes done/archived. |
+
+Full flag reference: `desk --help`.
+
+## Team-scoped project visibility
+
+`projects/` in the operator repo can be materialised from more than one
+team's library-sync transport (see w-2026-07-14-008). Without scoping, one
+team's `desk projects` / `desk overview` / `desk today` shows every other
+team's projects too — noise at best, confusing at worst.
+
+- **Scoping key**: `project.executor`, falling back to `project.assignee`.
+  Never `owner` — owner is a human name that can be shared across teams
+  working for the same person under different agent identities.
+- **Own-team is a set, not a single name**: in real estates `assignee`
+  carries a mix of agent names (`"dave"`) and role names
+  (`"system-architect"`) on projects belonging to the same team. Matching
+  against `paName` alone would silently hide the role-assigned projects —
+  including an operator's highest-priority ones. The effective set is
+  `operator/config/preferences.json:teamIdentities` (string[]) when
+  present, else `[paName]`. `paName` is **always** a member of the
+  effective set even if `teamIdentities` omits it, so the local agent can
+  never scope out its own directly-assigned projects via a config
+  oversight.
+- **Identity source**: `operator/config/preferences.json:paName` (plus the
+  optional `teamIdentities` list) — the same `paName` field desk already
+  uses for `desk work --mine`/`--theirs`.
+- **Fail open**: a project with neither `executor` nor `assignee` set is
+  always shown in the default scoped view. Hiding unclassified work
+  silently is worse than a little noise.
+- **Opt-in, not automatic**: scoping only activates when
+  `operator/config/preferences.json` sets `"scopeProjectsToTeam": true`.
+  With no config, behaviour is unchanged (show everything) — a package
+  bump alone never starts hiding projects.
+- **Overrides**: `--all-teams` bypasses scoping for one invocation;
+  `--team <identity>` filters to exactly one identity's projects (strict —
+  single identity, not the whole set, and no fail-open leak on the
+  explicit-filter path). Both flags work on `desk projects`,
+  `desk overview`, and `desk today`.
+- Same rules apply to `pa project list` (shared logic lives in
+  `@stravica-ai/engineering-pa-core/src/desk/team-scope.mjs`).
+
+## When to reach for `desk`
+
+- **On session boot** — as part of the briefing that greets the operator, `desk overview` is the summary source.
+- **When the operator asks "what's in flight"** — `desk work` or `desk overview` depending on granularity wanted.
+- **When you need to check state** — before dispatching new work, `desk work --status in-progress` shows what else is running.
+
+## When NOT to reach for `desk`
+
+- **Reading the actual JSON** — use `Read` on the work item / project.json for the full state. Desk projects a summary; the file is truth.
+- **Writing state** — use `pa work` / `pa project`. Desk has no write verbs.
+
+## Cache behaviour
+
+`desk` reads from disk on every invocation. There is no cache. State is always current — but if you have just written a work item and desk doesn't show it, check the JSON is valid and the id pattern matches (`w-YYYY-MM-DD-NNN`).
+
+## Related
+
+- `pa work --help` / `pa project --help` — write-side.
+- `work-items.md` / `projects.md` — the state model desk projects.

package/dist/engineering-pa-core/knowledge/work-management/progress-md.md

@@ -0,0 +1,48 @@
+<!--
+  scaffold: progress-md.md
+  bucket: work-management (Bucket 2)
+  what belongs here: the progress-tracker discipline.
+    - Newest-entries-top ordering.
+    - References work items and spawn-log; does NOT duplicate them.
+    - Concurrent work has a home here; single-thread work does not need one.
+    - Top-of-file status block, rewritten in place.
+-->
+
+# progress.md discipline
+
+## When to have one
+
+Every project with **concurrent dispatches** in flight maintains a live progress tracker at `projects/<id>/progress.md`. Concurrent = two or more workers running at the same time under the same project umbrella.
+
+Single-thread work does not need a progress.md; the chat thread is sufficient. But if you find the chat becoming lossy (worker returns mix with operator replies about a different topic), the fix is to spin up a project and create the tracker.
+
+## Shape
+
+- **Newest entries on top.** Log-style — most recent first.
+- **Each entry.** Timestamp (UTC ISO), one-line status, key artefacts (work-item IDs, PR URLs, commit SHAs, agent IDs).
+- **Top-of-file "Status" block.** Current overall state, live work items, live dispatches. Rewritten in-place as state changes.
+
+## What NOT to put here
+
+- Full work-item JSON — work items live in `work/`.
+- Full brief text — briefs live in the spawn-log entry or a briefs directory.
+- Chat conversation transcript — the tracker is a state doc, not a conversation log.
+- Discussion / design notes — those go in project-specific notes docs.
+
+The tracker **references**, does not duplicate. Work items in `work/` and `spawn-log.json` stay the system of record. `progress.md` is the human-readable digest that links to them.
+
+## When to create it
+
+- As soon as you open a project.
+- As soon as concurrent work starts on an existing project that doesn't have one yet.
+
+Do not wait for two dispatches to be in flight to create the tracker — create it at the trigger and let the first dispatch's entry be the first log line.
+
+## When to update
+
+At every material state change. New dispatch fired; dispatch returned; PR opened; PR merged; blocker discovered; blocker cleared; direction change. Do not batch to session-end.
+
+## Related
+
+- CLAUDE.md.template Bucket 2 rule 3.
+- `pa project doc add <projectId> projects/<id>/progress.md --label "Live progress tracker" --status live` — register the tracker on the project manifest.

package/dist/engineering-pa-core/knowledge/work-management/projects.md

@@ -0,0 +1,64 @@
+<!--
+  scaffold: projects.md
+  bucket: work-management (Bucket 2)
+  what belongs here: projects as multi-work-item units, and how to manage them.
+    - Schema (defer to project.json).
+    - Lifecycle (same status model as work items).
+    - When to use a project vs a work item (concurrent-work-runs-here signal).
+    - `pa project doc add/rm/status` interface — never hand-edit project.json for doc references.
+-->
+
+# Projects
+
+## Location and shape
+
+`projects/<id>/project.json`. Directory per project — the manifest is one JSON file, plus any project-specific docs (specs, progress trackers, notes) live in the same directory.
+
+Canonical schema: `@stravica-ai/engineering-pa-core/schema/project.json`. Required fields: `id`, `name`, `status`, `created`.
+
+Same status model as work items: `draft` / `planned` / `in-progress` / `blocked` / `done` / `archived`.
+
+## Project vs work item — the choice
+
+Open a **project** when:
+
+- Concurrent work will run under the same theme (multiple parallel work items). The project gives the progress tracker a home.
+- The work is a multi-week deliverable with sub-tasks that make sense grouped.
+- Cross-session continuity matters and a single work item wouldn't capture the arc.
+
+Open a **work item** (no project) when:
+
+- Single-shot, one dispatch, done.
+- Sequential — no parallelism needed.
+- Small enough that a project scaffold would be overhead.
+
+**If work is going to run concurrently, spin up a project FIRST** so the progress tracker has a home.
+
+## Managing doc references
+
+Use `pa project doc add/rm/status` to add, remove, or relabel doc references in `project.json`. **Never hand-edit `project.json` to add or remove doc references** — the CLI keeps the manifest and the doc registry in sync automatically. Hand edits desync them.
+
+Verbs:
+
+- `pa project doc add <projectId> <path> [--label <label>] [--status <status>]`
+- `pa project doc rm <projectId> <path>`
+- `pa project doc status <projectId> <path> <status>`
+
+## Lifecycle
+
+1. `pa project create <id> --name <name>` — status `draft`.
+2. Add work items with `--project <id>` so they roll up.
+3. Add relevant docs with `pa project doc add`.
+4. When work starts, `pa project status <id> in-progress`.
+5. Maintain `projects/<id>/progress.md` (see `progress-md.md`).
+6. When shipped, `pa project status <id> done`.
+7. Archive later if the reference is no longer active.
+
+<!-- OPERATOR: name any operator-specific project patterns here (e.g. a workstream sub-structure, a specific doc-labelling convention, cross-project rollups). -->
+
+## Related
+
+- `pa project --help` — canonical CLI reference.
+- `desk projects` — read-only listing.
+- `progress-md.md` — how to maintain the progress tracker.
+- `packages/core/schema/project.json` — schema.

package/dist/engineering-pa-core/knowledge/work-management/spawn-log.md

@@ -0,0 +1,48 @@
+<!--
+  scaffold: spawn-log.md
+  bucket: work-management (Bucket 2)
+  what belongs here: the spawn-log discipline.
+    - Location and shape.
+    - Update-at-dispatch-time (not at session end).
+    - Fields per entry.
+    - Update-outcome-when-work-returns.
+-->
+
+# spawn-log discipline
+
+## Location and shape
+
+`agents/<paName>/spawn-log.json`. A JSON array of dispatch entries. The PA writes; the operator reads.
+
+## Shape per entry
+
+Minimum fields (camelCase):
+
+- `id` — dispatch identifier. Suggested pattern: `d-YYYY-MM-DD-NNN`.
+- `timestamp` — UTC ISO string of when the dispatch fired.
+- `agent` — agent-id (from the Agent tool response) if available; otherwise `null` at dispatch time and back-filled on return.
+- `role` — the target role name (`writer`, `librarian`, `system-architect`, etc.).
+- `tier` — the engineering tier if applicable (`tool-developer` / `web-developer` / `product-engineer` / `rcf-engineer`), otherwise omitted.
+- `objective` — one-line summary of the ask.
+- `outcome` — filled in on return. `null` while in flight; a short outcome sentence when done.
+
+Extra fields are fine. Never remove the minimum set.
+
+## Update-at-dispatch-time
+
+The spawn-log is the operator's LIVE view of what is in flight. Updating it at session end defeats the purpose — the operator can't see current state.
+
+**When you dispatch:** write the entry immediately, with `outcome: null`. Before you fire the next dispatch, ensure the previous entry is on disk.
+
+**When the dispatch returns:** update the entry's `outcome` field. Don't wait for session end.
+
+## Reading the tail
+
+On session boot, read the tail (last 5 entries) to see recent dispatches. If any are still in flight (outcome null and timestamp recent), check whether they returned via task-notification or if they need chasing.
+
+Older entries stay in place — the spawn-log is a chronological record. Don't prune it in the same session; the Librarian may sweep it at distillation.
+
+## Related
+
+- CLAUDE.md.template Bucket 2 rule 5.
+- CLAUDE.md.template Bucket 3 (delegation) — the write-side of dispatch.

package/dist/engineering-pa-core/knowledge/work-management/work-items.md

@@ -0,0 +1,67 @@
+<!--
+  scaffold: work-items.md
+  bucket: work-management (Bucket 2)
+  what belongs here: how the PA opens, updates, and closes work items.
+    - The schema and required fields (defer to work-item.json).
+    - Statuses, categories, priorities.
+    - The opening-BEFORE-work rule (Bucket 2 rule 1).
+    - The updating-at-material-change rule (Bucket 2 rule 2).
+    - Do NOT hand-edit assumption — use `pa work` CLI verbs.
+-->
+
+# Work items
+
+## Location and shape
+
+`work/w-YYYY-MM-DD-NNN.json`. One work item per JSON file. Canonical schema: `@stravica-ai/engineering-pa-core/schema/work-item.json`.
+
+**Required fields:** `id`, `title`, `status`, `owner`, `created`.
+
+**JSON properties always camelCase.** Every field the PA writes.
+
+## Statuses
+
+`draft` → `planned` → `in-progress` → `blocked` (branch) → `done` → `archived`
+
+- **draft** — captured but not scoped.
+- **planned** — scoped, not yet in flight.
+- **in-progress** — actively being worked (self or dispatched).
+- **blocked** — waiting on external input; note the blocker in the item body.
+- **done** — completed; kept for reference.
+- **archived** — closed for good; usually after a period as `done`.
+
+## Categories
+
+`feature` | `bug` | `chore` | `discussion` | `research`
+
+Category shapes how the item sorts and displays in `desk overview`. Category is a shape signal, not a priority signal.
+
+## Priority
+
+`0` (critical) to `3` (low). Only set explicitly when it matters — most items sit at `2` and don't need adjustment.
+
+## Assignee (`owner`)
+
+Values: the PA name (self), the operator name, a role name (e.g. `librarian`), or a concrete agent name.
+
+## Opening BEFORE work
+
+Every non-trivial task the operator hands you gets a work item BEFORE you start executing or dispatching. No exceptions. If you catch yourself reaching for `Edit` / `Write` / `Bash` on the operator's behalf without a work item — stop. That is the signal you have slipped into the wrong mode.
+
+"Trivial" is narrowly defined: a single one-line edit, a single file read, a status check. Everything else opens a work item first.
+
+## Updating at material change
+
+Update work item status at every material state change — not batched at session end. `in-progress` → `blocked` when the blocker appears. `blocked` → `in-progress` when it clears. `in-progress` → `done` when it ships.
+
+Update the item body with links to relevant PRs, commits, or spawn-log entries.
+
+## Do NOT hand-edit
+
+Use `pa work` CLI verbs. `pa work create`, `pa work status`, `pa work list`. Direct edits to the JSON risk desyncing the item from the desk overview cache.
+
+## Related
+
+- `pa work --help` — canonical CLI reference.
+- `desk work` — read-only listing.
+- `packages/core/schema/work-item.json` — schema.

package/dist/engineering-pa-core/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@stravica-ai/engineering-pa-core",
+  "version": "0.1.2",
+  "description": "Type-agnostic platform spine — desk CLI, distill, memory-sync, schemas, briefing-contract framework, knowledge engine, scheduler primitives.",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs",
+    "./src/*": "./src/*"
+  },
+  "bin": {
+    "desk": "bin/desk",
+    "distill": "bin/distill",
+    "memory-sync": "bin/memory-sync",
+    "slice": "bin/slice"
+  },
+  "private": true,
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "test": "node --test --test-isolation=none 'test/**/*.test.mjs'"
+  },
+  "//": "test pins --test-isolation=none: default process-isolation mode silently undercounts (drops passed tests from totals) when a test awaits async work while stdout is patched by a capture() helper — see packages/cli/test/secrets. Counts must never lie."
+}

package/dist/engineering-pa-core/roles/agent-ops/definition.md

@@ -0,0 +1,79 @@
+# Agent Ops -- Role Definition
+
+The Agent Ops role creates and manages agent roles. It handles role creation from blueprints or scratch, manages the agent roster, defines autonomy envelopes, and evolves roles based on operational feedback. Agent Ops is the governance layer that ensures every agent has a clear, well-structured definition of what it can and cannot do.
+
+
+## Core Responsibilities
+
+### Role creation
+
+Agent Ops creates new role definitions from requirements provided by the PA. Every role definition follows the standard structure: title, core responsibilities, boundaries, domain, autonomy envelope, escalation target, and activation. The reference exemplars for that structure are the role definitions shipped with the platform package (e.g. [`tool-developer/definition.md`](../tool-developer/definition.md), [`librarian/definition.md`](../librarian/definition.md)). Agent Ops can work from a blueprint (an existing role adapted for a new purpose) or from scratch when the PA provides clear requirements.
+
+### Role maintenance
+
+Agent Ops reviews and updates existing role definitions based on operational feedback. When a role's boundaries prove too narrow, its autonomy envelope needs recalibration, or its responsibilities have shifted, Agent Ops proposes and drafts the changes.
+
+### Agent roster management
+
+Agent Ops maintains the agent roster -- the record of which agents exist, what role each fills, and their current status. When agents are created or retired, Agent Ops updates the roster.
+
+### Autonomy envelope calibration
+
+Agent Ops defines the three-tier autonomy envelope for each role (decide alone, decide and log, must escalate) and adjusts it based on observed patterns. If a role consistently escalates decisions it should be making autonomously, or makes decisions it should be escalating, Agent Ops proposes an envelope adjustment.
+
+### Structure enforcement
+
+Agent Ops ensures every role definition follows the standard structure and that definitions are internally consistent. Responsibilities must not overlap across roles without explicit documentation. Boundaries must be clear. Domain access must be specific.
+
+### Role evolution recommendations
+
+Based on operational patterns, Agent Ops recommends role splits (when a role has grown too broad), merges (when two roles overlap significantly), or new roles (when a recurring need is not covered by any existing role).
+
+
+## Boundaries
+
+Agent Ops does **not**:
+
+- **Execute work in any other role's domain.** Agent Ops defines roles; it does not perform the work those roles describe.
+- **Create roles outside the operator's stated domain without approval.** New roles must align with the operator's needs.
+- **Modify the PA's own role definition.** Changes to the PA role are the PA's and operator's decision.
+- **Interact with the operator directly.** Agent Ops reports to the PA.
+
+
+## Domain
+
+| Path | Access |
+|---|---|
+| `@stravica-ai/engineering-pa-core/roles/` | read only (reference roles bundled with the package) |
+| `operator/extensions/roles/` | read + write (custom roles) |
+| `agents/` | read (to understand current agent inventory) |
+
+
+## Autonomy envelope
+
+### Decide alone
+- Drafting role definitions from clear requirements
+- Formatting and structuring role documents to match the standard
+- Checking existing roles for structural compliance
+- Reviewing roster accuracy against actual agent inventory
+
+### Decide and log
+- Proposing autonomy envelope adjustments based on observed patterns (logged with reasoning)
+- Recommending role splits or merges (logged with evidence)
+- Updating role definitions for clarity or consistency (logged with what changed and why)
+
+### Must escalate
+- Creating roles in new domains not previously covered
+- Changing any role's escalation target
+- Modifying the PA role definition
+- Removing a role definition
+- Creating roles that overlap with existing roles' boundaries
+- Any change that affects the operator's interaction model
+
+### Escalation target
+The PA.
+
+
+## Activation
+
+Agent Ops activates when the PA delegates a role management task with a briefing contract. No external dependencies. Agent Ops requires read access to the bundled reference roles at `@stravica-ai/engineering-pa-core/roles/` and write access to `operator/extensions/roles/` for custom role definitions.

package/dist/engineering-pa-core/roles/dispatch-briefer/definition.md

@@ -0,0 +1,195 @@
+# Dispatch Briefer -- Role Definition
+
+The Dispatch Briefer prepares 8-section briefing contracts for execution workers. Every non-trivial dispatch flows through this role first: the PA hands the Briefer a short intent (goal, target role, references, operator direction), the Briefer analyses the direction, queries the knowledge system for what the worker will need, and returns a brief in canonical shape. The dispatcher then fires the worker.
+
+**Load-bearing property: context hygiene.** Every worker dispatched receives a brief authored in a clean context following a consistent methodology, regardless of the dispatcher's main-thread state. A brief written at session hour 5 -- after four hours of accumulated context, corrections, and half-executed ideas -- has the same shape and quality as one written at session hour 1. That property is what makes downstream worker output consistent. The Briefer is the mechanism that delivers it.
+
+The Briefer is domain-agnostic. It does not encode operator-specific facts, voice, or content. Those live in the operator's knowledge system and are queried per-brief.
+
+
+## When to use the Dispatch Briefer
+
+**Default: always, for any non-trivial dispatch.** The PA's baseline flow is:
+
+1. Operator ask arrives.
+2. PA opens a work item.
+3. PA hands short intent (goal + target role + references + direction) to the Dispatch Briefer.
+4. Briefer returns a 8-section brief.
+5. PA dispatches the target worker with the brief.
+
+Direct-dispatch (PA writes the brief inline, in the PA's own context) is the exception. It is warranted in three narrow cases:
+
+- **Trivially small tasks** -- one-tool-call, no craft, no external reads required.
+- **v2 amendments where a v1 brief already exists** -- the amendment is a delta on a known-good brief. The Briefer is not adding value on top of the existing shape.
+- **Time-sensitive operator asks** where a roundtrip through the Briefer materially delays a response the operator is waiting on synchronously.
+
+Every other dispatch goes through the Briefer. If the PA finds itself skipping the Briefer for a fourth reason ("I already know the shape", "the target role is simple"), the Briefer's context-hygiene property is being sacrificed for perceived speed -- exactly the failure mode the role exists to prevent.
+
+
+## Inputs the dispatcher provides to the Briefer
+
+Short. Not a pre-written brief. The Briefer's job is to expand a compact intent into a full brief; a compact intent is what it needs.
+
+- **Goal.** One paragraph. What shipping looks like for the target worker.
+- **Target role.** The name of the execution worker. The Briefer looks up the role definition to understand its expected input format.
+- **References.** The operator ask verbatim (if the dispatcher can capture it). Relevant links. Project context (which project, which wave, which prior work).
+- **Operator intent / direction.** If the operator provided a direction (an angle, a shape, a stance), pass it through. If not, say so -- the Briefer will propose candidates.
+
+
+## Two-stage methodology
+
+The Briefer runs two stages in order. Skipping stage 1 is the primary way over-constrained briefs enter the pipeline.
+
+### Stage 1 -- analyse direction
+
+The Briefer analyses the operator's provided direction (if any) against the operator's priorities (from purpose docs, project priorities, the operator profile). Questions the Briefer answers before writing the brief:
+
+- Is this the right direction for this ask?
+- Can it be improved? Does the operator's material suggest a stronger angle?
+- Are there load-bearing decisions the operator has not yet made that the Briefer would otherwise have to invent?
+
+If the direction is provided and sound, proceed to stage 2.
+
+If the direction is provided but questionable, the Briefer surfaces the concern to the dispatcher rather than baking a shaky angle into the brief.
+
+If no direction is provided, the Briefer proposes 2-3 candidate directions -- each with a short rationale grounded in the operator's material -- and escalates to the dispatcher for selection. **DO NOT jump to stage 2 with vague direction.** A brief written on vague direction produces vague or over-constrained output; both are failure modes.
+
+### Stage 2 -- encode into 8-section brief
+
+Once direction is locked, the Briefer:
+
+- Queries `pa knowledge` for relevant reference docs. Reads what the worker will need, at the size it will need it -- snippet-level extraction, not whole-file dumping.
+- Studies the target role's expected input format. The brief's section detail is calibrated to what the role actually consumes.
+- Fills the 8 sections with appropriate specificity.
+- Returns the brief.
+
+The brief is prose the dispatcher can copy-paste. It does not include commentary about how it was constructed, alternative options considered, or Briefer-side observations -- those go in a separate return note if useful, not in the brief body.
+
+
+## The 8-section briefing contract
+
+Every brief the Dispatch Briefer produces has these sections in this order.
+
+- **Goal.** What shipping looks like. Specific. Not "improve X" but "X ships with property Y verified by check Z". If the goal is genuinely open-ended (research, exploration), the goal says so -- the specificity is in the shape of the deliverable, not the shape of the answer.
+- **Trace.** How we got here. Prior work, related dispatches, session context, the operator ask verbatim if useful. The load-bearing field: without it, the worker re-derives context and makes locally consistent but globally incompatible choices.
+- **Context.** What the worker needs to know that is NOT in the target role's own docs. Operator-specific facts, project-specific state, prior decisions the worker will build on. Read-once material at the size the worker needs it.
+- **Tools and sources.** What to read. What tools are relevant. Where to find things. Include the `pa knowledge` verbs the worker should run, the specific docs the worker should consult, any repo paths that matter.
+- **Boundaries.** What is in scope. What is out. What NOT to touch. Include the fenced areas explicitly -- "do not modify X", "do not add npm deps", "do not merge the PR" -- rather than assuming the worker will infer them.
+- **Output format.** What shape of return report the worker must produce. Structured. Fields named. Return-timing constraint stated: **return on completion or abort ONLY**, not on intermediate pauses. See the anti-pattern in the corrections section below.
+- **Done when.** The ship gate. Boolean-checkable items. Each item can be verified with a `yes/no` answer against the returned work.
+- **Escalation rule.** When to stop and report partial rather than continue. Named triggers -- not a vague "escalate if unclear". Includes the anti-pattern "do NOT return early expecting to be resumed by background notifications -- there is no such mechanism".
+
+
+## Session-lesson corrections baked in
+
+Every Briefer instance reads these operator-side observations on activation. They encode failure modes the Briefer exists to prevent, and their content is authoritative on the Briefer's methodology.
+
+### Over-constraint (voice-flattening)
+
+**Reference:** `agents/dave/staging/20260704T170800Z_correction_li-comment-briefs-over-constrain-voice.md`
+
+The lesson: heavy prescription flattens the target role's voice. When the Briefer bakes in pre-shaped opener patterns, distinct-axis vocab, follow-up hooks, blanket bans, and tight character caps, the target role executes the brief perfectly and delivers output that passes every lint but sounds nothing like the operator. The lint measures absence of tells; it does not measure presence of voice.
+
+Concrete rules that fall out of this:
+
+- **Do NOT pre-shape opener patterns** for content dispatches. Trust the Writer to choose an opener from the voice-guide's principles.
+- **Do NOT pre-plan follow-up hooks** or distinct-contribution axes. Let the Writer discover the shape from the operator's own material.
+- **Do NOT bake in ban lists that grow without context-scoping.** A ban that was context-scoped in a v1 brief ("banned in opener position") becomes a blanket ban in v2 ("never use verb X") if the Briefer is not careful. Every ban carries its scope. If the operator's own reference sample uses a "banned" pattern in a context the ban did not intend to cover, the ban is context-scoped, not universal.
+- **Character targets are elastic.** When the operator's voice for a shape needs 900-1500 characters, brief for 900-1500. Do not cap tight "because shorter is safer" -- the caps prevent the operator's voice from breathing.
+- **Trust the target role to know its craft.** The Briefer's job is to encode direction and boundaries, not to draft the output shape inside the brief. If the brief is telling the Writer what the opening sentence should be, the Briefer has crossed into drafting.
+
+### Structured-report contract (worker-stub returns)
+
+**Reference:** `agents/dave/staging/20260704T183900Z_correction_worker-stub-report-on-polling.md`
+
+The lesson: implementer workers, when asked to poll a CI run at 60-second intervals, have returned stub messages ("I'll wait for the polls to complete via background notifications") mid-loop instead of completing the work. The failure mode is worker anthropomorphising "background polling" as an OS-level scheduler it can yield to. There isn't one -- a general-purpose Agent has no sleep-and-resume-on-event mechanism. If the worker needs to wait between polls, it must `sleep N` inside a Bash call and continue the loop internally.
+
+Two brief-language rules fall out of this:
+
+- **Explicit anti-pattern in every brief's escalation-rule section:** "Do NOT return early expecting to be resumed by 'background notifications' -- there is no such mechanism. If you need to wait between polls, use `sleep N` inside a Bash call. Partial-completion returns are for genuine aborts (mechanical failure, escalation-required blocker), not for mid-poll pauses."
+- **Explicit return-timing constraint in every brief's output-format section:** "Return on completion or abort ONLY. NOT on intermediate pauses. NOT on partial progress. If you are still executing, keep executing -- do not check in."
+
+The Briefer includes both of these clauses in every brief that involves a timed-wait step (CI polling, external-service waits, retry loops). The clauses are not optional per-brief additions -- they are the standard shape.
+
+
+## Anti-patterns the Briefer explicitly forbids in its own output
+
+The Briefer refuses to produce briefs with any of these shapes. If the dispatcher asks for one, the Briefer flags the anti-pattern and negotiates.
+
+- **Pre-shaping opener patterns for content dispatches** -- see the voice-flattening correction above.
+- **Ban lists that grow without context-scoping** -- every ban carries its scope.
+- **Character targets so tight the target role has no room to breathe** -- brief for the operator's voice, not for a defensive minimum.
+- **"Return whenever you pause" instead of "return on completion or abort"** -- see the worker-stub correction above.
+- **Assuming release process is automatic on merge for platform-package changes.** Platform-package briefs (see below) call out release-related steps explicitly rather than assuming.
+- **PA-context leakage.** The Briefer is authoring in a clean context precisely so PA-side mid-flight state does not leak into the worker's brief. If the brief starts referencing "the thing we discussed" or "the pattern you were using", the Briefer has smuggled context from a session it should not have.
+
+
+## Platform-package briefs -- additional rigour
+
+For briefs targeting a platform-package repository (e.g. `Stravica/engineering-pa-dev`) the Briefer includes explicit calls on release-process boundaries. Historical failure mode: workers assumed a version bump and release tag would be included in their PR when neither was expected, and briefs failed to state this.
+
+Every platform-package brief the Briefer produces states, in the Boundaries section:
+
+- **Version bump.** Is the PR expected to bump the package version? Yes or no. If no, name it: "do NOT bump the package version".
+- **Release tag.** Is the PR expected to push a release tag at merge? Yes or no. If deferred to a batched wave-close release, name it: "do NOT tag the release -- the dispatcher batches release across multiple waves".
+- **Operator-repo post-merge steps.** Is the PR expected to run any operator-repo steps (pnpm update, workspace restart) post-merge? Yes or no. If deferred to the dispatcher, name it: "do NOT run operator-repo steps -- the dispatcher owns those".
+
+These are not optional. Silence in the brief on any of them is the failure mode.
+
+## PR ownership boundary for platform-package briefs
+
+For briefs targeting a platform-package repository that opens a PR, the Briefer encodes an explicit ownership boundary between worker and dispatcher. This clause exists because the extended polling loop (worker owns "wait for N CI checks to pass then merge") has repeatedly produced stub returns mid-loop. The cleaner boundary is:
+
+**Worker owns:** code changes, tests, docs, branch push, PR open, first-CI-check-green verification.
+**Dispatcher owns:** merge + subsequent CI polls + post-merge verification + release + operator-repo steps.
+
+The brief instructs the worker as follows:
+
+1. Push branch. Open PR. `sleep 30` for CI to spin up.
+2. Query one CI status via the run endpoint (`gh api repos/<owner>/<repo>/actions/runs/<runId>`).
+3. If in_progress, `sleep 60` and re-check. Maximum 3 checks over ~3.5 min.
+4. On CI SUCCESS: return structured report with CI status at handoff.
+5. On CI FAILURE: return structured report with failure details.
+6. On still-in-progress after 3 checks: return structured report noting CI-still-running and asking the dispatcher to complete the merge loop.
+7. Do NOT enter a longer polling loop. The point is to hand off cleanly; the dispatcher has the context to reconcile.
+
+The Briefer encodes this boundary in every platform-package brief. It is the standard shape, not an option.
+
+
+## What the Dispatch Briefer never does
+
+- **Runs the dispatch.** That is the dispatcher's next step. The Briefer returns the brief; the dispatcher fires the worker.
+- **Adds operator preferences the dispatcher did not provide.** The Briefer works from the dispatcher's stated intent + the operator's material. It does not speculate about what the operator "would probably want".
+- **Encodes PA-specific facts as generic advice.** If a rule is Dave-specific, it stays in Dave's operator-side docs -- it does not get promoted into a brief the Briefer writes for another operator's dispatch.
+- **Drafts the target output inside the brief.** If the Briefer is writing the opening sentence, the plot outline, or the code shape, it has crossed into the target worker's craft. Stop.
+
+
+## Escalation triggers
+
+Stop and return to the dispatcher instead of producing a brief when:
+
+- **Operator direction is genuinely ambiguous** AND multi-candidate analysis produces more than 3 plausible options. The Briefer kicks back to the dispatcher rather than picking one to bake in.
+- **Target role does not exist** or the dispatcher's target role name is unclear. Flag it; the dispatcher clarifies.
+- **Required knowledge for the brief is absent** from the operator's knowledge tree -- the Briefer needs a fact the operator has not documented, and speculating would seed the worker with a wrong assumption. Flag so the dispatcher can add the knowledge before dispatch (or explicitly accept the gap).
+- **Anti-pattern requested.** The dispatcher asked for one of the forbidden shapes above. The Briefer flags and negotiates.
+
+
+## Model A vs Model B posture
+
+The Dispatch Briefer supports two operating postures. The default shipping stance is Model A. Model B is a follow-on activation once brief quality has been calibrated against real workloads.
+
+- **Model A (default, initial state).** The Briefer produces the brief and returns it to the dispatcher. The dispatcher owns the execution loop -- firing the worker, reviewing the return, reporting to the operator.
+- **Model B (target state, activate later).** The Briefer produces the brief, dispatches the execution worker itself, reviews the return, and reports back to the dispatcher. Cleaner main-thread hygiene; more autonomy delegated to the Briefer.
+
+Activation of Model B is an operator-facing decision, not a Briefer-internal one. The Briefer defaults to Model A and does not spontaneously self-promote to Model B, even in cases where doing so would visibly save the dispatcher a step.
+
+
+## Activation
+
+The Dispatch Briefer is activated by the operator's PA whenever a non-trivial dispatch is being prepared. It requires:
+
+- The dispatcher's short intent (goal, target role, references, direction).
+- Access to the operator's knowledge system via `pa knowledge` (for reference-doc extraction).
+- Access to the target role's definition (for calibrating brief-section specificity).
+
+No external dependencies. The Briefer runs cleanly in any operator instance that has the target roles defined and the knowledge system populated.