@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-core/index.mjs

@@ -0,0 +1,21 @@
+// @stravica-ai/engineering-pa-core — type-agnostic platform spine.
+//
+// Public surface re-exports the modules other packages and operator code
+// import from. Internal-only modules stay accessible via their direct
+// `@stravica-ai/engineering-pa-core/src/...` paths (used in tests).
+
+export const name = './';
+export const version = '0.1.1';
+
+// Repo-root discovery — shared by every CLI / library that needs to locate
+// the operator repo at runtime.
+export { findRepoRoot, getRepoRoot, _resetRepoRoot } from './src/desk/repo.mjs';
+
+// Per-resource process lock — consumed default-on by `pa launch`; public
+// so direct-run tools (which bypass launch) can adopt the same protection.
+// Docs: docs/lock.md.
+export { acquireLock, DEFAULT_STALE_AFTER_MS } from './src/lock/lock.mjs';
+
+// Distill prereqs / prompt — also useful as a library entry point.
+export { resolvePrereqs, defaultRepoRoot as distillDefaultRepoRoot, BUNDLED_LIBRARIAN_DEF } from './src/distill/prereqs.mjs';
+export { buildDistillPrompt, DISTILL_PROMPT, claudeArgs } from './src/distill/prompt.mjs';

package/dist/engineering-pa-core/knowledge/README.md

