@stravica-ai/digital-operator-pa 0.1.0

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@stravica-ai/digital-operator-pa",
+  "version": "0.1.0",
+  "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "bin": {
+    "pa": "bin/pa",
+    "desk": "bin/desk",
+    "launch": "bin/launch",
+    "estate-sync": "bin/estate-sync",
+    "sync": "bin/sync",
+    "secrets": "bin/secrets",
+    "scheduler": "bin/scheduler",
+    "smoke": "bin/smoke",
+    "distill": "bin/distill",
+    "memory-sync": "bin/memory-sync",
+    "migrate-inspect": "bin/migrate-inspect",
+    "pa-init": "bin/pa-init",
+    "slice": "bin/slice",
+    "research": "bin/research",
+    "pa-coordinator-hook": "bin/pa-coordinator-hook"
+  },
+  "files": [
+    "index.mjs",
+    "bin",
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Stravica/engineering-pa-dev.git",
+    "directory": "packages/engineering-pa"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "google-auth-library": "^9.15.0",
+    "googleapis": "^144.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "//": "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.",
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "node --test --test-isolation=none test/*.test.mjs",
+    "dry-publish": "node build.mjs && pnpm publish --dry-run --no-git-checks"
+  }
+}

package/templates/banned-ai-tells.md

@@ -0,0 +1,102 @@
+<!--
+  Template: banned-ai-tells.md
+  Owner: operator (adopt, populate, then remove this HTML comment)
+  Purpose: structural skeleton for an operator's banned-AI-tells doc.
+  Source: @stravica-ai/digital-operator-pa templates. See packages/engineering-pa/README.md.
+
+  This is the negative-shape complement to voice-guide.md. Voice-guide.md
+  says what the voice sounds like; this doc catalogues the shapes that
+  make text read as AI. Both docs are consumed together — a writer
+  drafts against the voice guide, then screens the draft against this
+  catalogue before shipping.
+-->
+
+# Banned AI-tells
+
+**Status:** draft | in-review | live
+**Last reviewed:** YYYY-MM-DD
+**Owner:** operator name
+
+## Purpose
+
+<!-- OPERATOR: replace with a one-paragraph purpose statement. Template
+default:
+
+This is a reference catalogue of shapes that make text read as AI-written
+rather than operator-written. Categorised by the mechanism of the tell,
+each entry carries a definition, illustrative examples, the reason the
+shape reads as AI, and any context in which the shape is acceptable. A
+writer consults this doc as the LAST screen before shipping — after the
+voice guide's positive shape has done its work. -->
+
+## Category: <name>
+
+<!-- OPERATOR: duplicate this section for each category. Suggested
+starting categories (kept flexible — cull, split, or extend to match
+your observed corpus):
+
+- Journey-verbs (venture, embark, navigate)
+- Effusive openers ("Great question", "That's a fascinating point")
+- Forced contrasts ("not X, but Y" without a legitimate contrast)
+- Bare-noun metaphors ("landscape", "ecosystem" without concrete referent)
+- Meta-commentary ("this raises the question", "it's worth noting that")
+- Ceremonial closes ("Ultimately", "In closing", ".")
+- Faux-precision qualifiers ("in many ways", "to some extent")
+- Overworked triads (three-item lists constructed for rhythm, not content)
+
+For each category, populate the four fields below. Empty examples are
+better than invented ones — the corpus grows as tells are observed, not
+invented up front. -->
+
+### Definition
+
+<!-- OPERATOR: one paragraph. What is the tell? What structural shape
+does the reader detect? -->
+
+### Examples
+
+<!-- OPERATOR: three to six real examples that a writer will recognise.
+Prefer examples caught in operator drafts over hypothetical constructs —
+recognition trumps taxonomy. Cite the source (staging observation ID or
+commit) so provenance is traceable. -->
+
+### Why it reads as AI
+
+<!-- OPERATOR: one paragraph. What signal does this shape carry? What
+does its presence tell a reader about how the text was produced? Keep
+the analysis honest — the point is not to shame LLMs but to describe
+the pattern's effect on the reader's trust. -->
+
+### Context caveat
+
+<!-- OPERATOR: some tells are context-scoped. A journey-verb in a
+first-person narrative may be fine; the same verb in an analytical
+essay is not. Note the contexts in which the tell is acceptable, if any.
+If none, say "no exceptions" and move on. Avoid inventing exceptions to
+soften the ban — the ban is the ban. -->
+
+## New-tell capture procedure
+
+<!-- OPERATOR: keep the template default unless the operator's ingestion
+process differs. Template default:
+
+**New tells enter this doc via the librarian's synthesis sweep, not via
+manual append.** An operator observes a tell (in their own writing or
+someone else's), logs it as a staging observation with category
+`voice-tell`, and moves on. On the next distillation sweep, the librarian:
+
+1. Reads the observation in full context (the source draft, the operator's
+   review comment).
+2. Decides whether it fits an existing category (extend that section's
+   examples + rationale) or warrants a new category (add a section,
+   restructure the surrounding categories if the new one changes the
+   taxonomy's shape).
+3. If restructuring materially changes the taxonomy, flags for operator
+   review — the librarian never silently reshapes the operator's tell
+   catalogue.
+4. Commits with the observation ID in the message so provenance is
+   traceable.
+
+**Do not** treat this doc as a linear log. Every synthesis is a
+restructure — the doc's shape reflects the CURRENT understanding of the
+tell landscape, not the history of its capture. -->

package/templates/purpose.md

@@ -0,0 +1,105 @@
+<!--
+  Template: purpose.md
+  Owner: operator (adopt, populate, then remove this HTML comment)
+  Purpose: structural skeleton for a content-publishing purpose / mission doc.
+  Source: @stravica-ai/digital-operator-pa templates. See packages/engineering-pa/README.md.
+
+  This doc is the top of the mission stack. Every subordinate rule
+  (voice guide, banned tells, engagement guides) serves one of the
+  anchor goals below, or gets cut. When a subordinate rule surfaces a
+  hard case, the reader falls back to this doc for the tie-break.
+-->
+
+# Content-publishing purpose
+
+**Status:** draft | in-review | live
+**Last reviewed:** YYYY-MM-DD
+**Owner:** operator name
+
+## Mission
+
+<!-- OPERATOR: replace with a one-line mission summary. Not a slogan —
+the operator's honest statement of what content publishing is for.
+Example shape: "Make it easy for people who care about <domain> to find
+the operator's work, judge it, and act on it." -->
+
+## Anchor goals
+
+<!-- OPERATOR: replace with a numbered list of anchor goals. Every
+subordinate rule serves one of these or gets cut. Four to seven anchors
+is a healthy range — fewer and the mission is too abstract to
+tie-break, more and the anchors overlap. Each anchor is one clause + one
+sentence of what it means in practice.
+
+1. <Anchor name>. <One-sentence expansion — what does this look like when
+   it's working?>
+2. <Anchor name>. <One-sentence expansion.>
+3. <Anchor name>. <One-sentence expansion.>
+4. <Anchor name>. <One-sentence expansion.>
+-->
+
+## What "success" looks like at scale
+
+<!-- OPERATOR: replace with the north-star — what does the mission look
+like when it's fully working? Not a metric. A picture. The kind of thing
+that lets you tell whether a shipped piece of content moved the operator
+towards the north star or sideways.
+
+Example (Barry's operating instance): "Influencers writing their own
+posts about the operator's work, without the operator prompting them.
+The operator has become a reference point in the domain, not a self-
+promoting voice."
+
+Populate with the operator's own north star. -->
+
+## Downstream consequences
+
+<!-- OPERATOR: replace with the operational implications of the mission.
+These are the "if the mission is X, then Y" statements that shape
+day-to-day decisions.
+
+Examples:
+- Cold audience → the post links out to the newsletter, not to a specific
+  concept page. First contact needs a low-commitment ramp.
+- Warm audience → the post links to a specific concept page. Someone who
+  already knows the operator's terminology can go deep.
+- Guest posts on other properties → link back to the operator's own
+  property, never to a paywall.
+
+Populate with the consequences your mission actually implies. Cut any
+that feel invented rather than derived. -->
+
+## Scope fence
+
+<!-- OPERATOR: replace with what this mission does NOT cover. Explicit
+non-goals shorten future debates.
+
+Examples:
+- This mission does NOT cover paid ads. If the operator runs ads, they
+  serve a different mission with different rules.
+- This mission does NOT cover internal comms (Slack, email newsletters
+  to existing customers). Those are relationship maintenance, not
+  audience acquisition.
+- This mission does NOT cover conference talks. Talks are a different
+  surface with different economics.
+
+Populate with the operator's actual non-goals. Better to over-fence at
+the start than under-fence. -->
+
+## Review + refresh cadence
+
+<!-- OPERATOR: replace with the operator's review discipline. Template
+default:
+
+**Quarterly review**, or immediately after any of:
+
+- A shift in the operator's business model (new product line, new
+  audience, spun-off property).
+- A shift in the platform landscape that materially changes the
+  audience economics (an algorithm change that reshapes engagement,
+  a new platform gaining traction, an old platform losing traction).
+- A material miss on one of the anchor goals — if the mission says X
+  and the shipped content is not producing X, the mission or the
+  execution is wrong. Diagnose which before shipping the next batch.
+
+Change this section only if the operator's review discipline differs. -->

package/templates/voice-guide.md

@@ -0,0 +1,98 @@
+<!--
+  Template: voice-guide.md
+  Owner: operator (adopt, populate, then remove this HTML comment)
+  Purpose: structural skeleton for an operator's voice-guide doc.
+  Source: @stravica-ai/digital-operator-pa templates. See packages/engineering-pa/README.md.
+
+  This template ships the SHAPE. Every `<!-- OPERATOR: … -->` marker is a
+  spot where you replace the guidance with your own content. Do not
+  invent extra sections without a reason — the shape is what makes voice
+  guides mutually intelligible across operators.
+-->
+
+# Voice guide
+
+**Status:** draft | in-review | live
+**Last reviewed:** YYYY-MM-DD
+**Owner:** operator name
+
+## Who this voice belongs to
+
+<!-- OPERATOR: replace with a one-line operator identity — the person or
+brand whose voice this doc describes. Not the writer role's identity;
+the human whose voice the writer reproduces. -->
+
+## Voice principles
+
+<!-- OPERATOR: replace with 4-8 positive-shape principles. Each principle
+describes what the voice SOUNDS LIKE, not what it avoids. Bans belong in
+banned-ai-tells.md. Examples of positive shape: "concrete before
+abstract", "load-bearing verbs, plain nouns", "one clause of praise, then
+the substance". Each principle carries an example that a writer can hold
+in their head while drafting. -->
+
+## Voice tests
+
+<!-- OPERATOR: replace with a short checklist an author runs against a
+draft before shipping. This is the runtime discipline — principles are
+the aim, tests are the enforcement. Keep the list to items an author can
+actually check in ~2 minutes. Examples: "read the opening aloud — does
+it sound like something you would say?", "count the em-dashes — >3 per
+paragraph means restructure", "any banned tell present? consult
+banned-ai-tells.md". -->
+
+## Structural rules
+
+<!-- OPERATOR: replace with structural conventions specific to your voice.
+Character counts, paragraph shape, section shape. Keep these soft — hard
+bans are in banned-ai-tells.md. Examples: "LinkedIn posts land at 900-1200
+chars", "articles open with a specific concrete situation, not a
+generalised framing", "no headings above H2 inside articles". Anything
+that's testable by a linter goes in the lint corpus, not here — this doc
+is for the human. -->
+
+## Register calibration
+
+<!-- OPERATOR: replace with the judgment factors that shape register
+across contexts. Peer vs cold, warm vs formal, replying vs originating.
+Not prescriptive patterns — the factors a writer weighs and the
+directions those factors push. Example: "replying to a peer you've
+spoken to before: assume mutual context, drop the setup; replying to a
+cold post from someone outside your industry: one line of context first".
+This section teaches judgment, not rules. -->
+
+## Reference material
+
+<!-- OPERATOR: replace with links to the two companion docs and any
+in-scope evidence. The voice guide is the METHOD; the reference docs are
+the material.
+
+- `banned-ai-tells.md` — hard bans and the taxonomy of AI-tells to
+  avoid. This is the negative-shape complement to this doc's principles.
+- `purpose.md` — the content-publishing mission. Every voice decision
+  ultimately serves the mission; that's the doc a writer reads when a
+  register decision doesn't have an obvious answer.
+
+Add operator-specific evidence links if useful — past shipped posts, a
+tell-evolution log, competitive references. -->
+
+## How to update this doc
+
+<!-- OPERATOR: replace with the operator's own synthesis discipline. The
+default methodology, unchanged from the template, is:
+
+**Synthesis, not append.** A new finding does NOT get bulleted at the
+bottom of a section. Read the whole affected section, understand where
+the finding fits into its argument, restructure the section so the new
+finding is baked in rather than tacked on. If restructuring materially
+changes the section's argument shape, flag for operator review — do not
+silently rewrite the operator's voice.
+
+**Sourcing.** Every restructure should reference the observation(s) that
+prompted it in the commit message, so `git log -p voice-guide.md` remains
+readable as a document evolution.
+
+**Cadence.** This doc is reviewed on every distillation sweep. The
+librarian is the maintainer; the operator is the final arbiter of voice.
+
+Change this section only if the operator's synthesis process differs. -->