@stravica-ai/digital-operator-pa 0.1.1 → 0.1.3

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

@@ -10,6 +10,14 @@
 
 # Delegation modes
 
+## Dispatch-first is the operating posture, not a mode you select
+
+Before the three modes below, the posture: **dispatch-first**. The PA's main thread exists for three things only — orchestrating work, keeping the work-trail current (work items, projects, spawn-log, journal, staging), and interacting with the operator. Everything that produces a work product — research, writing, code, analysis, multi-file reads — goes into a dispatch. This is stated unmissably at the top of the PA's CLAUDE.md as the "PA operating mode — dispatch-first" preamble; the modes below are only about HOW to dispatch once you have decided (single subagent vs task group), plus the narrow trivial-inline carve-out.
+
+**The produces-a-work-product test.** If the ask produces an artefact the operator or a downstream worker would consume — a draft, a code change, a research finding, a synthesised answer that took reading to build — it is dispatched. Mode 3 (single-threaded) is reserved for work that produces no such artefact: a one-line edit, a single file read, a status answer straight from `pa knowledge`, or a task whose topic sits so close to what you are already doing that a dispatch adds pollution without benefit. "Dispatching costs more than finishing" is a tie-breaker inside that narrow carve-out — never a licence to work inline on anything that produces a work product.
+
+## The three modes
+
 Three modes. Selection is a choice, not a default — each has a distinct trigger shape.
 
 ## Mode 1 — Single subagent

package/dist/engineering-pa-scaffold/templates/CLAUDE.md.template

@@ -10,6 +10,8 @@ You are a colleague, not a servant. You have opinions and you voice them -- with
 
 Your long-term goal is to learn {OPERATOR_NAME}'s judgement so thoroughly that you can operate autonomously on their behalf -- making decisions, managing tasks, running delegated work -- without needing to ask. Every interaction is training data. The measure of progress: how often can you act without escalating? Every question you have to ask that you could have answered is a gap.
 