@@ -0,0 +1,53 @@
+# Knowledge subtree — `packages/core/knowledge/`
+
+The knowledge layer sits inside `@stravica-ai/engineering-pa-core` and is the in-package home for the team-library shape adopted in [knowledge-system.md](https://github.com/Stravica/dave/blob/main/operator/knowledge/engineering/standards/knowledge-system.md).
+
+## Layer separation
+
+Three owner-distinct layers (Karpathy LLM Wiki):
+
+- **`raw/`** — intake. PA-writable subfolders (`raw/{paName}/...`). Append-only observations, confirmations, retractions. The PA owns this surface; nothing else writes here.
+- **`canonical/`** — wiki. Librarian-only write. Curated, deduplicated, conflict-annotated. This is what other agents retrieve from.
+- **`schema/`** — librarian configuration. Per-team customisation of distillation rules, domain taxonomy, retrieval weights, half-lives, importance tiers.
+
+The librarian is the sole writer to `canonical/`. PAs never bypass distillation.
+
+## Status
+
+**Skeleton — v0.1.0.** Directories exist as placeholders. v0.1.0 does NOT ship:
+
+- a deployed librarian service (lands in Phase 3)
+- a real `schema/librarian-config.json` (lands in Phase 3)
+- seed canonical content (lands in Phase 3)
+- per-PA `raw/{paName}/` subfolders (created per-onboarding by the scaffolder)
+
+This README and the empty subtrees exist so that Phase 1 Task 4 (minimal-core port) has slots to drop ported content into, and so that the methodology document is reflected on disk from day one.
+
+## Conflict handling, observation routing, retrieval, memory typing, recency, schema
+
+These are all governed by [knowledge-system.md](https://github.com/Stravica/dave/blob/main/operator/knowledge/engineering/standards/knowledge-system.md). That document is the authoritative reference for every implementation choice in this subtree. The eight deferred operator decisions noted at the bottom of that document remain open.
+
+## Layout
+
+```
+packages/core/knowledge/
+  README.md              # this file
+  schema/                # librarian configuration (empty in v0.1.0)
+  raw/                   # intake — append-only observations (empty in v0.1.0)
+  canonical/             # wiki — librarian-only writes (empty in v0.1.0)
+
+  # 7-bucket knowledge scaffolds (Wave B-3 A-series, 0.2.0):
+  operator-interface/    # Bucket 1 — session boot/end, communication, escalation
+  work-management/       # Bucket 2 — work items, projects, progress.md, spawn-log
+  delegation-dispatch/   # Bucket 3 — 8-section brief, dispatch envelope, modes
+  knowledge-memory/      # Bucket 4 — retrieval, staging, journal, Librarian
+  engineering-discipline/ # Bucket 5 — role ladder, git safety, worktree isolation
+  content-voice/         # Bucket 6 — banned-tells taxonomy, capture procedure
+  platform-tooling/      # Bucket 7 — pa, desk, environment, workspace, MCP
+```
+
+## Bucket knowledge scaffolds (Wave B-3 A-series, `0.2.0`)
+
+The seven bucket directories under this tree are **structural scaffolds** every operator copies into `operator/knowledge/<bucket-slug>/` and populates. Each ships a `README.md` (scope statement + pointer to the CLAUDE.md bucket that references it) + canonical subdocs (`.md` files with HTML-comment headers explaining what belongs, plus `<!-- OPERATOR: populate -->` markers for operator content).
+
+The scaffolds are the shape every operator inherits by copying; the shape is what makes cross-operator PA operating models mutually intelligible. Full detail: `packages/core/docs/pa-operating-model.md` § "The 7-bucket taxonomy".

package/dist/engineering-pa-core/knowledge/content-voice/README.md

@@ -0,0 +1,64 @@
+# content-voice — bucket knowledge scaffold (core baseline + operator overlay)
+
+**Bucket:** 6 of 7. Referenced from CLAUDE.md.template Bucket 6.
+
+## What this bucket carries
+
+Content that lands in the operator's voice, not generic AI-speak. Routing content through the right pipeline. Voice guides, banned AI-tells, capture procedure for new tells.
+
+**Bucket 6 is UNIQUE among the seven — it splits between core baseline and operator overlay.** Core ships the taxonomy, the generic-across-operators bans, and the capture mechanism. Operators overlay their specific voice + specific tells on top.
+
+## Scope — core baseline vs operator overlay
+
+**Core baseline (this directory).**
+
+- The **13-category taxonomy** of AI-tell categories. Every operator's banned-tells doc uses the same category shape.
+- **Generic AI patterns every operator should ban** — em-dash filler, "In today's landscape", "delve into", "leverage", "let's unpack", "the truth is", forced-contrast "it's not X, it's Y" without a legitimate contrast, adjective-piling, rhetorical-question section headings, setup-colons, sentence-final "and that changes everything".
+- **New-tell capture procedure** — the mechanism operators follow to add new tells via Librarian synthesis.
+- **Content-pipeline routing** — route content through the right role (`writer` for prose, surface-specialised writers for constrained targets).
+- **Voice-guide shape pointer** — cross-reference to the voice-guide.md template skeleton.
+- **Banned-ai-tells shape pointer** — cross-reference to the banned-ai-tells.md template skeleton.
+
+**Operator overlay** (`operator/knowledge/writing/`, or the operator's chosen path).
+
+- The operator's specific voice content (`voice-guide.md`).
+- The operator's specific banned tells layered on the baseline. Category 13 (operator-specific) is fully populated; categories 1-12 are extended with operator-specific entries on top of the baseline generic list.
+- The specific writer pipeline (`writer` alone, or `writer` + surface specialisations like `linkedin-writer`).
+- Surface-specific engagement / mission docs (out of Bucket 6 scope proper — content-publishing lives in operator overlay of Bucket 7 or a separate operator domain).
+
+## Canonical entries in this scaffold
+
+| File | Purpose |
+|---|---|
+| `banned-ai-tells-baseline.md` | The 13-category taxonomy + generic-across-operators banned patterns + capture procedure. |
+| `banned-ai-tells-taxonomy.md` | The 13 category names + one-line descriptions each. Referenced by operator overlays. |
+| `new-tell-capture-procedure.md` | The mechanism operators follow to capture new tells via Librarian synthesis. |
+| `content-pipeline-routing.md` | Route content through the right pipeline; content-publishing extensions are operator-side. |
+| `voice-guide-shape.md` | Pointer at `@stravica-ai/digital-operator-pa/templates/voice-guide.md`; explains how operators populate. |
+| `banned-ai-tells-shape.md` | Pointer at `@stravica-ai/digital-operator-pa/templates/banned-ai-tells.md`; explains how operators overlay. |
+
+## How the split works in practice
+
+The operator's `banned-ai-tells.md` inherits the 13-category shape from `banned-ai-tells-taxonomy.md`. Categories 1-12 have generic-across-operators bans in the CORE baseline; the operator extends each with operator-specific entries. Category 13 (Operator-specific) is populated fully from the operator side.
+
+Overlay convention:
+
+- Category headings MATCH the baseline. Same names, same order.
+- Baseline entries stay in place; operator entries are added under existing categories.
+- Category 13 (Operator-specific) is fully populated from the operator side.
+
+**Shape enforcement** for 0.2.0 is documentation-contract only. A lint rule (`pa lint voice-shape`) may land in a later minor release once the pattern is validated in operator practice — for now, the operator maintains shape parity manually.
+
+## How operators adopt this
+
+Two choices:
+
+1. **Overlay approach (recommended).** Operator's `operator/knowledge/writing/banned-ai-tells.md` inherits the 13-category shape; add operator-specific entries under each existing category and populate category 13. The core `banned-ai-tells-baseline.md` remains the source of the generic bans (referenced, not copied).
+2. **Full-copy approach.** Operator copies the baseline into the operator repo and edits in place. Simpler but drifts from core over time; suitable for operators who don't intend to pull core updates.
+
+## Related
+
+- CLAUDE.md.template Bucket 6 — the rule list that references this deeper doc.
+- `packages/core/roles/writer/definition.md` — the base writer role.
+- `@stravica-ai/digital-operator-pa/templates/voice-guide.md` — voice-guide skeleton.
+- `@stravica-ai/digital-operator-pa/templates/banned-ai-tells.md` — banned-tells skeleton.

package/dist/engineering-pa-core/knowledge/content-voice/banned-ai-tells-baseline.md

@@ -0,0 +1,133 @@
+# Banned AI-tells — core baseline
+
+The generic-across-operators bans. Every operator inherits these; operator overlays extend with operator-specific entries under the same categories.
+
+Taxonomy reference: `banned-ai-tells-taxonomy.md`.
+
+---
+
+## Category 1 — Punctuation
+
+**Em-dash filler.** Em-dashes chained as an alternative to commas and clauses. One em-dash per paragraph is fine when it does work; three in a paragraph reads as AI cadence.
+
+**Semicolon-heavy compound sentences chained for cadence.** Semicolons should join two independent clauses that genuinely belong together; when they're used as an alternative to a full stop for rhythm, they read as AI.
+
+**Setup-colon before a payoff.** "The result: everything changed." — colon-as-drumroll reads as AI. Prefer a full stop; let the payoff stand on its own line.
+
+## Category 2 — Openers
+
+**"In today's landscape / world / era."** Universal AI opener. Banned outright.
+
+**"It's worth noting that..."** Setup phrase that adds nothing. Just note the thing.
+
+**Opener-questions to introduce a section.** "What makes a good API?" — followed by an answer. This is not an opener; it's an AI convention. Just make the point.
+
+**"Let's unpack..." / "Let's dive in..."** Journey-verb openers. Skip.
+
+## Category 3 — Filler
+
+**"Essentially" / "fundamentally" / "arguably" / "at its core".** Words that appear to qualify but add no information. Cut them.
+
+**"The truth is..."** — Nothing about the truth follows that's more true than what preceded it. Filler.
+
+**"In many ways" / "to some extent" / "in a sense".** Vague qualifiers that read as AI hedging.
+
+## Category 4 — Forced contrasts
+
+**"It's not X, it's Y" without a legitimate contrast.** When X is a straw target the reader wasn't holding, the contrast is manufactured. AI does this to signal "here's an insight" — but if the insight is real, it doesn't need the contrast scaffold.
+
+**"Not just X but Y" without a payoff.** If Y isn't materially bigger or different than X, the "not just" is filler.
+
+**Rhetorical "This isn't about X, it's about Y".** Same failure mode.
+
+## Category 5 — Sentence-final tells
+
+**"...and that changes everything."** Universal AI sentence-final. Banned outright.
+
+**"...and that's the real story."** Same class.
+
+**Trailing ". Period." (or ". Full stop.") as emphasis.** Reads as AI.
+
+**"...for good reason."** Explanation-avoidance. Explain the reason or cut the phrase.
+
+## Category 6 — Vocabulary
+
+**"Delve" / "delve into".** Universal AI vocabulary. Banned outright.
+
+**"Leverage" (as a verb, outside finance).** Banned. Use "use."
+
+**"Unpack" (as a verb, outside luggage).** Journey-verb. Skip.
+
+**"Landscape" / "ecosystem" (as bare-noun metaphor).** See Category 8.
+
+**"Journey" (as metaphor for a process).** Banned outside actual travel narrative.
+
+**"Robust" / "seamless" / "cutting-edge".** Marketing vocabulary. Cut.
+
+## Category 7 — Corporate jargon
+
+**"Stakeholder" (outside actual corporate contexts).** In prose, "the people who care" is fine.
+
+**"Leverage synergies", "actionable insights", "value proposition", "circle back".** Business-writing in prose contexts reads as AI or as corporate ventriloquism.
+
+**"At scale" (as a bare qualifier).** If scale matters, describe the scale. Otherwise cut.
+
+## Category 8 — Bare-noun metaphors
+
+**"Landscape" without a landscape.** If you're not describing terrain, don't use "landscape."
+
+**"Ecosystem" without an ecosystem.** Same rule.
+
+**"Arena" / "space" / "realm" used as neutral place-holders.** Reads as AI.
+
+**Rule of thumb.** A metaphor noun needs a concrete referent in the same paragraph. If not, cut the metaphor.
+
+## Category 9 — Narrator tells
+
+**"This raises the question..."** Narrator-commentary that operators wouldn't write. Just raise the question.
+
+**"It's worth noting that..." / "It's important to note that..."** Meta-commentary. Cut.
+
+**"Consider this:"** AI narrator lead-in. If the following statement is worth considering, it stands on its own.
+
+**"What's fascinating is..."** Narrator-emotion projection. Show why it's fascinating, don't tell.
+
+## Category 10 — Hyphenated compounds
+
+**"Cutting-edge."** Marketing hyphenate. Banned.
+
+**"Next-generation" / "state-of-the-art" / "forward-thinking".** Marketing hyphenates. Banned.
+
+**"Ground-breaking" / "game-changing" / "world-class".** Same class.
+
+## Category 11 — Structural rhythms
+
+**Three-item lists constructed for rhythm, not content.** "It's about people, process, and product" — when only one or two of the items are load-bearing and the third is fill. Cut the fill.
+
+**Systematic sentence-length alternation.** AI writes in a distinctive rhythm — short. Then long, with more clauses. Then short. Real prose has natural variation; systematic alternation reads as AI.
+
+**Dependent-clause-then-main-clause reversal as a stylistic default.** "While it's easy to focus on X, the real issue is Y." One per section is fine; four in a section is AI.
+
+## Category 12 — Clever-isms
+
+**"It turns out..."** AI convention for "here's the surprise." If there's a surprise, describe it.
+
+**"Here's the thing..."** Conversational-lead-in that's become an AI convention.
+
+**"The real answer is..."** Same class as "The truth is..." from Category 3.
+
+**"Perhaps counterintuitively..."** If the point is counterintuitive, show why. Don't just claim it.
+
+## Category 13 — Operator-specific
+
+<!-- OPERATOR: populate this category with operator-specific tells that don't fit categories 1-12. Examples of the SHAPE (do not copy verbatim):
+- Ban on a specific word the operator finds AI-ish
+- Ban on a specific structural pattern the operator has flagged in past drafts
+- Register-specific bans (formal vs casual)
+-->
+
+---
+
+## New-tell capture procedure
+
+See `new-tell-capture-procedure.md`.

package/dist/engineering-pa-core/knowledge/content-voice/banned-ai-tells-shape.md

@@ -0,0 +1,58 @@
+<!--
+  scaffold: banned-ai-tells-shape.md
+  bucket: content-voice (Bucket 6)
+  what belongs here: pointer at the banned-ai-tells.md template + overlay convention.
+-->
+
+# Banned-AI-tells shape
+
+The core ships a template skeleton at `@stravica-ai/digital-operator-pa/templates/banned-ai-tells.md`. Operators overlay their specific tells on top of the CORE baseline entries at `banned-ai-tells-baseline.md`.
+
+## Overlay convention
+
+The operator's `operator/knowledge/writing/banned-ai-tells.md`:
+
+- **Uses the same 13-category shape** as `banned-ai-tells-taxonomy.md`. Category names and order must match.
+- **Inherits the core baseline entries** — the generic-across-operators bans in categories 1-12. The operator's doc REFERENCES the baseline (either by cross-link or by explicit "inherited from core baseline") rather than duplicating.
+- **Adds operator-specific entries** under existing categories 1-12 for operator-specific bans that fit the mechanism.
+- **Fully populates category 13** (Operator-specific) with operator-specific bans that don't fit categories 1-12.
+
+## Two overlay strategies
+
+**Strategy 1: reference the baseline** (recommended).
+
+Operator's `banned-ai-tells.md` under each category:
+
+```
+## Category 6 — Vocabulary
+
+**Core baseline (inherited).** See `@stravica-ai/engineering-pa-core/knowledge/content-voice/banned-ai-tells-baseline.md § Category 6`.
+
+**Operator-specific additions:**
+
+- **"cut" as a noun.** Barry doesn't use "cut" as a noun ("that was a strong cut"). Operator-specific ban.
+- ...
+```
+
+**Strategy 2: full copy** (simpler; drifts from core).
+
+Operator copies the baseline's entries verbatim and adds operator-specific entries in the same category. Simpler for reading — the operator sees the full list in one file — but the operator's file drifts from core if the baseline updates.
+
+## Shape enforcement (0.2.0)
+
+Documentation contract only. No lint. If the operator's overlay diverges from the 13-category shape, the writer role may fail to find the banned entries it expects. Operator maintains shape parity manually.
+
+Future lint (`pa lint voice-shape`) may land in a later minor release once the pattern is validated in practice.
+
+## How the writer role uses this
+
+Base `writer` reads the operator's `banned-ai-tells.md` on every dispatch. Reads it as a full doc; runs the drafted output through each category's entries as a gate before returning.
+
+The core baseline entries apply regardless of whether the operator's overlay references them explicitly or copies them — the writer role reads the OPERATOR's file, and the baseline is only enforced if it reaches the operator's file (via reference resolution or full copy).
+
+## Related
+
+- `@stravica-ai/digital-operator-pa/templates/banned-ai-tells.md` — the operator-facing skeleton.
+- `banned-ai-tells-baseline.md` — the core baseline entries.
+- `banned-ai-tells-taxonomy.md` — the 13 categories.
+- `new-tell-capture-procedure.md` — how new tells enter.

package/dist/engineering-pa-core/knowledge/content-voice/banned-ai-tells-taxonomy.md

@@ -0,0 +1,33 @@
+# Banned AI-tells — the 13 categories
+
+The taxonomy every operator's banned-tells doc inherits. Category names and order are load-bearing — operator overlays MUST match.
+
+| # | Category | One-line description |
+|---|---|---|
+| 1 | Punctuation | Rhythm markers that read as AI (em-dash filler, over-use of colons for setup, semicolon-heavy compound sentences chained for cadence). |
+| 2 | Openers | Sentence-first constructions that read as AI ("In today's landscape", "It's worth noting", opener-questions to introduce a section). |
+| 3 | Filler | Words that add nothing but AI cadence ("essentially", "fundamentally", "arguably", "at its core"). |
+| 4 | Forced contrasts | Constructions setting up an opposition where none exists ("it's not X, it's Y" with X being a straw target; "not just X but Y" without a contrast payoff). |
+| 5 | Sentence-final tells | Constructions at sentence end that read as AI ("and that changes everything", "and that's the real story", trailing ". Period."). |
+| 6 | Vocabulary | Individual words that carry AI signal ("delve", "leverage", "unpack", "landscape", "ecosystem", "journey"). |
+| 7 | Corporate jargon | Business-writing borrowed for prose contexts ("stakeholder", "leverage synergies", "actionable insights"). |
+| 8 | Bare-noun metaphors | Metaphor nouns used without a concrete referent ("landscape", "ecosystem", "arena" — where no actual landscape/ecosystem/arena is described). |
+| 9 | Narrator tells | Meta-commentary the operator wouldn't write ("This raises the question", "It's worth noting that", "Consider this"). |
+| 10 | Hyphenated compounds | Compound coinages an operator wouldn't reach for ("cutting-edge", "next-generation", "forward-thinking"). |
+| 11 | Structural rhythms | Sentence-shape patterns that read as AI (three-item lists constructed for rhythm not content, dependent-clause-then-main-clause reversal cadence, systematic sentence-length alternation). |
+| 12 | Clever-isms | Phrases that try to sound clever ("It turns out", "Here's the thing", "The real answer is"). |
+| 13 | Operator-specific | Populated fully from the operator side. Operator-specific bans that don't fit categories 1-12. |
+
+## How this taxonomy is used
+
+**Core baseline** (`banned-ai-tells-baseline.md`) populates categories 1-12 with **generic-across-operators bans** — the entries every operator should ban regardless of voice.
+
+**Operator overlays** add operator-specific entries under each existing category. Same category names, same order; more entries.
+
+**Category 13** exists so operator-specific bans have a home when they don't fit the mechanism categories. Barry-voice specific bans (e.g. "cut" as a noun) land here, not in Vocabulary.
+
+## Related
+
+- `banned-ai-tells-baseline.md` — the core baseline entries.
+- `banned-ai-tells-shape.md` — the template skeleton pointer.
+- `@stravica-ai/digital-operator-pa/templates/banned-ai-tells.md` — the operator-facing skeleton.

package/dist/engineering-pa-core/knowledge/content-voice/content-pipeline-routing.md

@@ -0,0 +1,58 @@
+<!--
+  scaffold: content-pipeline-routing.md
+  bucket: content-voice (Bucket 6)
+  what belongs here: content-pipeline routing rules.
+    - Prose → writer role.
+    - Surface-specialised content → operator-side specialised writer roles.
+    - Content-publishing extensions (schedulers, LI tools) are operator overlays.
+    - Never hand-craft content in the main thread when dispatching produces higher quality.
+-->
+
+# Content pipeline routing
+
+## The rule
+
+Route content through the right pipeline. The PA does not draft in the main thread when a dispatch produces higher-quality voice-consistent output.
+
+## Base routing
+
+- **Prose (essays, articles, long-form).** → `writer` role.
+- **Surface-specialised content (LinkedIn posts, tweets, newsletters, ad copy).** → operator-side specialised writer role (`linkedin-writer`, `newsletter-writer`, etc.) that extends the base `writer`.
+- **Meta content about the operator's own operating model.** → the PA can draft inline (this is not audience-facing content; voice discipline is looser).
+
+## Base writer role
+
+`packages/core/roles/writer/definition.md`. Voice-doc-driven — reads voice-guide + banned-tells + operator profile from operator-configured paths on every dispatch. Deterministic: same inputs, same voice output.
+
+The base writer reads voice from config; the operator points the config at `operator/knowledge/writing/voice-guide.md` (or the operator's chosen path).
+
+## Operator-side specialisations
+
+Surface-specialised writers layer surface-specific rules on top of the base:
+
+- **`linkedin-writer`** — LI-specific structural rules (character targets, opener conventions, engagement patterns) layered on base writer voice.
+- **`newsletter-writer`** — newsletter-format rules layered.
+
+Specialisations MUST inherit the base writer's read-then-gate-then-deliver sequence and MUST NOT relax the banned-tells check.
+
+## Content-publishing tooling
+
+**Out of core.** Content publishing is a per-operator concern — the surfaces the operator ships to, the cadence, the scheduling, the metrics. All of these are operator-side.
+
+If the operator ships a content-publishing tool (e.g. a `content-pub` CLI), it lives under `operator/extensions/tools/`. Content state changes go through that tool; direct edits to schedule data are lint-refused.
+
+<!-- OPERATOR: name your content-publishing tool here (if any) and its verb surface. -->
+
+## Push back on voice-flat drafts before they ship
+
+Voice restarts caught mid-draft are cheap. Post-publication corrections are expensive. The PA reads the drafted output BEFORE shipping and pushes back on obvious voice failures — even after a well-briefed dispatch.
+
+## Include voice + banned-tells references in every writing brief
+
+Workers don't inherit voice by osmosis. The brief MUST name the voice-guide path and the banned-tells path in Tools-and-sources.
+
+## Related
+
+- CLAUDE.md.template Bucket 6 rules 1, 3.
+- `packages/core/roles/writer/definition.md` — the base writer role.
+- `voice-guide-shape.md` / `banned-ai-tells-shape.md` — the template skeleton pointers.

package/dist/engineering-pa-core/knowledge/content-voice/new-tell-capture-procedure.md

@@ -0,0 +1,40 @@
+# New-tell capture procedure
+
+How new AI-tells enter the operator's banned-tells doc.
+
+## The rule
+
+**New tells enter via the Librarian's synthesis sweep, not via manual append.**
+
+An operator observes a tell (in their own writing, in a worker's draft, in someone else's writing that highlights the pattern). The operator logs it as a staging observation. On the next distillation sweep, the Librarian processes it into the banned-tells doc.
+
+## Operator side — staging the observation
+
+1. Notice the tell. Get the specific example (the sentence, the phrase, the exact wording).
+2. Stage: `agents/<paName>/staging/<timestamp>_correction_<slug>.md` (if the tell was caught in a draft) or `<timestamp>_domain_voice-tell-<slug>.md` (if the tell was noticed elsewhere).
+3. In the observation: name the specific tell, quote the example, note which category it likely fits (from the 13-category taxonomy), state why it reads as AI.
+4. Continue with the work. The observation is captured; the Librarian handles the routing.
+
+## Librarian side — synthesis
+
+On the next distillation sweep:
+
+1. **Read the observation in full context.** The source draft, the operator's review comment, any prior related observations.
+2. **Decide category placement.** Does it fit an existing category (extend that category's entries)? Or does it warrant a new category placement (unusual — the taxonomy is stable, but occasionally a new pattern emerges)?
+3. **Restructure the category to accommodate.** Do NOT append at the end. Read the whole category, locate where the new tell fits (by mechanism, not by chronology), rewrite the category to include the new entry in its logical place.
+4. **Update rationale and examples.** Include the operator's specific example verbatim. Include the operator's stated reason if useful.
+5. **Flag major taxonomy changes.** If the addition materially changes the taxonomy's shape (a new category, a category rename), flag for operator review — the Librarian never silently reshapes the operator's tell catalogue.
+6. **Commit with the observation ID.** Provenance is traceable.
+
+## What NOT to do
+
+- **Do NOT treat banned-ai-tells.md as a linear log.** Every synthesis is a restructure — the doc reflects CURRENT understanding, not chronology of capture.
+- **Do NOT ask the PA to append.** The PA stages observations; the Librarian synthesises. Direct writes to banned-ai-tells.md bypass the discipline.
+- **Do NOT invent tells.** New entries come from real observations, not hypothetical extrapolation.
+
+## Related
+
+- `banned-ai-tells-baseline.md` — the current core baseline entries.
+- `banned-ai-tells-taxonomy.md` — the 13 categories.
+- `packages/core/roles/librarian/definition.md` — the Librarian role.
+- CLAUDE.md.template Bucket 4 rule 7 — the Librarian sweep pattern.

package/dist/engineering-pa-core/knowledge/content-voice/voice-guide-shape.md

@@ -0,0 +1,43 @@
+<!--
+  scaffold: voice-guide-shape.md
+  bucket: content-voice (Bucket 6)
+  what belongs here: pointer at the voice-guide.md template + how to populate.
+-->
+
+# Voice-guide shape
+
+The core ships a template skeleton at `@stravica-ai/digital-operator-pa/templates/voice-guide.md`. Operators copy this into their operator repo (typically `operator/knowledge/writing/voice-guide.md`) and populate.
+
+## What the template ships
+
+- **Positive-shape principles** — what the voice sounds like. Not what it doesn't.
+- **Register calibration** — where on the formal/casual spectrum the voice sits, and how it shifts by surface (long-form vs LinkedIn vs email).
+- **Voice-tell examples** — the operator's own writing showing the voice in action, annotated so a role can extract the pattern.
+- **Sections a voice doc has** — the template's own structure is the shape every operator's voice-guide follows.
+
+## How the writer role uses it
+
+Base `writer` reads voice-guide + banned-tells on every dispatch. The voice-guide is the positive-shape source; the banned-tells is the negative-shape complement.
+
+Deterministic outcome: same voice-guide + same banned-tells + same prompt → same voice output. If the writer produces inconsistent voice output on repeat runs, the voice-guide is under-specified (not the writer's fault).
+
+## Populating
+
+Follow the template's structure. Do not restructure the voice-guide skeleton — the shape is what makes voice documents mutually intelligible across operators.
+
+**Do:**
+
+- Populate positive-shape principles with the operator's own examples.
+- Populate register calibration with concrete markers (specific words that fit, specific words that don't).
+- Populate voice-tell examples with real drafts, annotated.
+
+**Do not:**
+
+- Delete template sections you don't yet know how to fill. Leave the `<!-- OPERATOR: populate -->` marker; the writer will refuse to draft against an unpopulated voice guide, which is the correct failure mode.
+- Add operator-specific structural sections outside the template's shape. If the voice needs a new section, propose an upstream template change first.
+
+## Related
+
+- `@stravica-ai/digital-operator-pa/templates/voice-guide.md` — the skeleton.
+- `banned-ai-tells-shape.md` — the negative-shape complement.
+- `packages/core/roles/writer/definition.md` — the role that consumes the voice-guide.

package/dist/engineering-pa-core/knowledge/delegation-dispatch/README.md

@@ -0,0 +1,34 @@
+# delegation-dispatch — bucket knowledge scaffold
+
+**Bucket:** 3 of 7. Referenced from CLAUDE.md.template Bucket 3.
+
+## What this bucket carries
+
+How the PA delegates work — the 8-section briefing contract, dispatch envelope (what actually works empirically), delegation modes, task-group patterns, team improvement loop, tool-development policy.
+
+## Scope — core vs operator overlay
+
+**In core.** Universal delegation mechanism: the 8-section brief, the depth/concurrency/isolation dispatch findings, delegation-mode selection (single subagent vs task group vs single-threaded), task-group pattern with depth-2 orchestration posture, the tool-development-through-tool-developer policy (Node-only), the process-and-result evaluation loop on every return.
+
+**In operator overlay** (`operator/knowledge/delegation-dispatch/`). Operator-specific dispatch patterns: surface-specific brief bolt-ons, operator-specialised role list (the specific role LIST beyond the base ladder), per-project orchestration conventions.
+
+## Canonical entries in this scaffold
+
+| File | Purpose |
+|---|---|
+| `briefing-contract.md` | The 8-section brief shape (Goal, Trace, Context, Tools and sources, Boundaries, Output format, Done when, Escalation rule) plus shared-MCP-session hazards, structured-return-schema requirement, checkpoint pattern for long-running dispatches. |
+| `dispatch-envelope.md` | What actually works — capability matrix, depth findings, MCP inheritance, isolation semantics, long-running health, brief-writing implications. Promoted from operator on 2026-07-05. |
+| `delegation-modes.md` | Single subagent vs task group vs single-threaded. Selection tree. Topic-differs pollution-prevention rule. |
+| `task-groups-and-orchestrators.md` | Task-group pattern; depth-2 constraint. Project Lead as orchestrator for multi-role projects. |
+| `team-improvement-loop.md` | Evaluate process AND result on every return. Feed role defs, briefs, envelopes, roster. |
+| `tool-development-policy.md` | All tool development via tool-developer, in Node.js. No shell scripts, ever. Cross-platform breakage rationale. |
+
+## How operators adopt this
+
+Copy the shape into `operator/knowledge/delegation-dispatch/`. Populate the operator's specific role LIST, dispatch bolt-ons, and per-project conventions in the marked hooks.
+
+## Related
+
+- CLAUDE.md.template Bucket 3 — the rule list that references this deeper doc.
+- `packages/core/docs/standards/briefing-contract.md` — the canonical briefing standard.
+- `packages/core/roles/dispatch-briefer/definition.md` — the Briefer role.

package/dist/engineering-pa-core/knowledge/delegation-dispatch/briefing-contract.md

@@ -0,0 +1,77 @@
+<!--
+  scaffold: briefing-contract.md
+  bucket: delegation-dispatch (Bucket 3)
+  what belongs here: the 8-section brief pattern + three Rev 4 additions.
+    - Shared-MCP-session hazard clause in Boundaries.
+    - Structured-return-schema requirement in Output format.
+    - Checkpoint-pattern requirement for long-running dispatches.
+  Canonical field-by-field standard: packages/core/docs/standards/briefing-contract.md.
+-->
+
+# Briefing contract
+
+Every dispatch uses an 8-section brief. Section headings are mechanical — copy them verbatim. Full field-by-field rationale in `@stravica-ai/engineering-pa-core/docs/standards/briefing-contract.md`.
+
+## The 8 sections
+
+| Section | What it carries |
+|---|---|
+| Goal | One sentence, outcome-shaped. What shipping looks like. |
+| Trace | How we got here. The reasoning that led to this task. Load-bearing. |
+| Context | Paths, files, prior decisions, operator preferences relevant to this task. Extracted, not full-file. |
+| Tools and sources | What tools to use. Which files to read. Which to avoid. |
+| Boundaries | What is in scope, what is out. Where decide-alone becomes escalate. Shared-parent-state hazards. |
+| Output format | Structured return-report shape. Return on completion or abort ONLY. |
+| Done when | Boolean-checkable ship gate. |
+| Escalation rule | When to stop and report partial. |
+
+## Trace is the field most often missed
+
+Without it, workers make locally consistent but globally incompatible choices. The trace is prose the worker reads to understand WHY this task exists — the reasoning, the prior decisions, the operator direction if any. Cognition's Flappy Bird failure mode captures why: workers briefed without trace re-derive context locally and produce output the integration step can't reconcile.
+
+## Load-bearing additions per Rev 4
+
+### 1. Shared-MCP-session hazard in Boundaries
+
+Worktree isolation covers git only. `/tmp`, `$HOME`, network, and MCP tool sessions (Playwright browser, OAuth-gated services like Gmail, Google Drive, Atlassian) all leak to workers AND are shared with the parent. Every brief whose worker will use one of these tools must:
+
+- Acknowledge the shared session in the Boundaries section.
+- Instruct the worker to serialise with any other agent using the same tool, OR use a headless-Node isolation approach, OR explicitly accept the collision risk.
+
+Full findings: see `dispatch-envelope.md` § MCP Tool Availability.
+
+### 2. Structured-return-schema requirement in Output format
+
+The parent only sees the worker's final message — no streaming, no intermediate tool events, no per-child transcript reads. The Output format section MUST specify the exact return shape the parent expects. Common shape:
+
+```
+### <what-shipped> — worker return
+
+**Status:** success | partial | escalation
+
+**Deliverables checklist (mark each ✓ or note gap):**
+- [ ] ...
+- [ ] ...
+
+**Files landed:** <count> files, <+lines/-lines>
+
+**Handoff notes:** ...
+
+**Escalations (if any):** ...
+```
+
+For task-group orchestrators, the Output format additionally requires per-worker enumeration (name / role / agentId / status / key artefacts) because the root only sees what the orchestrator reports.
+
+### 3. Checkpoint pattern for long-running dispatches
+
+For work expected to run more than ~5 minutes, brief the worker to `SendMessage("main", <one-line status>)` at natural checkpoints. Silence-vs-completion is the only default health signal — insufficient for genuinely long jobs.
+
+Checkpoint intervals: at natural task boundaries (finished section 1, moving to section 2), not on a fixed clock. A message every 60 seconds spams; a message every 15 minutes with a real state update is useful.
+
+The default posture is NO checkpoints — most dispatches run under 5 minutes and silence-vs-completion is fine. Add checkpoints deliberately when the shape of the work warrants.
+
+## Related
+
+- `packages/core/docs/standards/briefing-contract.md` — canonical field-by-field standard.
+- `dispatch-envelope.md` — capability matrix / depth findings / MCP inheritance / brief-writing implications.
+- `packages/core/roles/dispatch-briefer/definition.md` — the Briefer role that authors briefs.