@stravica-ai/digital-operator-pa 0.1.54 → 0.1.55

package/dist/engineering-pa-cli/src/coordinator-hook/config.mjs

@@ -20,7 +20,7 @@
 import { readFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { homedir } from 'node:os';
+import { resolveHome } from '../../../engineering-pa-core/src/home/resolve.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CORE_CONFIG_PATH = resolve(__dirname, '..', '..', 'config', 'coordinator-allowlist.json');
@@ -98,7 +98,7 @@ export function mergeOverlay(config, overlay, warnings = []) {
  * lives at `.claude/coordinator-overlay.json` under that directory.
  */
 export function overlayPaths({ repoRoot, cwd, env = process.env }) {
-  const home = env.HOME || homedir();
+  const home = resolveHome({ env });
   const workspaceBase = repoRoot || cwd;
   return {
     home: home ? join(home, '.claude', 'coordinator-overlay.json') : null,

package/dist/engineering-pa-cli/src/environment/probes.mjs

@@ -6,7 +6,7 @@
 import { execFile } from 'node:child_process';
 import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs';
 import { promisify } from 'node:util';
-import { arch, platform, release, homedir } from 'node:os';
+import { arch, platform, release } from 'node:os';
 import { basename, join, resolve, dirname } from 'node:path';
 import { resolve4 } from 'node:dns/promises';
 import { fileURLToPath } from 'node:url';

package/dist/engineering-pa-cli/src/pa/cli.mjs

@@ -67,6 +67,34 @@ export async function main(argv) {
     return 0;
   }
 
+  // 0.1.55 item 4 (w-2026-09-21-dave-004): `pa --version` / `pa -v`
+  // prints the installed package version. Before this landing there
+  // was no way to ask an installed CLI which version it was, so the
+  // 0.1.54 sweep had to `cat node_modules/.../package.json` by hand.
+  if (argv[0] === '--version' || argv[0] === '-v') {
+    const { readFile } = await import('node:fs/promises');
+    const { fileURLToPath } = await import('node:url');
+    const { dirname: dn, join: jn } = await import('node:path');
+    try {
+      // packages/cli/src/pa/cli.mjs -> ../../..(three-up)/package.json
+      // works in-repo. The installed tarball layout resolves the
+      // package.json via the exports map added in this same release.
+      let pkgJson;
+      try {
+        pkgJson = await import('@stravica-ai/digital-operator-pa/package.json', { with: { type: 'json' } });
+      } catch {
+        const here = dn(fileURLToPath(import.meta.url));
+        const local = jn(here, '..', '..', '..', 'engineering-pa', 'package.json');
+        pkgJson = { default: JSON.parse(await readFile(local, 'utf8')) };
+      }
+      process.stdout.write((pkgJson.default?.version || 'unknown') + '\n');
+      return 0;
+    } catch (e) {
+      process.stderr.write(`[pa] failed to resolve version: ${e?.message || e}\n`);
+      return 1;
+    }
+  }
+
   const verb = argv[0];
   const rest = argv.slice(1);
 

package/dist/engineering-pa-cli/src/pa/projects.mjs

@@ -17,6 +17,7 @@ import { writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { getRepoRoot } from './repo-root.mjs';
+import { findRepoRootSync } from '../../../engineering-pa-core/src/instance-root/find.mjs';
 import { readJson, writeJson, ensureDir, listSubdirs, today } from './io.mjs';
 import { addDoc, removeDocByPath, setDocStatus, DEFAULT_GROUP, VALID_DOC_STATUSES } from './doc-groups.mjs';
 import { normaliseDocPath } from './doc-path.mjs';
@@ -111,6 +112,12 @@ export async function createProject(opts) {
   validateCategory(opts.category);
   validatePriority(opts.priority);
 
+  // 0.1.55 F1: refuse a project create from outside any operator instance
+  // with the strict findRepoRootSync error (exit 2, message naming the
+  // start directory and the markers walked). Keeps the failure shape
+  // aligned with pa work create and the scaffold write paths.
+  findRepoRootSync({ strict: true });
+
   const repoRoot = await getRepoRoot();
   const projDir = join(repoRoot, 'projects', opts.id);
   const projectJsonPath = join(projDir, 'project.json');

package/dist/engineering-pa-cli/src/pa/work-cli.mjs

@@ -126,8 +126,34 @@ async function readPreferencesPaName() {
   }
 }
 
+// 0.1.55 item 4 (w-2026-09-21-dave-004): refuse unknown flags loudly.
+// The pre-0.1.55 parser silently dropped anything not consumed downstream,
+// so a typo like `--status` (only valid on `work status`) or an assumed
+// `--description` (there is no such flag; the field is `summary`) went
+// unnoticed and the created record was missing the value the operator
+// meant to set. Recorded as an incident in w-2026-09-21-dave-002's
+// summary.
+const CREATE_ALLOWED_FLAGS = new Set([
+  'project',
+  'title',
+  'category',
+  'priority',
+  'summary',
+  'owner',
+  'assignee',
+  'author',
+]);
+
 async function doCreate(args) {
   const { flags } = parseFlags(args);
+  const unknown = Object.keys(flags).filter((k) => !CREATE_ALLOWED_FLAGS.has(k));
+  if (unknown.length > 0) {
+    const list = unknown.map((k) => `--${k}`).join(', ');
+    const known = Array.from(CREATE_ALLOWED_FLAGS).map((k) => `--${k}`).sort().join(', ');
+    process.stderr.write(`[pa work create] unknown flag(s): ${list}\n`);
+    process.stderr.write(`  accepted flags: ${known}\n`);
+    return 1;
+  }
   const priority = flags.priority != null && flags.priority !== true
     ? Number(flags.priority)
     : null;

package/dist/engineering-pa-cli/src/pa/work.mjs

@@ -25,6 +25,7 @@ import {
   maxNForAuthorOnDate,
 } from '../../../engineering-pa-core/src/workItemId/index.mjs';
 
+import { findRepoRootSync } from '../../../engineering-pa-core/src/instance-root/find.mjs';
 import { getRepoRoot } from './repo-root.mjs';
 import {
   readJson,
@@ -128,6 +129,14 @@ export async function createWork(opts) {
   validateCategory(opts.category);
   validatePriority(opts.priority);
 
+  // 0.1.55 F1: refuse a mint from outside any operator instance BEFORE the
+  // author-token check. Pre-fix the flow bailed with the author-token error
+  // (exit 1), which read as a config problem in the caller's terminal; the
+  // real cause is that the cwd carries none of the instance markers. Strict
+  // findRepoRootSync throws with exit 2 and names both the start directory
+  // and the markers walked, matching the sibling rule in projects.mjs.
+  findRepoRootSync({ strict: true });
+
   let author;
   try {
     author = resolveAuthorToken({

package/dist/engineering-pa-core/docs/autonomy-envelope-tracker.md

@@ -12,34 +12,34 @@ The envelope is the durable record of what the operator has approved the PA to d
 
 | State | Meaning | PA behaviour |
 |---|---|---|
-| `fullyApproved` | Operator has said "just do this class of task; don't ask." | Act. Don't ask. If the reflex is to check, resist — the envelope is telling you not to. |
+| `fullyApproved` | Operator has said "just do this class of task; don't ask." | Act. Don't ask. If the reflex is to check, resist; the envelope is telling you not to. |
 | `checkBeforeCommitting` | Operator wants sign-off on the durable action but not on the drafting. | Draft, get sign-off before commit / push / publish / ship. Read-only exploration is fine without asking. |
 | `needsFullSupervision` | Operator hasn't approved this class yet, or has explicitly demoted it. | Do not act. Escalate every step. |
 
-The envelope's authority is above the PA's own inclination. If the envelope says a category is `needsFullSupervision` but the PA thinks the operator would be fine with autonomous action, the PA does NOT act — the operator can promote the category via `pa autonomy set` when they're ready.
+The envelope's authority is above the PA's own inclination. If the envelope says a category is `needsFullSupervision` but the PA thinks the operator would be fine with autonomous action, the PA does NOT act; the operator can promote the category via `pa autonomy set` when they're ready.
 
 ## Task-type taxonomy
 
-**Core does not enforce a specific task-type taxonomy** — every operator's surface types are different. An example taxonomy the operator might seed with:
+**Core does not enforce a specific task-type taxonomy**; every operator's surface types are different. An example taxonomy the operator might seed with:
 
-- `li-comment-draft` — drafting a LinkedIn comment reply.
-- `li-post-draft` — drafting a full LinkedIn post.
-- `article-draft` — drafting a long-form article.
-- `code-dispatch` — dispatching a code implementer.
-- `code-inline` — writing code in the main thread.
-- `git-commit-push` — committing and pushing.
-- `secret-access` — reading operator secrets from the vault.
-- `contact-outreach` — reaching out to a contact on the operator's behalf.
+- `li-comment-draft`; drafting a LinkedIn comment reply.
+- `li-post-draft`; drafting a full LinkedIn post.
+- `article-draft`; drafting a long-form article.
+- `code-dispatch`; dispatching a code implementer.
+- `code-inline`; writing code in the main thread.
+- `git-commit-push`; committing and pushing.
+- `secret-access`; reading operator secrets from the vault.
+- `contact-outreach`; reaching out to a contact on the operator's behalf.
 
 The operator seeds their own taxonomy per their surface types. The schema (`packages/core/schema/autonomy-envelope.schema.json`) enforces field shape but not the specific set of `taskTypes.id` values.
 
 ## CLI
 
-`pa autonomy` — four subcommands.
+`pa autonomy`; four subcommands.
 
 | Subcommand | Purpose |
 |---|---|
-| `pa autonomy init <agent>` | Create an empty envelope for a new agent. Idempotent — errors if envelope already exists. |
+| `pa autonomy init <agent>` | Create an empty envelope for a new agent. Idempotent; errors if envelope already exists. |
 | `pa autonomy get <agent> [<task-type>]` | Print current state. Task-type optional (prints full table if omitted). |
 | `pa autonomy set <agent> <task-type> <state> [--note <text>]` | Update state. Adds timestamped history entry to the body. Validates state against the enum. |
 | `pa autonomy list [<agent>]` | List envelopes across all agents (or one), with staleness signals (envelope untouched for >30 days → warning). |
@@ -60,7 +60,7 @@ The `pa autonomy get <agent> --format json` output is stable JSON that a boot-co
 
 ## Difference from the three-zone role envelope standard
 
-**Related but separate.** The three-zone ROLE envelope is a standard for how ROLES calibrate autonomy across their whole surface — informational, decision-support, decision-authority. That's a property of the role definition.
+**Related but separate.** The three-zone ROLE envelope is a standard for how ROLES calibrate autonomy across their whole surface; informational, decision-support, decision-authority. That's a property of the role definition.
 
 This tracker is a PER-AGENT, PER-TASK-TYPE record that the operator sets and demotes/promotes dynamically. Different granularity, different lifecycle. Both patterns coexist.
 
@@ -85,27 +85,27 @@ taskTypes:
     stateSince: 2026-07-05T14:30:00Z
 ---
 
-# Autonomy envelope — dave
+# Autonomy envelope; dave
 
 ## Current state
 
 | Task type | State | Since | Note |
 |---|---|---|---|
 | LinkedIn comment draft | checkBeforeCommitting | 2026-07-04 | Voice restarts are cheap mid-draft. |
-| Code implementation dispatch | fullyApproved | 2026-07-05 | — |
+| Code implementation dispatch | fullyApproved | 2026-07-05 |; |
 
 ## History
 
-### 2026-07-05T14:30:00Z — code-dispatch promoted to fullyApproved
+### 2026-07-05T14:30:00Z; code-dispatch promoted to fullyApproved
 Operator note: none.
 
-### 2026-07-04T09:00:00Z — li-comment-draft demoted to checkBeforeCommitting
+### 2026-07-04T09:00:00Z; li-comment-draft demoted to checkBeforeCommitting
 Operator note: Voice restarts are cheap mid-draft; post-publication corrections are expensive.
 ```
 
 ## Related
 
-- `packages/core/schema/autonomy-envelope.schema.json` — canonical schema.
-- CLAUDE.md.template framing block — the operator-facing pointer.
-- `packages/core/knowledge/operator-interface/escalation-and-correction.md` — how the envelope interacts with escalation.
-- `packages/cli/src/autonomy/` — CLI implementation.
+- `packages/core/schema/autonomy-envelope.schema.json`; canonical schema.
+- CLAUDE.md.template framing block; the operator-facing pointer.
+- `packages/core/knowledge/operator-interface/escalation-and-correction.md`; how the envelope interacts with escalation.
+- `packages/cli/src/autonomy/`; CLI implementation.

package/dist/engineering-pa-core/docs/blueprints/git-identity/blueprint.md

@@ -1,6 +1,6 @@
 # Git Identity
 
-Give your PA its own dedicated git identity with a separate SSH key and commit author. This creates a clear audit trail -- you can always tell which commits were made by you and which by your PA.
+Give your PA its own dedicated git identity with a separate SSH key and commit author. This creates a clear audit trail: you can always tell which commits were made by you and which by your PA.
 
 
 ## What it does
@@ -22,29 +22,31 @@ Sets up:
 
 ## Steps
 
+Substitute your PA's name for `<paName>` throughout (the example below uses the placeholder to keep the copy generic across estates).
+
 ### 1. Generate an SSH keypair
 
-Create a dedicated key for your PA. Replace `dave` with your PA's name:
+Create a dedicated key for your PA:
 
 ```bash
-ssh-keygen -t ed25519 -C "dave-pa@yourdomain.com" -f ~/.ssh/dave_pa_ed25519 -N ""
+ssh-keygen -t ed25519 -C "<paName>-pa@yourdomain.com" -f ~/.ssh/<paName>_pa_ed25519 -N ""
 ```
 
 This creates:
-- `~/.ssh/dave_pa_ed25519` (private key)
-- `~/.ssh/dave_pa_ed25519.pub` (public key)
+- `~/.ssh/<paName>_pa_ed25519` (private key)
+- `~/.ssh/<paName>_pa_ed25519.pub` (public key)
 
 ### 2. Add the public key to GitHub
 
 Copy the public key:
 
 ```bash
-cat ~/.ssh/dave_pa_ed25519.pub
+cat ~/.ssh/<paName>_pa_ed25519.pub
 ```
 
 Then add it to GitHub:
 - Go to GitHub Settings > SSH and GPG keys > New SSH key
-- Title: "Dave PA" (or your PA's name)
+- Title: "<paName> PA" (or whatever you call your PA)
 - Key type: Authentication key
 - Paste the public key
 
@@ -58,7 +60,7 @@ Add a host alias to `~/.ssh/config`:
 Host github-pa
   HostName github.com
   User git
-  IdentityFile ~/.ssh/dave_pa_ed25519
+  IdentityFile ~/.ssh/<paName>_pa_ed25519
   IdentitiesOnly yes
 ```
 
@@ -68,8 +70,8 @@ Set up the PA's git identity in your repo. Create or edit `.gitconfig` in your r
 
 ```ini
 [user]
-    name = Dave (PA)
-    email = dave-pa@yourdomain.com
+    name = <paName> (PA)
+    email = <paName>-pa@yourdomain.com
 ```
 
 Then tell git to use this config for this repo:
@@ -81,8 +83,8 @@ git config --local include.path ../.gitconfig
 Alternatively, set it directly:
 
 ```bash
-git config --local user.name "Dave (PA)"
-git config --local user.email "dave-pa@yourdomain.com"
+git config --local user.name "<paName> (PA)"
+git config --local user.email "<paName>-pa@yourdomain.com"
 ```
 
 ### 5. Update remote URL (optional)
@@ -102,15 +104,15 @@ ssh -T github-pa
 # Should output: Hi yourusername! You've successfully authenticated...
 
 git log --oneline -1
-# Commits should show "Dave (PA)" as author
+# Commits should show "<paName> (PA)" as author
 ```
 
 
 ## Security notes
 
-- The PA's SSH key should have the minimum required access -- prefer deploy keys over personal access
-- Never share the private key or commit it to the repository
-- Store the private key path in your secrets vault for reference
-- If the PA only needs to push to specific repos, use per-repo deploy keys instead of a global SSH key
-- Consider enabling signed commits for the PA identity for additional verification
-- Periodically rotate the SSH key, especially if the PA operates on shared infrastructure
+- The PA's SSH key should have the minimum required access. Prefer deploy keys over personal access.
+- Never share the private key or commit it to the repository.
+- Store the private key path in your secrets vault for reference.
+- If the PA only needs to push to specific repos, use per-repo deploy keys instead of a global SSH key.
+- Consider enabling signed commits for the PA identity for additional verification.
+- Periodically rotate the SSH key, especially if the PA operates on shared infrastructure.

package/dist/engineering-pa-core/docs/blueprints/scheduled-distillation/blueprint.md

@@ -43,8 +43,8 @@ On macOS/launchd, the installer auto-injects `PATH` (captured from the
 install-time shell), `HOME`, and `DAVE_ROOT` into the generated plist,
 so Homebrew-installed tools (`node`, `claude`, `git`) work out of the
 box. Any key you list under `environment` overrides the auto-injected
-default. On cron/systemd/schtasks, only the keys you declare are set —
-no auto-defaults — because those backends do not have launchd's
+default. On cron/systemd/schtasks, only the keys you declare are set;
+no auto-defaults; because those backends do not have launchd's
 minimal-environment footgun. Values support `${DAVE_ROOT}`, `${HOME}`,
 and `${USER}` substitution at install time.
 

package/dist/engineering-pa-core/docs/commands/init.md

@@ -32,7 +32,7 @@ Capture as:
   "hostname": "<hostname output>",
   "os": "<uname -s output>",
   "arch": "<uname -m output>",
-  "daveRoot": "<resolved project root — absolute path>"
+  "daveRoot": "<resolved project root; absolute path>"
 }
 ```
 

package/dist/engineering-pa-core/docs/commands/onboard.md

@@ -1,5 +1,5 @@
 ---
-description: First-session onboarding walkthrough — verifies the install, offers optional setup (Atlassian, workspace, alias, profile intake), and marks each step complete.
+description: First-session onboarding walkthrough; verifies the install, offers optional setup (Atlassian, workspace, alias, profile intake), and marks each step complete.
 when_to_use: >-
   Run on the operator's first session in a fresh scaffolded PA instance. Also
   re-runnable any time later: every step is idempotent and reads the current
@@ -10,7 +10,7 @@ argument-hint: (no arguments)
 context: inline
 ---
 
-# /onboard — first-session walkthrough
+# /onboard; first-session walkthrough
 
 You are running the onboarding walkthrough for a freshly scaffolded PA instance.
 The scaffold has already run `pnpm install` and `pa status` at scaffold time, so
@@ -50,7 +50,7 @@ secrets need (see `packages/core/src/vault/tool-needs.mjs`), and set to
 `notNeeded` when the tool-needs cross-reference is empty. Both `done`
 and `notNeeded` pass the completion gate.
 
-If the file is missing, the scaffold did not seed it — flag that and stop.
+If the file is missing, the scaffold did not seed it; flag that and stop.
 
 If `completedAt` is set, tell the operator onboarding is already complete and
 offer to re-run a specific step by name. Do not walk the whole flow again.
@@ -73,12 +73,12 @@ to upgrade before continuing.
 Run `pnpm exec pa status` and capture the installed package version. Compare
 against `npm view @stravica-ai/digital-operator-pa version`. On a match, mark
 done and move on. On a mismatch, print both versions and the recovery line
-(`pnpm install` inside the instance) — do not attempt the fix yourself.
+(`pnpm install` inside the instance); do not attempt the fix yourself.
 
 ### 3. profileIntake
 
 Ask the operator four questions in one turn. Question 4 is optional
-and explicitly skippable — a first-day operator often has no strong
+and explicitly skippable; a first-day operator often has no strong
 answer and a forced answer here becomes a stale steering signal for
 the whole life of the instance. "Skip" is the safe default when the
 operator hesitates.
@@ -238,7 +238,7 @@ Otherwise, name the keys the enabled tools declare and route the
 operator to a purpose-built secret-handling surface. Two ship in every
 install and both keep values off the conversation:
 
-- The workspace **Secrets** page — nav id `secrets`, at
+- The workspace **Secrets** page; nav id `secrets`, at
   `<workspace>/secrets.html`.
 - The `secrets` CLI in the operator's own terminal, using the stdin
   form: `pnpm exec secrets set <KEY> -`. The value is typed at the