+**PA operating mode — dispatch-first. This is the defining posture; re-read it every boot.** Your main thread exists for three things only: (1) orchestrating work, (2) keeping the work-trail current (work items, projects, spawn-log, journal, staging), and (3) interacting with {OPERATOR_NAME}. **ALL substantive work goes into a dispatch** — a subagent with a full 8-section brief. Research, writing, code, analysis, multi-file reads, anything that produces a work product: dispatched, not done inline. You lead the team by delegating, not by doing. Keeping the main thread clean is what keeps you available to {OPERATOR_NAME} and stops you burning context on work you could have handed off. The narrow inline exceptions (a one-line edit, a single file read, a status answer) are enumerated in Bucket 3 — treat them as the exception, never the reflex. When unsure: dispatch.
+
 **Autonomy envelope.** Per-task-type approval state lives at `agents/{PA_NAME}/autonomy-envelope.md`. Three states: `fullyApproved` (act, don't ask), `checkBeforeCommitting` (draft, get sign-off before durable action), `needsFullSupervision` (do not act; escalate every step). {OPERATOR_NAME} promotes or demotes at any time via `pa autonomy set`. The envelope is the durable record; your judgement calibrates day-to-day, but the envelope is what you check when the reflex is unclear. See `@stravica-ai/engineering-pa-core/docs/autonomy-envelope-tracker.md`.
 
 **This file's discipline.** Seven buckets; always-on rules per bucket sized by need, not by number. New findings land in bucket knowledge docs under `operator/knowledge/<bucket-slug>/`, not here. CLAUDE.md changes only when the operating model shifts. The Librarian never writes to this file.
@@ -58,7 +60,7 @@ Serve {OPERATOR_NAME} as PA. Two-way agreement, not one-way command execution.
 
 Stay available for {OPERATOR_NAME}. Preserve main-thread context. Lead the team through delegation, not through doing.
 
-1. **Delegate by default.** Execute inline only when trivial (one-line edit, single file read), when dispatching costs more than finishing, OR when the topic is close enough to main-thread context that a dispatch adds pollution without benefit. Off-topic tasks always dispatch -- different subjects in one thread degrade both.
+1. **Dispatch-first (see PA operating mode at the top of this file).** Substantive work is dispatched, full stop. The ONLY inline exceptions: a genuinely trivial one-off (one-line edit, single file read, a status answer straight from `pa knowledge`), or where the topic sits so close to what you are already doing that a dispatch adds pollution without benefit. "Dispatching costs more than finishing" is NOT a licence to work inline on anything that produces a work product. Off-topic tasks always dispatch -- different subjects in one thread degrade both.
 2. **Every dispatch uses the 8-section briefing contract:** Goal, Trace, Context, Tools and sources, Boundaries, Output format, Done when, Escalation rule. Structured return schemas in the Output-format section are load-bearing -- the parent only sees the worker's final message, no streaming.
 3. **Trace is load-bearing.** Without it, workers make locally consistent but globally incompatible choices.
 4. **Preserve main-thread context.** Dispatch when either (a) the reading/exploration would consume significant context, OR (b) the topic differs from the main-thread subject enough that inline work would pollute or fragment the current thread. Size is one signal; subject-continuation is another.

package/dist/engineering-pa-workspace/src/api.mjs

@@ -8,6 +8,7 @@ import { hostname } from 'node:os';
 
 import { getSecretsStatus, setSecret, MISSING_TARGET_ERROR } from './secrets-api.mjs';
 import { detect as schedulerDetect, list as schedulerList } from '../../engineering-pa-core/src/scheduler/index.mjs';
+import { filterProjectsByTeam, readTeamScopeConfig } from '../../engineering-pa-core/src/desk/team-scope.mjs';
 
 /**
  * handleApi -- route handler for all API endpoints.
@@ -78,13 +79,16 @@ export function handleApi(req, res, url, repoRoot, deps = {}) {
   }
 
   // GET /__api/projects
+  // Team-scoped through the same core filter desk/pa use: with
+  // scopeProjectsToTeam opt-in, other-team projects are hidden from the UI;
+  // fail-open (returns everything) when scoping isn't enabled. ?allTeams=1
+  // bypasses (mirrors desk --all-teams); ?team=<id> filters to one team.
   if (method === 'GET' && pathname === '/__api/projects') {
-    try {
-      const projects = walkProjects(repoRoot);
+    scopedProjects(repoRoot, url).then((projects) => {
       sendJson(res, 200, { projects });
-    } catch (err) {
+    }).catch((err) => {
       sendJson(res, 500, { error: err.message });
-    }
+    });
     return true;
   }
 
@@ -100,15 +104,15 @@ export function handleApi(req, res, url, repoRoot, deps = {}) {
   }
 
   // GET /__api/overview
+  // Same team-scoping as /__api/projects — the homepage cards read from here.
   if (method === 'GET' && pathname === '/__api/overview') {
-    try {
-      const projects = walkProjects(repoRoot);
+    scopedProjects(repoRoot, url).then((projects) => {
       const work = walkWork(repoRoot);
       const overview = buildOverview(projects, work, repoRoot);
       sendJson(res, 200, overview);
-    } catch (err) {
+    }).catch((err) => {
       sendJson(res, 500, { error: err.message });
-    }
+    });
     return true;
   }
 
@@ -745,6 +749,23 @@ function walkProjects(repoRoot) {
   return projects;
 }
 
+// Read projects filtered through the core team-scope rules (the same helpers
+// desk and `pa` use — packages/core/src/desk/team-scope.mjs). Scoping only
+// activates when operator/config/preferences.json opts in
+// (scopeProjectsToTeam:true); with no config it's a no-op that returns every
+// project (backward-compatible fail-open). Query controls mirror desk's flags:
+//   ?allTeams=1  -> bypass scoping entirely (like --all-teams)
+//   ?team=<id>   -> strict single-team filter (like --team <id>)
+async function scopedProjects(repoRoot, url) {
+  const config = await readTeamScopeConfig(repoRoot);
+  return filterProjectsByTeam(walkProjects(repoRoot), {
+    selfIdentities: config.teamIdentities,
+    scopeEnabled: config.scopeEnabled,
+    allTeams: url.searchParams.get('allTeams') === '1',
+    team: url.searchParams.get('team'),
+  });
+}
+
 function walkWork(repoRoot) {
   const workDir = join(repoRoot, 'work');
   if (!existsSync(workDir)) return [];

package/dist/engineering-pa-workspace/src/nav.mjs

@@ -12,9 +12,26 @@
  *   - A missing or absent operator manifest is not an error.
  *   - A malformed manifest is logged and skipped; the other side still loads.
  *
- * Caching: each load checks both manifest mtimes. The cached merged list is
- * returned unchanged if neither file changed since the last load. Missing
- * files are tracked with mtime 0 so their appearance triggers a reload.
+ * Per-device scoping: after merging, entries whose target page is not
+ * materialised on THIS device are dropped (not just warned). The estate runs
+ * one shared nav manifest that lists every page across all library repos, but
+ * `library-sync` only writes a page file onto a device when the repo that owns
+ * it is mounted there. So the presence of the href's target page file IS the
+ * per-entry materialisation signal — an hq-only page (e.g. article-ideas,
+ * content-calendar, both under operator/extensions/workspace/) is absent on a
+ * device that doesn't mount stravica-library-hq, so its nav entry is hidden
+ * rather than rendered as a dangling 404 link. This needs no per-entry "owner"
+ * field and no coupling to the .library-sync manifest internals: the page file
+ * library-sync lays down (or omits) is the source of truth. Hrefs whose shape
+ * we can't resolve to a local page (external links, deep paths) are left
+ * untouched.
+ *
+ * Caching: each load checks both manifest mtimes. The cached (merged + scoped)
+ * list is returned unchanged if neither file changed since the last load.
+ * Missing files are tracked with mtime 0 so their appearance triggers a reload.
+ * `library-sync` rewrites the extension nav.json as part of the same mount tree
+ * whenever it materialises or removes pages, so a materialisation transition
+ * always bumps a manifest mtime and re-triggers scoping.
  */
 
 import { readFileSync, statSync, existsSync } from 'node:fs';
@@ -107,35 +124,50 @@ function mergeItems(coreItems, extItems, warn) {
 }
 
 /**
- * Validate that every item's href resolves to an existing page, either under
- * APP_DIR or EXT_DIR (for top-level /<name>.html). Non-resolving items are
- * kept in the list with a warning so operators can see their work-in-progress.
+ * Classify an href by whether its target page is materialised on this device.
+ * Returns 'present', 'absent', or 'unresolvable'.
+ *
+ *   - Core-shape paths (/core/tools/workspace/app/<file>) resolve under appDir.
+ *   - Top-level extension-shape paths (/<file>.html) resolve under extDir or appDir.
+ *   - Any other shape (external links, deep paths) is 'unresolvable' — we cannot
+ *     (and should not) judge its local presence, so callers leave it untouched.
  */
-function warnOnMissingHrefs(items, appDir, extDir, warn) {
+function pagePresence(href, appDir, extDir) {
+  const corePrefix = '/core/tools/workspace/app/';
+  if (href.indexOf(corePrefix) === 0) {
+    const name = href.slice(corePrefix.length).split('?')[0].split('#')[0];
+    if (!name) return 'unresolvable';
+    return existsSync(join(appDir, name)) ? 'present' : 'absent';
+  }
+  const topMatch = href.match(/^\/([^/?#]+\.html)(?:[?#].*)?$/);
+  if (topMatch) {
+    const name = topMatch[1];
+    const inExt = extDir && existsSync(join(extDir, name));
+    const inApp = existsSync(join(appDir, name));
+    return (inExt || inApp) ? 'present' : 'absent';
+  }
+  return 'unresolvable';
+}
+
+/**
+ * Scope the merged list to this device: drop any entry whose target page is
+ * resolvable-in-shape but absent from disk (i.e. its owning library repo is not
+ * materialised here), logging why. Entries whose page is present, or whose href
+ * shape we can't resolve to a local page, are kept. This is what makes a shared
+ * estate-wide nav manifest render cleanly per-device without hand-editing:
+ * hq-only entries vanish on non-HQ devices because their pages were never
+ * written there.
+ */
+function scopeToMaterialised(items, appDir, extDir, warn) {
+  const kept = [];
   for (const item of items) {
-    const href = item.href;
-    // Core-shape paths: /core/tools/workspace/app/<file>
-    const corePrefix = '/core/tools/workspace/app/';
-    if (href.indexOf(corePrefix) === 0) {
-      const name = href.slice(corePrefix.length).split('?')[0].split('#')[0];
-      if (!existsSync(join(appDir, name))) {
-        warn('[nav] warning: nav item "' + item.id + '" points at missing page ' + href);
-      }
+    if (pagePresence(item.href, appDir, extDir) === 'absent') {
+      warn('[nav] hidden: nav item "' + item.id + '" page not materialised on this device (' + item.href + ')');
       continue;
     }
-    // Top-level extension-shape: /<file>.html
-    const topMatch = href.match(/^\/([^/?#]+\.html)(?:[?#].*)?$/);
-    if (topMatch) {
-      const name = topMatch[1];
-      const inExt = extDir && existsSync(join(extDir, name));
-      const inApp = existsSync(join(appDir, name));
-      if (!inExt && !inApp) {
-        warn('[nav] warning: nav item "' + item.id + '" points at missing page ' + href);
-      }
-      continue;
-    }
-    // Any other shape we leave alone — might be an external link or a deep core path.
+    kept.push(item);
   }
+  return kept;
 }
 
 /**
@@ -172,12 +204,12 @@ export function loadNav(opts) {
     ? readManifest(extManifest, 'extension nav manifest', warn)
     : [];
   const merged = mergeItems(coreItems, extItems, warn);
-  warnOnMissingHrefs(merged, appDir, extDir, warn);
+  const scoped = scopeToMaterialised(merged, appDir, extDir, warn);
 
   CACHE.coreMtimeMs = coreMtime;
   CACHE.extMtimeMs = extMtime;
-  CACHE.items = merged;
-  return merged;
+  CACHE.items = scoped;
+  return scoped;
 }
 
 /**

package/dist/engineering-pa-workspace/src/server.mjs

@@ -60,6 +60,11 @@ const APP_DIR = resolve(__dirname, '..', 'app');
 const DEBUG = process.env.WS_DEBUG === '1';
 const log = DEBUG ? console.log.bind(console) : function () {};
 const warn = DEBUG ? console.warn.bind(console) : function () {};
+// Always-on warning sink. Most diagnostics stay silent unless WS_DEBUG=1, but
+// failures that silently break operator-visible surface area (e.g. a whole
+// extension failing to load, presenting as a vague UI outage) must ALWAYS be
+// visible so the root cause is diagnosable without re-running under WS_DEBUG.
+const warnAlways = console.warn.bind(console);
 
 // --- Extension dir ---
 // Convention: operator/extensions/workspace/ overlays core app pages and
@@ -461,7 +466,11 @@ async function loadExtensions() {
       });
     }
   } catch (e) {
-    warn('[workspace] Extension api.mjs failed to load: ' + e.message);
+    // Always warn — a failed extension import takes out every route the
+    // extension registers, which surfaces to the operator as a broken UI with
+    // no obvious cause. Name the extension and the error; keep the server
+    // alive (a bad extension must not take down the whole workspace).
+    warnAlways('[workspace] Extension failed to load: ' + extApiPath + ' — ' + (e && e.stack ? e.stack : e));
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",