@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-core/docs/entity-location-map.md

@@ -0,0 +1,93 @@
+# Entity-Location Map
+
+Canonical paths for everything a PA refers to. Paths under "Operator space", "PA run folder", "Work and projects", and "Session" are **relative to the operator repo root** — never hard-code the absolute value. Paths under "Platform package" are inside the installed `@stravica-ai/digital-operator-pa` package and accessed via `node` import resolution rather than absolute paths in the operator repo. See [working-directory.md](./working-directory.md).
+
+
+## Operator space
+
+| What | Where |
+|---|---|
+| Operator profile | `operator/profile/operator.json` |
+| Operator knowledge | `operator/knowledge/` |
+| Domain catalogue | `operator/knowledge/domains.json` |
+| Operator notes | `operator/notes/` |
+| Config / preferences | `operator/config/preferences.json` |
+| PA memory (canonical) | `operator/memory/` |
+| Operator extensions (roles) | `operator/extensions/roles/` |
+| Operator extensions (tools) | `operator/extensions/tools/` |
+| Operator extensions (blueprints) | `operator/extensions/blueprints/` |
+| Operator extensions (workspace) | `operator/extensions/workspace/` |
+| Extension manifest | `operator/extensions/manifest.json` |
+
+
+## PA run folder
+
+| What | Where |
+|---|---|
+| PA run folder | `agents/<paName>/` |
+| PA staging | `agents/<paName>/staging/` |
+| PA journal | `agents/<paName>/journal.md` |
+| PA spawn log | `agents/<paName>/spawn-log.json` |
+| PA learned rules | `agents/<paName>/learned-rules.md` — where the estate keeps one; never created when absent (rules are then synthesised into the operator's structured knowledge docs) |
+| Next-session notes | `agents/<paName>/next-session.md` |
+| Handover artefacts | `agents/<paName>/handover/<ts>.json` |
+| PA memory (local cache) | `~/.claude/projects/<sanitised-project-path>/memory/` |
+
+
+## Work and projects
+
+| What | Where |
+|---|---|
+| Work items | `work/w-YYYY-MM-DD-NNN.json` |
+| Projects | `projects/<id>/project.json` |
+| Project progress trackers | `projects/<id>/progress.md` |
+
+
+## Platform package
+
+In v2 the platform code lives in `node_modules/@stravica-ai/digital-operator-pa/` (and its workspace-internal packages). Operator code addresses platform resources by package import path, never by an in-repo path.
+
+**Resolving symbolic `@stravica-ai/engineering-pa-*` paths.** Platform docs (and the shipped CLAUDE.md template) reference bundled assets by symbolic package path, e.g. `@stravica-ai/engineering-pa-core/docs/…`. The internal packages are `private: true` and are never installed under their own names — the symbolic path resolves inside the wrapper's bundle:
+
+```
+@stravica-ai/engineering-pa-<pkg>/<subpath>
+  → node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-<pkg>/<subpath>
+```
+
+| What | Resolved via |
+|---|---|
+| Core docs | bundled in `@stravica-ai/engineering-pa-core/docs/` |
+| Core knowledge (bucket scaffolds) | bundled in `@stravica-ai/engineering-pa-core/knowledge/` |
+| Desk CLI | `node_modules/.bin/desk` |
+| Distill CLI | `node_modules/.bin/distill` |
+| Memory-sync CLI | `node_modules/.bin/memory-sync` |
+| Secrets CLI | `node_modules/.bin/secrets` |
+| Sync CLI | `node_modules/.bin/sync` |
+| Scheduler CLI | `node_modules/.bin/scheduler` |
+| PA CLI | `node_modules/.bin/pa` |
+| pa-init scaffolder | `node_modules/.bin/pa-init` |
+| Research CLI | `node_modules/.bin/research` |
+| Knowledge retrieval libs | `import('@stravica-ai/engineering-pa-core/src/knowledge/retrieval/*.mjs')` |
+| Role definitions | bundled in `@stravica-ai/engineering-pa-core/roles/<role>/definition.md` |
+| Standards docs | bundled in `@stravica-ai/engineering-pa-core/docs/standards/` |
+| Schemas | bundled in `@stravica-ai/engineering-pa-core/schema/` |
+
+
+## Operational artefacts (gitignored)
+
+Per the tooling standard §16, per-host operational files must be in `.gitignore` and never committed:
+
+| What | Where |
+|---|---|
+| Vault | `.vault/` (encrypted; key handled by secrets CLI) |
+| Schedule definitions | `schedules/<id>.json` |
+| Distill run logs | `.cache/distill/logs/` |
+| Sync state | `.cache/estate-sync/` |
+| Research sessions | `.cache/research/sessions/<sessionId>/` |
+
+
+## Session
+
+| What | Where |
+|---|---|
+| Session environment | `.session/environment.json` |

package/dist/engineering-pa-core/docs/knowledge-scaffold.md

@@ -0,0 +1,121 @@
+# Knowledge System
+
+Dave's knowledge system provides structured, queryable storage for everything your PA learns. It is domain-based, supports linking between documents, and maintains indexes for fast retrieval.
+
+
+## How it works
+
+Knowledge is organised into domains -- logical groupings of related information. Each domain is a directory under `operator/knowledge/` containing markdown files. The domain registry at `operator/knowledge/domains.json` (seeded from `core/knowledge/scaffold/domains.json`) tracks all active domains.
+
+### Domain structure
+
+A domain directory contains:
+- Markdown files (`.md`) -- the actual knowledge content
+- An optional `index.json` -- domain-specific metadata and file listing
+- Subdirectories for sub-topics as needed
+
+### Example
+
+```
+operator/knowledge/
+  cooking/
+    index.json
+    basics.md
+    recipes.md
+    techniques/
+      fermentation.md
+  finance/
+    index.json
+    budgeting.md
+    investments.md
+```
+
+Each domain entry in `domains.json` looks like:
+
+```json
+{
+  "id": "cooking",
+  "name": "Cooking",
+  "path": "operator/knowledge/cooking",
+  "description": "Recipes, techniques, and culinary knowledge",
+  "fileCount": 3,
+  "lastUpdated": "2026-04-12T10:00:00Z"
+}
+```
+
+
+## Linking conventions
+
+Dave supports two linking formats for connecting knowledge across documents:
+
+### Wiki-links
+
+Use double-bracket syntax to link to other documents:
+
+```
+See [[fermentation]] for details on lacto-fermentation.
+```
+
+Wiki-links are resolved by searching for a file matching the target name (case-insensitive) across all knowledge domains. If multiple matches exist, the link resolves to the most recently updated one.
+
+### Standard markdown links
+
+Use standard markdown links for explicit paths:
+
+```
+See [fermentation](techniques/fermentation.md) for details.
+```
+
+
+## Backlink indexing
+
+The retrieval system maintains a backlink index -- for every document, it knows which other documents link to it. This enables:
+- "What references this topic?" queries
+- Adjacency graph traversal
+- Orphan detection (documents with no inbound or outbound links)
+
+The backlink index is rebuilt during knowledge reindexing (`npm run reindex`).
+
+
+## Adjacency graph
+
+The retrieval system builds a graph of document relationships based on links. This graph supports:
+- Finding related documents (neighbours in the graph)
+- Shortest-path queries between topics
+- Cluster detection (groups of tightly linked documents)
+
+
+## Querying knowledge
+
+The retrieval tools at `core/knowledge/retrieval/` provide:
+
+- **index-builder.mjs** -- Rebuilds all indexes (domain registry, backlinks, adjacency graph)
+- **search.mjs** -- Full-text search across all knowledge
+- **graph.mjs** -- Graph queries (neighbours, paths, clusters)
+
+Your PA uses these tools automatically when answering questions. You can also trigger a manual reindex:
+
+```bash
+npm run reindex
+```
+
+
+## Adding new knowledge
+
+1. Create a domain directory under `operator/knowledge/` if it does not exist.
+2. Add markdown files with your content.
+3. Use wiki-links or markdown links to connect related documents.
+4. Run `npm run reindex` to update indexes, or let the PA handle it during normal operation.
+
+The PA's librarian role can also be delegated to organise and structure knowledge from raw observations.
+
+
+## How knowledge flows
+
+1. **Observation** -- Your PA notices something relevant during a conversation and stages it as a timestamped markdown file.
+2. **Staging** -- Staged observations accumulate in the PA's staging directory.
+3. **Distillation** -- The librarian role processes staged observations, extracting durable knowledge and updating the operator profile.
+4. **Knowledge** -- Distilled content is filed into the appropriate domain under `operator/knowledge/`.
+5. **Indexing** -- The retrieval system rebuilds indexes to include the new content.
+
+This cycle runs continuously. Every interaction is a potential source of new knowledge.

package/dist/engineering-pa-core/docs/lock.md

@@ -0,0 +1,155 @@
+# lock — shared per-resource process lock
+
+`@stravica-ai/engineering-pa-core` › `acquireLock` — the platform-wide primitive
+for "at most one of me at a time". Public core API: consumed default-on by
+`pa launch` for every scheduled-task run, and importable by any direct-run
+tool (anything a cron invokes without going through `pa launch`) that needs
+the same protection.
+
+## Why it exists
+
+Two runs of the same scheduled task on the same host must not overlap. The
+motivating incident (2026-07-06): a supervised distillation sweep ran 1288+
+seconds and was still running as the next cron tick approached — without a
+lock, two Claude sweeps would have consumed the same staging areas
+concurrently (duplicate routing, git races). The lock closes that class of
+gap at the root: the second run exits cleanly with a logged skip instead of
+spawning a second session.
+
+## Import
+
+```js
+import { acquireLock, DEFAULT_STALE_AFTER_MS } from '@stravica-ai/engineering-pa-core';
+```
+
+## API
+
+```js
+const lock = await acquireLock(lockPath, {
+  staleAfterMs,     // optional — see "Staleness policy"; default 2 h
+  now,              // optional clock seam (tests)
+  pid,              // optional owner pid (default process.pid)
+  isProcessAlive,   // optional liveness seam (tests)
+  fs,               // optional fs seam: { readFile, writeFile, unlink, stat, mkdir }
+});
+```
+
+Returns one of:
+
+```js
+// Live contention — someone else legitimately holds it. Never thrown.
+{ acquired: false,
+  holder: { pid, acquiredAt },      // pid/acquiredAt null if lock unreadable
+  reason: 'held by pid 1234 since 2026-07-06T11:40:00Z' }
+
+// Acquired (possibly after breaking a stale lock).
+{ acquired: true,
+  record: { pid, acquiredAt },      // what was written to the lock file
+  stale: null | { pid, acquiredAt, reason: 'dead-pid' | 'age-exceeded' | 'unreadable' },
+  release: async () => {} }         // call on every exit path (try/finally)
+```
+
+When `stale` is non-null the caller SHOULD log a warning naming the broken
+lock — the steal is safe but worth an audit trail.
+
+## Lock file
+
+One JSON file per protected resource, camelCase properties:
+
+```json
+{ "pid": 12345, "acquiredAt": "2026-07-06T12:00:00Z" }
+```
+
+- **Path is caller-chosen.** Convention: one path per resource under the
+  operator repo's gitignored `.cache/` area (tooling standard §16 —
+  operational artefacts are never git-tracked). `pa launch` uses
+  `.cache/launch/<taskId>.lock`.
+- **First run needs no setup.** A missing lock file or missing parent
+  directory is the normal empty state — the directory is created on demand.
+- **Release is ownership-checked.** `release()` deletes the file only if it
+  still carries this acquisition's pid + timestamp, so a long run whose lock
+  was stolen never deletes the successor's lock. Release of an
+  already-deleted lock is a no-op.
+
+## Staleness policy
+
+Two signals decide whether an existing lock is stale, in order:
+
+1. **Dead pid — primary.** If the recorded process no longer exists
+   (`process.kill(pid, 0)` semantics; `EPERM` counts as alive), the lock is
+   broken immediately regardless of age. This is what recovers from crashed
+   runs — a run killed mid-task cannot wedge the next tick.
+2. **Age threshold — backstop.** If the recorded process appears alive but
+   the lock is older than `staleAfterMs`, it is broken anyway. This covers
+   pid reuse (the recorded pid now names an unrelated process, so signal 1
+   would report "alive" forever) and unreadable lock files (crash mid-write:
+   the pid cannot be checked, so file mtime vs `staleAfterMs` is the only
+   signal — fresher than the threshold is treated as held, older is broken).
+
+**Default: `DEFAULT_STALE_AFTER_MS` = 2 hours.** Rationale: the motivating
+consumers are scheduled agent sweeps whose legitimate runtimes are routinely
+tens of minutes (observed: 1288+ seconds), so a short window would steal a
+live lock mid-sweep; 2 hours safely clears observed long runs while still
+self-healing a pid-reuse wedge within one-to-two ticks of a typical 4-hourly
+schedule. The threshold is deliberately caller-configurable:
+
+- **Fast, well-bounded jobs should tighten it.** The `sync` CLI (seconds-long
+  git runs on a 30-minute tick) passes 10 minutes.
+- **Jobs that can legitimately run longer than 2 hours must raise it.**
+- **`pa launch` consumers** set it per task via the optional
+  `lockStaleAfterMinutes` field in `schedules/<id>.json` — no code needed.
+
+## Contention semantics for cron consumers
+
+`acquireLock` never throws for "someone else holds it" — it reports and
+lets the caller choose exit semantics. The platform convention for scheduled
+consumers is: log a greppable skip line naming the holder, write a
+`noop-locked` audit record (tooling standard §15), and **exit 0** — an
+overlap skip is a healthy no-op, not a failure, and must not generate cron
+mail. `pa launch` and `sync` both follow this. A consumer that needs the
+skip to be visible to a supervisor may exit 2 instead; document the choice.
+
+## Adopting in a direct-run tool
+
+```js
+import { acquireLock } from '@stravica-ai/engineering-pa-core';
+
+const lock = await acquireLock(join(repoRoot, '.cache', 'my-tool', 'my-tool.lock'));
+if (!lock.acquired) {
+  console.error(`[my-tool] skipped — ${lock.reason}`);
+  process.exit(0); // healthy no-op — see contention semantics above
+}
+if (lock.stale) {
+  console.error(`[my-tool] warning: broke stale lock (${lock.stale.reason}) — proceeding`);
+}
+try {
+  // ... the work ...
+} finally {
+  await lock.release();
+}
+```
+
+## Consumers
+
+| Consumer | Lock path | staleAfterMs |
+|---|---|---|
+| `pa launch` (default-on, per task) | `.cache/launch/<taskId>.lock` | 2 h default; per-task `lockStaleAfterMinutes` |
+| `estate-sync` CLI (alias: `sync`) | `.cache/estate-sync/.lock` | 10 min |
+
+## Tests
+
+```
+node --test packages/core/test/lock/lock.test.mjs
+```
+
+Covers: acquire on empty path, first-run mkdir against the real fs, live
+contention, the 1288-second long-sweep no-steal case, dead-pid steal,
+age-exceeded steal, caller-configured thresholds, unreadable-lock-file
+handling, ownership-checked release, release-after-steal, release-idempotence.
+
+## Standards
+
+Follows the [tooling standard](./standards/tooling.md): Node stdlib only
+(§3), dependency injection over mocking (§8), camelCase JSON (§11),
+gitignored operational artefacts (§16). Exit-code guidance for consumers
+derives from §6.

package/dist/engineering-pa-core/docs/memory-sync.md

@@ -0,0 +1,28 @@
+# Cross-Machine Memory Sync
+
+Your Claude Code feedback memories are synced across machines via the repo. The canonical store is `operator/memory/`. The local Claude Code cache at `~/.claude/projects/<sanitised-project-path>/memory/` is a write-through cache, not the source of truth.
+
+
+## How it works
+
+Sync is handled by `core/tools/memory-sync/`:
+
+- `SessionStart` hook runs `memory-sync pull` (repo -> cache) so every session boots with the latest memories.
+- `SessionEnd` hook runs `memory-sync push` (cache -> repo) so any new/edited memories land in git.
+- Hooks live in `.claude/settings.json` at the repo root and travel with the project.
+
+
+## How to use it
+
+Save new memories the normal way — write to the local cache path. The sync handles propagation.
+
+On a fresh machine, `git clone` the repo and start a Claude Code session; the SessionStart hook populates the cache automatically.
+
+
+## CLI
+
+```
+node core/tools/memory-sync/bin/memory-sync pull
+node core/tools/memory-sync/bin/memory-sync push
+node core/tools/memory-sync/bin/memory-sync status
+```