@stravica-ai/digital-operator-pa 0.1.20 → 0.1.21

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

@@ -1,12 +1,23 @@
 // work-cli.mjs — argv router for `pa work <verb>`.
 //
 // Verbs:
-//   pa work create [--project <id>] --title "..." --category <c> [--priority N] [--summary "..."] [--owner ...] [--assignee ...]
+//   pa work create [--project <id>] --title "..." --category <c> [--priority N] [--summary "..."] [--owner ...] [--assignee ...] [--author <token>]
 //   pa work status <id> <status>
 //   pa work list   [--project <id>] [--status ...] [--mine] [--theirs] [--all] [--json]
 //
 // PA name (for --mine resolution) is read from
 // operator/config/preferences.json. Falls back to 'pa' if missing.
+//
+// The `paName` field ALSO doubles as the fallback author-token source
+// for `pa work create` (writer-scoped id allocation, R1 of the
+// 2026-08-11 library remediation train). Precedence, highest first:
+//   1. --author flag (or opts.author from a programmatic caller)
+//   2. PA_AUTHOR_TOKEN env var
+//   3. preferences.json `paName`
+// If none resolve, `pa work create` hard-errors — the whole point of
+// R1 is that a mint with no author identity is a defect, not a
+// fall-back-to-default case. Full rationale + tests in
+// `@stravica-ai/engineering-pa-core/src/workItemId/index.mjs`.
 
 import { readPreferences } from '../../../engineering-pa-core/src/preferences.mjs';
 
@@ -18,6 +29,7 @@ const USAGE = `pa work — manage operator-repo work items
 Usage:
   pa work create [--project <id>] --title "..." --category <feature|bug|chore|discussion|research>
                  [--priority 0|1|2|3] [--summary "..."] [--owner ...] [--assignee ...]
+                 [--author <token>]
   pa work status <id> <draft|planned|in-progress|blocked|done|archived>
   pa work list   [--project <id>] [--status ...] [--category ...] [--mine] [--theirs] [--all] [--json]
   pa work -h, --help
@@ -26,6 +38,9 @@ Notes:
   - status=done stamps \`completedAt\` to today (only if not already set).
   - --mine resolves the PA name from operator/config/preferences.json
     (paName / agentName). Default: "pa".
+  - --author sets the writer-scoped id's author token. Precedence:
+    --author > PA_AUTHOR_TOKEN env > preferences.json paName. Must
+    match /^[a-z]{2,12}$/ and be present in operator/config/authors.json.
 
 Exit codes:
   0 ok | 1 usage/not-found | 2 operational failure
@@ -89,11 +104,29 @@ async function getPaName() {
   }
 }
 
+/**
+ * Read the raw `paName` (device-local overlay merged over shared). Unlike
+ * `getPaName`, this returns null if the field is unset — createWork's
+ * author-resolver treats null as "skip this source", not "fall back to
+ * literal 'pa'" (which would silently mask a missing token).
+ */
+async function readPreferencesPaName() {
+  try {
+    const repoRoot = await getRepoRoot();
+    const config = await readPreferences(repoRoot);
+    if (!config) return null;
+    return config.paName || config.agentName || null;
+  } catch {
+    return null;
+  }
+}
+
 async function doCreate(args) {
   const { flags } = parseFlags(args);
   const priority = flags.priority != null && flags.priority !== true
     ? Number(flags.priority)
     : null;
+  const preferencesPaName = await readPreferencesPaName();
   const res = await createWork({
     projectId: typeof flags.project === 'string' ? flags.project : null,
     title: typeof flags.title === 'string' ? flags.title : null,
@@ -102,6 +135,8 @@ async function doCreate(args) {
     summary: typeof flags.summary === 'string' ? flags.summary : null,
     owner: typeof flags.owner === 'string' ? flags.owner : null,
     assignee: typeof flags.assignee === 'string' ? flags.assignee : null,
+    author: typeof flags.author === 'string' ? flags.author : null,
+    preferencesPaName,
   });
   process.stdout.write(`created ${res.id}\n`);
   process.stdout.write(`  ${res.path}\n`);

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

@@ -1,18 +1,30 @@
 // work.mjs — write-side commands for `pa work <verb>`.
 //
-// Source of truth is work/w-YYYY-MM-DD-NNN.json. We never cache.
+// Source of truth is work/w-YYYY-MM-DD-*.json. We never cache.
 //
 // What lives here:
-//   - create: scaffold a new work item with the next-free NNN for today
+//   - create: scaffold a new work item with the next-free NNN in the
+//             CURRENT WRITER'S per-day sequence
 //   - status: change status (stamps `completedAt` on done)
 //   - list:   list work items, optionally filtered
 //
-// ID format and status/category enums match
-// packages/core/schema/work-item.json.
+// Id format, parsing, and author resolution all live in
+// `@stravica-ai/engineering-pa-core/src/workItemId/index.mjs` — the
+// single-source primitive for the whole estate. See its header for the
+// two legal forms (legacy + writer-scoped), the R1 remediation
+// background, and the author-token precedence rules.
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
+import {
+  parseWorkItemId,
+  isValidWorkItemId,
+  buildWorkItemId,
+  resolveAuthorToken,
+  maxNForAuthorOnDate,
+} from '../../../engineering-pa-core/src/workItemId/index.mjs';
+
 import { getRepoRoot } from './repo-root.mjs';
 import { readJson, writeJson, ensureDir, listJsonFiles, today } from './io.mjs';
 
@@ -20,8 +32,6 @@ const STATUSES = new Set(['draft', 'planned', 'in-progress', 'blocked', 'done',
 
 const CATEGORIES = new Set(['feature', 'bug', 'chore', 'discussion', 'research']);
 
-const ID_RE = /^w-(\d{4}-\d{2}-\d{2})-(\d{3})$/;
-
 function validateStatus(status) {
   if (!STATUSES.has(status)) {
     const err = new Error(
@@ -53,38 +63,44 @@ function validatePriority(priority) {
 }
 
 /**
- * Scan work/*.json for the highest NNN with today's date. Returns the
- * next free NNN, zero-padded to 3 digits. Result is always "001"–"999".
+ * Highest NNN already allocated for `dateStr` in THIS author's per-day
+ * sequence. Legacy items (`w-YYYY-MM-DD-NNN` with no author segment)
+ * do not count toward any author's sequence — each writer starts from
+ * 001 on the day writer-scoping takes effect and existing legacy items
+ * simply occupy a separate, older space.
  *
  * If 999 is already taken, throws — callers should treat as an
- * operational failure and report. In practice this is unreachable.
+ * operational failure and report. In practice this is unreachable
+ * because NNN is per-author-per-day, not shared.
  */
-async function nextWorkNumber(repoRoot, dateStr) {
+async function nextWorkNumber(repoRoot, dateStr, author) {
   const dir = join(repoRoot, 'work');
   const files = await listJsonFiles(dir);
-  let max = 0;
-  const prefix = `w-${dateStr}-`;
-  for (const file of files) {
-    if (!file.startsWith(prefix)) continue;
-    const m = file.match(/^w-\d{4}-\d{2}-\d{2}-(\d{3})\.json$/);
-    if (!m) continue;
-    const n = parseInt(m[1], 10);
-    if (Number.isFinite(n) && n > max) max = n;
-  }
+  const max = maxNForAuthorOnDate(files, dateStr, author);
   const next = max + 1;
   if (next > 999) {
-    const err = new Error(`no free work-item slot for ${dateStr} (NNN exhausted)`);
+    const err = new Error(
+      `no free work-item slot for ${dateStr} in author=${author} sequence (NNN exhausted)`,
+    );
     err.exitCode = 2;
     throw err;
   }
-  return String(next).padStart(3, '0');
+  return next;
 }
 
 /**
  * Create a new work item. Returns { id, path }.
  *
  * Status defaults to "draft" per the brief. Date and NNN are
- * auto-derived from today; we do not accept overrides.
+ * auto-derived; we do not accept overrides.
+ *
+ * Author token comes from `opts.author` (explicit; wins over anything
+ * else), the `PA_AUTHOR_TOKEN` env var, or the `paName` field of
+ * `operator/config/preferences.json` (passed in as
+ * `opts.preferencesPaName` by the CLI entry). If none resolve, throws
+ * with an actionable message naming all three sources — a mint with no
+ * author identity is the exact defect R1 exists to close, so we refuse
+ * to fall back to any hard-coded default.
  */
 export async function createWork(opts) {
   if (!opts.title) {
@@ -95,13 +111,24 @@ export async function createWork(opts) {
   validateCategory(opts.category);
   validatePriority(opts.priority);
 
+  let author;
+  try {
+    author = resolveAuthorToken({
+      explicit: opts.author,
+      preferencesPaName: opts.preferencesPaName,
+    });
+  } catch (e) {
+    e.exitCode = 1;
+    throw e;
+  }
+
   const repoRoot = await getRepoRoot();
   const workDir = join(repoRoot, 'work');
   await ensureDir(workDir);
 
   const dateStr = today();
-  const nnn = await nextWorkNumber(repoRoot, dateStr);
-  const id = `w-${dateStr}-${nnn}`;
+  const nnn = await nextWorkNumber(repoRoot, dateStr, author);
+  const id = buildWorkItemId({ date: dateStr, author, nnn });
   const path = join(workDir, `${id}.json`);
 
   const item = {
@@ -127,10 +154,16 @@ export async function createWork(opts) {
 /**
  * Set work-item status. Stamps `completedAt` to today's date when
  * status=done (only if not already set). Always bumps `updated`.
+ *
+ * Accepts both legacy `w-YYYY-MM-DD-NNN` and writer-scoped
+ * `w-YYYY-MM-DD-<author>-NNN` ids — every existing item in the estate
+ * predates R1 and must remain mutable through this command.
  */
 export async function setWorkStatus(id, status) {
-  if (!ID_RE.test(id)) {
-    const err = new Error(`invalid work id: ${id} (expected w-YYYY-MM-DD-NNN)`);
+  if (!isValidWorkItemId(id)) {
+    const err = new Error(
+      `invalid work id: ${id} (expected w-YYYY-MM-DD-NNN or w-YYYY-MM-DD-<author>-NNN)`,
+    );
     err.exitCode = 1;
     throw err;
   }
@@ -157,6 +190,12 @@ export async function setWorkStatus(id, status) {
  * List work items. Filters: status, category, project, owner, assignee,
  * mine, theirs, all, paName (used for --mine resolution).
  * By default excludes done + archived (mirrors desk-list semantics).
+ *
+ * Reads any well-formed work item (both id forms). Skips files whose
+ * filename does not parse as a work-item id at all — the same
+ * skip-unparseable posture the original had, restated against the
+ * shared parser so an in-directory README or a stray temp file cannot
+ * poison the listing.
  */
 export async function listWork(filters = {}) {
   const repoRoot = await getRepoRoot();
@@ -164,10 +203,11 @@ export async function listWork(filters = {}) {
   const files = await listJsonFiles(dir);
   const items = [];
   for (const f of files) {
+    if (!parseWorkItemId(f)) continue;
     try {
       items.push(await readJson(join(dir, f)));
     } catch {
-      // Skip unparseable.
+      // Skip unparseable JSON contents.
     }
   }
   let filtered = items;

package/dist/engineering-pa-core/schema/work-item.json

@@ -9,8 +9,8 @@
   "properties": {
     "id": {
       "type": "string",
-      "pattern": "^w-\\d{4}-\\d{2}-\\d{2}-\\d{3}$",
-      "description": "Work item identifier in the format w-YYYY-MM-DD-NNN"
+      "pattern": "^w-\\d{4}-\\d{2}-\\d{2}(?:-[a-z]{2,12})?-\\d{3}$",
+      "description": "Work item identifier. Two forms are permanently valid: legacy `w-YYYY-MM-DD-NNN` (pre-2026-08-12 items) and writer-scoped `w-YYYY-MM-DD-<author>-NNN` (post-R1 mints; author = /^[a-z]{2,12}$/ from operator/config/authors.json). New allocators must always emit the writer-scoped form — see packages/core/src/workItemId/index.mjs."
     },
     "projectId": {
       "type": ["string", "null"],

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

@@ -0,0 +1,219 @@
+// workItemId/index.mjs — the canonical work-item-id primitive.
+//
+// One place, every rule. Every writer on the estate MUST parse work-item
+// ids through `parseWorkItemId` (accepts both legal forms) and MUST mint
+// new ids through `buildWorkItemId` (always the writer-scoped form).
+// Nothing outside this module gets to know the shape of an id, and
+// nothing outside this module gets to decide what the current writer's
+// author token is.
+//
+// ────────────────────────────────────────────────────────────────────────
+// Background — w-2026-08-12-001, R1 of the library remediation train.
+//
+// The estate has ≥5 autonomous writers competing for one filename space
+// (`work/w-YYYY-MM-DD-NNN.json`): Dave's macbook session, Dex's
+// wsd-laptop session, librarian-pr-intake on ops-01, upstream-triage on
+// smarthome01, Baz manual. Each allocated the next-free NNN from its own
+// locally-visible git state, and sync latency meant visible state lied.
+// Four dual-mint collisions in two weeks; the 2026-08-11 collision
+// wedged the ops-01 librarian sweep for 2+ hours (see incident
+// `2026-08-11-wedge-root-cause-d024.md` and library architecture review
+// `2026-08-11-library-architecture-review.md` §2.4 collision surface).
+//
+// Baz ratified the fix 2026-08-11: writer-scoped per-day sequences. Each
+// writer gets its own NNN space, keyed by an author token from the
+// authors registry (`operator/config/authors.json`). Cross-writer
+// collision is now structurally impossible with zero coordination.
+// Legacy ids without an author segment remain valid PARSE targets
+// forever (forward-only migration; existing items never renumbered) but
+// no allocator may ever MINT them again.
+//
+// ────────────────────────────────────────────────────────────────────────
+// The two legal forms
+//
+//   legacy:  w-YYYY-MM-DD-NNN                e.g. w-2026-08-11-025
+//   new:     w-YYYY-MM-DD-<author>-NNN       e.g. w-2026-08-12-dave-001
+//
+// Author token = /^[a-z]{2,12}$/ (lowercase letters only, 2–12 chars).
+// Deliberately all-alpha: keeps the parse alternation unambiguous
+// against the NNN segment (any middle segment starting with a digit is
+// legacy) and mirrors the registry's `dave`/`dex`/`sam`/`max`/`ian`/
+// `baz` shape without inviting alphanumeric drift.
+//
+// NNN = /^\d{3}$/, 001–999, zero-padded. NNN space is per-author-per-day,
+// which is why we never run out of headroom in practice.
+
+const AUTHOR_TOKEN_RE = /^[a-z]{2,12}$/;
+
+// Two-branch alternation — the ONE-line spec of every valid id in the
+// estate. Every other regex in this repo is either this one, or (for
+// filenames) this one with a `\.json` suffix.
+const WORK_ITEM_ID_RE = /^w-(\d{4}-\d{2}-\d{2})(?:-([a-z]{2,12}))?-(\d{3})$/;
+const WORK_ITEM_FILENAME_RE = /^w-(\d{4}-\d{2}-\d{2})(?:-([a-z]{2,12}))?-(\d{3})\.json$/;
+
+/**
+ * True iff `s` is a well-formed author token.
+ * @param {unknown} s
+ * @returns {boolean}
+ */
+export function isValidAuthorToken(s) {
+  return typeof s === 'string' && AUTHOR_TOKEN_RE.test(s);
+}
+
+/**
+ * Parse a work-item id (with or without `.json`). Accepts both the
+ * legacy `w-YYYY-MM-DD-NNN` form and the writer-scoped
+ * `w-YYYY-MM-DD-<author>-NNN` form. Returns `null` if the string is
+ * not a valid id in either form — callers decide how to handle that.
+ *
+ * @param {string} idOrFilename
+ * @returns {{ date: string, author: string | null, nnn: number, id: string, isLegacy: boolean } | null}
+ */
+export function parseWorkItemId(idOrFilename) {
+  if (typeof idOrFilename !== 'string') return null;
+  const bare = idOrFilename.endsWith('.json')
+    ? idOrFilename.slice(0, -'.json'.length)
+    : idOrFilename;
+  const m = bare.match(WORK_ITEM_ID_RE);
+  if (!m) return null;
+  const date = m[1];
+  const author = m[2] || null;
+  const nnn = parseInt(m[3], 10);
+  return { date, author, nnn, id: bare, isLegacy: author === null };
+}
+
+/**
+ * True iff `s` is a well-formed work-item id (either form). Convenience
+ * wrapper around `parseWorkItemId` for the many callers that only need
+ * a yes/no.
+ *
+ * @param {unknown} s
+ * @returns {boolean}
+ */
+export function isValidWorkItemId(s) {
+  return parseWorkItemId(String(s)) !== null;
+}
+
+/**
+ * Mint a writer-scoped id. NEW writes MUST always go through this
+ * function; the legacy form is parse-only and no allocator may re-emit
+ * it. Throws if `author` is not a valid token — that is a caller bug
+ * (an allocator with no resolved author identity), not a runtime input.
+ *
+ * @param {object} opts
+ * @param {string} opts.date    YYYY-MM-DD
+ * @param {string} opts.author  registry-validated author token
+ * @param {number} opts.nnn     1..999
+ * @returns {string}
+ */
+export function buildWorkItemId({ date, author, nnn }) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(date))) {
+    throw new Error(`buildWorkItemId: bad date: ${date}`);
+  }
+  if (!isValidAuthorToken(author)) {
+    throw new Error(
+      `buildWorkItemId: bad author token: ${JSON.stringify(author)} (expected /^[a-z]{2,12}$/)`,
+    );
+  }
+  if (!Number.isInteger(nnn) || nnn < 1 || nnn > 999) {
+    throw new Error(`buildWorkItemId: nnn out of range: ${nnn} (expected 1..999)`);
+  }
+  return `w-${date}-${author}-${String(nnn).padStart(3, '0')}`;
+}
+
+/**
+ * Resolve the current caller's author token. Precedence, highest first:
+ *
+ *   1. `opts.explicit`         — an explicit token passed by the caller
+ *                                (e.g. a HQ tool that KNOWS it is `max`
+ *                                or `ian`). ALWAYS wins.
+ *   2. `PA_AUTHOR_TOKEN` env   — session/host default.
+ *   3. `opts.preferencesPaName` — `paName` from
+ *                                `operator/config/preferences.json`,
+ *                                the interactive-session fallback.
+ *
+ * Hard-errors with an actionable message naming every source if none
+ * resolves. Rationale: an allocator without a resolved author is a
+ * design bug — silently defaulting to a hard-coded token would put us
+ * back in the collision class this whole R1 exists to close.
+ *
+ * The precedence ordering is load-bearing: HQ tools deployed on ops-01
+ * (which shares $HOME across many launch contexts) MUST be able to pin
+ * their own token via the explicit param without an ambient
+ * `PA_AUTHOR_TOKEN` inherited from the parent shell silently
+ * overriding them. Tested by
+ * `test/workItemId/resolveAuthorToken.test.mjs`.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.explicit]
+ * @param {string} [opts.envToken]           — inject env for tests; defaults to process.env.PA_AUTHOR_TOKEN
+ * @param {string} [opts.preferencesPaName]  — `paName` field from preferences.json, if loaded
+ * @returns {string}
+ */
+export function resolveAuthorToken(opts = {}) {
+  const envToken = 'envToken' in opts ? opts.envToken : process.env.PA_AUTHOR_TOKEN;
+  const candidates = [
+    { source: 'explicit param', value: opts.explicit },
+    { source: 'PA_AUTHOR_TOKEN env var', value: envToken },
+    { source: 'preferences.json paName', value: opts.preferencesPaName },
+  ];
+  for (const { source, value } of candidates) {
+    if (value == null || value === '') continue;
+    if (!isValidAuthorToken(value)) {
+      throw new Error(
+        `resolveAuthorToken: ${source} is not a valid author token: ${JSON.stringify(value)} (expected /^[a-z]{2,12}$/)`,
+      );
+    }
+    return value;
+  }
+  throw new Error(
+    'resolveAuthorToken: no author token resolved. Set one of, in order of precedence: ' +
+      '(1) an explicit token via the caller\'s API, ' +
+      '(2) the PA_AUTHOR_TOKEN environment variable, ' +
+      '(3) `paName` in operator/config/preferences.json. ' +
+      'Token must match /^[a-z]{2,12}$/. Registry lives at operator/config/authors.json.',
+  );
+}
+
+/**
+ * Compute the highest NNN already allocated for a given `date` +
+ * `author` slot from a bag of parsed work-item filenames. Legacy ids
+ * (no author segment) DO NOT count toward any author's sequence — each
+ * writer's per-day NNN space starts from 001 on the day writer-scoping
+ * takes effect, and legacy items just occupy a separate, older space.
+ *
+ * Purpose: the arithmetic every allocator does is identical; keep the
+ * rule in one place so a new writer added to the registry doesn't need
+ * to re-implement it.
+ *
+ * @param {string[]} filenames  raw directory entries
+ * @param {string}   date       YYYY-MM-DD
+ * @param {string}   author     the author whose sequence is being read
+ * @returns {number}            0 if the author has no items yet today
+ */
+export function maxNForAuthorOnDate(filenames, date, author) {
+  if (!isValidAuthorToken(author)) {
+    throw new Error(
+      `maxNForAuthorOnDate: bad author: ${JSON.stringify(author)} (expected /^[a-z]{2,12}$/)`,
+    );
+  }
+  let max = 0;
+  for (const name of filenames) {
+    const parsed = parseWorkItemId(name);
+    if (!parsed) continue;
+    if (parsed.date !== date) continue;
+    if (parsed.author !== author) continue;
+    if (parsed.nnn > max) max = parsed.nnn;
+  }
+  return max;
+}
+
+/**
+ * The regex sources, exported for callers that MUST use a raw string
+ * (JSON Schema `pattern`, other language regexes). Do not reach into
+ * `.source` in JavaScript — call `parseWorkItemId`/`isValidWorkItemId`
+ * instead.
+ */
+export const WORK_ITEM_ID_PATTERN = WORK_ITEM_ID_RE.source;
+export const WORK_ITEM_FILENAME_PATTERN = WORK_ITEM_FILENAME_RE.source;
+export const AUTHOR_TOKEN_PATTERN = AUTHOR_TOKEN_RE.source;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.20",
-  "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
+  "version": "0.1.21",
+  "description": "Digital Operator PA \u2014 single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",
   "exports": {
@@ -49,10 +49,11 @@
   "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",
+    "prepack": "node build.mjs",
     "test": "node --test --test-isolation=none test/*.test.mjs",
     "dry-publish": "node build.mjs && node scripts/dry-publish.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 \u2014 see packages/cli/test/secrets. Counts must never lie."
+}