@productbrain/cli 0.1.0-beta.978 → 0.1.0-beta.9784

package/dist/lib/workspaceNotice.js

@@ -0,0 +1,345 @@
+/**
+ * WP-1 — Loud workspace identity on every Chain write. WP-714 S3 extended this to every
+ * Chain READ too (see `emitEffectiveTenantNotice`'s doc comment below for the read-path wiring).
+ *
+ * Running `pb` from a directory with no repo pin (e.g. `~/`) silently resolves the
+ * GLOBAL profile and writes to whichever Chain that points at — proven live: captures
+ * meant for one workspace landed on another. This module makes every Chain read or write
+ * NAME its target workspace on stderr, and qualifies the line LOUDLY when the binding is an
+ * unpinned fallback (`global`/`default` — no repo pin) so a wrong-Chain call is never
+ * silent. An explicit binding (`local`/`env`) gets a plain, non-alarming line.
+ *
+ * Label source — the PROFILE SLUG only, via `resolveReportedProfile()`: it returns
+ * `missing-pin` when the credential cascade has ALREADY refused (nothing to name — see the
+ * formatter below), and otherwise delegates to `resolveEffectiveProfile()`, whose contract
+ * the rest of this paragraph describes.
+ * Deliberately NOT a workspace-name probe: `resolveEffectiveProfile()` reports the
+ * *configured* pin even when it dangles (TEN-2163), while a probe resolves what
+ * `resolveConfig()` actually binds. On a dangling local pin the two DISAGREE — the
+ * profile says `source='local'` (a plain, reassuring line) while the probe returns the
+ * GLOBAL workspace the write really drifts to. That would print a non-alarming line over
+ * the exact silent-drift this notice exists to expose. One resolution path means the
+ * label and its qualifier can never contradict — and there is no per-write network
+ * round-trip in front of the write.
+ *
+ * Output contract — follows capture.ts's grounding banner (the JSON-safety pattern):
+ *  - The notice is written to STDERR, never stdout, so strict-JSON stdout is byte-for-byte
+ *    unchanged in every mode.
+ *  - There is NO output-mode gate at all (WP-721). Every mode — `--json`, `--quiet`, plain TTY —
+ *    gets the one-line-per-process identity notice. `--json` used to suppress the plain line for
+ *    an explicit binding, which left an agent in a correctly pinned repo with a ZERO-BYTE stderr
+ *    and no tenant signal whatsoever (see `emitEffectiveTenantNotice` below). TEN-3238 had
+ *    already exempted the unpinned-fallback WARNING from that gate; WP-721 removed the gate.
+ *
+ * NOT compared here: the repo-local pin against the globally active `pb` profile (DEC-1632,
+ * TEN-3398/WP-720 — reversing part of WP-714 S3/PR #823). An earlier version of this module
+ * warned on that divergence on every read and write. But the pin exists precisely to OVERRIDE
+ * global, and `pb profile use` reconciles the two by default (`--local`/`--global` are the
+ * opt-in ways to diverge them) — so a divergence is only ever a deliberate act, never drift.
+ * Warning on it forever trained operators to ignore the warning: one global profile and ten
+ * pinned workspaces means nine permanent warnings on entirely correct setups. That comparison
+ * belongs at the POINT OF ACTION instead — `pb profile use --global <name>` says so once, right
+ * when an operator creates the divergence (see `commands/profile.ts`'s `pinnedElsewhere` note) —
+ * never ambiently on every read or write after the fact. The three comparisons that DO still
+ * belong here share one shape pin-vs-global didn't: *the effective tenant is not what your
+ * binding SAYS* — no explicit binding at all (the unpinned-fallback warning below), a credential
+ * silently overriding the binding (`env-key`/`local-key`/`cwd-key`, in the loud set below), or
+ * the binding moving mid-session (`sessionBinding.ts`'s refusal). Pin-vs-global was a different
+ * comparison that got mistaken for one of these.
+ *
+ * SSOT: one pure formatter + one thin emitter — called explicitly from the 7 write-command
+ * files (8 call sites) and once per process from the shared kernel wrapper (`client.ts`'s
+ * `kernelCall`/`kernelCallEnvelope`/`kernelCallWithSession` — TEN-3398/WP-711 follow-up wired
+ * the write path in too, see `emitEffectiveTenantNotice`'s doc comment below) — no per-command
+ * copy-paste.
+ *
+ * `pb admin` is a SEPARATE credential cascade (`adminConfig.ts`'s `resolveAdminConfig`) that
+ * deliberately excludes CWD env files (TEN-1334); neither cascade reads committed `config.json`
+ * siteUrl (TEN-4500). It can resolve a different tenant than the cascade above, so it gets its own formatter-reusing
+ * emitter (`emitAdminTenantNotice`/`describeAdminTenantForRefusal` below) rather than sharing
+ * `emitEffectiveTenantNotice`'s guard or resolution path.
+ */
+import { resolveReportedProfile } from './reportedProfile.js';
+import { readLocalProjectConfig } from './projectConfig.js';
+import { assertSessionStillBound } from './sessionBinding.js';
+/**
+ * Build the one-line target-workspace notice — or null when there is nothing to say.
+ *
+ *  - `none`               → null (not configured: nothing to name, stay silent).
+ *  - `missing-pin`        → null (declared project, no pin: the CLI REFUSES this write, so
+ *                           there is no target workspace to name — and never `→ unknown`).
+ *  - `cwd-key`            → LOUD, unnamed (a dotenv file here picked the Chain — same shape as
+ *                           `env-key`, different file).
+ *  - `env-key`            → LOUD, unnamed (an exported PRODUCTBRAIN_API_KEY picked the Chain;
+ *                           no profile describes it, so the write goes somewhere this process
+ *                           cannot name from config — TEN-3240).
+ *  - `preview`            → named + disposable (a deliberate `npm run pb:preview` binding; the
+ *                           PREVIEW banner already shouts, so this does not shout twice).
+ *  - `global` / `default` → qualified + hint (no repo pin → an unpinned fallback binding).
+ *  - `local` / `env`      → plain (an explicit, intentional binding).
+ *
+ * Pure: no IO. The display label is the profile slug — a single resolution path, so the
+ * label and the qualifier can never contradict each other. DEC-1632/TEN-3398: no longer
+ * compares the pin against the globally active profile — see this module's header comment.
+ */
+export function formatEffectiveTenantNotice({ profile, source }) {
+    const label = describeReportedTenant(profile, source);
+    return label ? `→ ${label}` : null;
+}
+/**
+ * The ONE place a `(profile, source)` pair maps to a human-readable label — no "→" prefix, so
+ * it can be embedded in prose (the tenant notice's base line, and WP-715's session-binding
+ * refusal message) rather than only ever printed as a standalone line. `formatEffectiveTenantNotice`
+ * above is the notice-line caller; `describeCurrentTenant` further down is the prose caller.
+ */
+export function describeReportedTenant(profile, source) {
+    if (source === 'none' || source === 'missing-pin')
+        return null;
+    // Deliberately NOT "unknown": that reads as "a workspace whose name we failed to look up".
+    // Here there is no name to look up — the credential itself chose the Chain, so the honest
+    // line names the credential and the repair (TEN-3240).
+    if (source === 'env-key') {
+        return 'unnamed workspace (PRODUCTBRAIN_API_KEY — the exported key picks the Chain, not a profile)';
+    }
+    if (source === 'cwd-key') {
+        return 'unnamed workspace (a dotenv file in this directory picks the Chain, not a profile)';
+    }
+    if (source === 'local-key') {
+        return 'unnamed workspace (config.local.json binds a credential directly, not a profile)';
+    }
+    const name = profile?.trim() || 'unknown';
+    // Deliberate and disposable: the operator ran `npm run pb:preview`, and index.ts already prints
+    // a loud PREVIEW banner on every command — so this names the workspace without a second alarm.
+    if (source === 'preview')
+        return `${name} (throwaway preview — \`npm run pb:real\` to go back)`;
+    if (source === 'global' || source === 'default') {
+        return `${name} (global default — run from your project dir to use its workspace)`;
+    }
+    // 'local' | 'env' — an explicit, intentional binding.
+    return name;
+}
+/**
+ * The repo-local PIN a direct-credential binding overrides, when the repo declares one (WP-715).
+ * Meaningful only for the three sources where a `config.local.json` `profile` field can still be
+ * PRESENT while this process does not actually use it — a direct apiKey/env/dotenv binding
+ * outranks it (DEC-1607). Mirrors `whoami.ts`'s `shadowedPin` (previously computed ad hoc,
+ * env-key only, in that one command); generalized here to the whole outranking family so any
+ * caller naming the current tenant can state a shadowed pin rather than silently drop it.
+ */
+function resolveShadowedPin(source) {
+    if (source !== 'env-key' && source !== 'cwd-key' && source !== 'local-key')
+        return null;
+    try {
+        return readLocalProjectConfig()?.profile?.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Full prose description of the tenant CURRENTLY IN PLAY, for embedding in a message whose
+ * whole point is naming it — e.g. the session-binding refusal at `sessionBinding.ts` (WP-715).
+ * Unlike `formatEffectiveTenantNotice`, this never drops a shadowed repo pin: it states it explicitly, so
+ * a refusal reading "expected X, found Y" can never render the SAME tenant on both sides (the
+ * bug this closes — `resolveEffectiveProfile().profile` is blind to a credential override, so it
+ * always named the pin even while a foreign key was the one actually in play). Always returns a
+ * string — never null/undefined — so a caller building a "found ..." sentence never has to
+ * supply its own fallback.
+ *
+ * Deliberately UNQUOTED, including the shadowed pin: `sessionBinding.ts`'s
+ * `found "${found}"` template is the one place that wraps this whole value in quotes (the same
+ * template quotes `expected` too), so quoting the pin here as well double-quoted its closing
+ * mark (`...pin "product-brain""`) — cosmetic, but it reads like a typo in the exact message an
+ * agent surfaces to a human. This function owns zero quoting; the template owns all of it.
+ */
+export function describeCurrentTenant(profile, source) {
+    const label = describeReportedTenant(profile, source) ?? 'a different, unrecorded workspace';
+    const shadowedPin = resolveShadowedPin(source);
+    return shadowedPin ? `${label}, shadowing pin ${shadowedPin}` : label;
+}
+/**
+ * Live-resolving wrapper for `client.ts`'s `describeCurrent` thunk (WP-715): re-runs
+ * `resolveReportedProfile()` — never `resolveEffectiveProfile()`, which is blind to a
+ * credential override — so a session-binding refusal always names the tenant a call would
+ * actually land in. Kept here, not client.ts, so that call site stays a one-liner.
+ */
+export function describeCurrentTenantForRefusal() {
+    const { profile, source } = resolveReportedProfile();
+    return describeCurrentTenant(profile, source);
+}
+/**
+ * Once-per-PROCESS guard (WP-714 S3). A `pb` invocation is one process, so this is really
+ * "once per command" — but a single command can reach this function many times (`pb orient`
+ * alone makes three separate `kernelCall`s). Set on the FIRST call regardless of outcome
+ * (silent 'none'/'missing-pin', json-suppressed, or an actual print): the resolved identity
+ * cannot change mid-process, so re-attempting on later calls would only ever repeat the same
+ * verdict — or, for a printed notice, repeat the same line.
+ */
+let hasAttemptedEffectiveTenantNotice = false;
+/** Test-only: reset the once-per-process guard between cases (mirrors resetReportedProfileSnapshot). */
+export function resetEffectiveTenantNoticeForTests() {
+    hasAttemptedEffectiveTenantNotice = false;
+}
+/**
+ * Resolve identity and write the target notice to STDERR — for every Chain read OR write, in
+ * EVERY output mode. WP-714 S3: originally called only from the 8 explicit write call sites;
+ * then ALSO called once per process from `client.ts`'s `kernelCall`/`kernelCallEnvelope` (the
+ * plain, non-session read path), so every read command that reaches the kernel announces too.
+ *
+ * ALSO wired into `kernelCallWithSession` (the write path) directly (TEN-3398 / WP-711
+ * follow-up). This comment used to claim that wiring was unnecessary because "every write
+ * command already calls this explicitly" — that premise was false: a census of every command
+ * module reaching `kernelCallWithSession` found 11 write commands (`accept-policy.ts`,
+ * `audit.ts`, `conflicts.ts`, `direction.ts`, `feedback.ts`, `handshake.ts`, `method.ts`,
+ * `questions.ts`, `rework.ts`, `shape.ts`, `verify.ts`) that never called this at all — a
+ * silent write with no target-workspace line, `chain.verifyEntry` and `rework.report` among
+ * them. A handful of write commands (`capture`/`promote`/`relate`/`restore`/`session`/
+ * `update`, plus the shared `organisationWrite.ts`/`runOrganisationWrite` helper used by
+ * `organisation.ts`/`organisationHierarchy.ts`) still call it explicitly, earlier in their own
+ * flow than any call `kernelCallWithSession` makes (e.g. `update`'s post-write
+ * `chain.getEntry` refresh) — the once-per-process guard makes `kernelCallWithSession`'s own
+ * call a no-op for those, so their output is unchanged bit-for-bit.
+ *
+ * Takes NO output-mode argument (WP-721). It used to take a `json` boolean that suppressed the
+ * plain line for an explicit binding; that parameter existed only to feed the gate, so it went
+ * with the gate rather than lingering as an ignored argument inviting the gate's return. The
+ * full reasoning is at the (now unconditional) emit inside the body — in short: `--json` is how
+ * agents invoke pb, agents are the bulk of both readers and writers, and a one-line-per-process
+ * stderr receipt naming the target Chain is the signal, not the noise. TEN-3238 had already made
+ * the unpinned-fallback WARNING survive `--json` for the same reason; WP-721 finished the job for
+ * the identity line itself. Safe in every mode because the notice goes to STDERR, so strict JSON
+ * on stdout stays byte-for-byte unchanged (and the CLI already writes unconditional stderr
+ * warnings elsewhere, e.g. the preview-scrub misroute in config.ts).
+ *
+ * DEC-1632/TEN-3398: does NOT compare the repo-local pin against the globally active profile —
+ * removed entirely (see this module's header comment). A prior version attached a "differs
+ * from the globally active Chain profile" line here that survived `--json` (WP-714 S3, PR
+ * #823); that line is gone, not just re-gated, because the pin existing to override global was
+ * never a warning-worthy condition in the first place.
+ *
+ * Never throws and does no network IO: a wrong/unreadable config degrades to silence, and
+ * the label comes from `resolveReportedProfile()` — only fast local config reads (no probe)
+ * in front of the call. It is safe to call immediately before any Chain read or write.
+ */
+export async function emitEffectiveTenantNotice() {
+    if (hasAttemptedEffectiveTenantNotice)
+        return;
+    hasAttemptedEffectiveTenantNotice = true;
+    let profile = null;
+    let source = 'none';
+    try {
+        ({ profile, source } = resolveReportedProfile());
+    }
+    catch {
+        return; // unreadable/racing config — say nothing rather than crash a read or write.
+    }
+    if (source === 'none' || source === 'missing-pin')
+        return;
+    // WP-721: NO `json` gate. The identity line is emitted in every mode, for every source that
+    // has a tenant to name — an explicit `local`/`env` pin included. The loud QUALIFIER for the
+    // unpinned-fallback family still differs (`describeReportedTenant` owns it, unchanged); what
+    // no longer differs is whether an agent is told anything at all.
+    //
+    // The removed gate was justified as "the plain line carries no warning, so it is pure noise in
+    // agent logs". That reasoning does not survive the shape of the thing: this is ONE line per
+    // PROCESS (the `hasAttemptedEffectiveTenantNotice` guard above), on STDERR, naming the tenant a
+    // read or write is about to touch. For an agent that is not noise — it is the receipt for the
+    // exact safety property this module exists to provide, and WP-715 states the standard outright:
+    // "Agents are the primary consumers of the pb CLI and invoke it with --json. A guard that
+    // renders only in human TTY output is, for the bulk of real usage, not shipped."
+    //
+    // The gate went unnoticed because a SECOND line — the pin-vs-global disagreement NOTICE — used
+    // to survive `--json` and happened to carry the tenant name. DEC-1632 removed that comparison
+    // (correctly: a pin exists to override global, so a divergence is deliberate, and warning on it
+    // forever is fatigue), and with it the last thing an agent saw. Proven live on
+    // `@productbrain/cli@0.1.0-beta.5421`: `pb get WP-711 --json 2>err` left `err` at ZERO BYTES in
+    // a correctly pinned repo. DEC-1632's fatigue argument was about a WARNING that fires on
+    // correct setups, never about a single identity line — so restoring this line does NOT
+    // reintroduce that comparison, and must not: see this module's header comment.
+    //
+    // Safe in every mode for the same reason the unpinned-fallback warning already was (TEN-3238):
+    // it goes to STDERR, so strict JSON on stdout stays byte-for-byte unchanged.
+    const notice = formatEffectiveTenantNotice({ profile, source });
+    if (notice)
+        process.stderr.write(notice + '\n');
+}
+/**
+ * Map `resolveAdminConfig()`'s `AdminConfigSource` onto the read/write notice's
+ * `ReportedProfileSource` vocabulary, so `pb admin` reuses the SAME formatter and label rules
+ * (`formatEffectiveTenantNotice`/`describeReportedTenant`) instead of a parallel copy. This is
+ * deliberately NOT a call to `resolveReportedProfile()` — that walks a DIFFERENT cascade
+ * (`config.ts`'s `resolveConfig`, which DOES read CWD env files — a key and its URL as a pair
+ * from the same file, never committed `config.json` siteUrl, TEN-4500) and can disagree with what `resolveAdminConfig()` actually resolved, which would name
+ * a tenant this admin call is not actually about to use. `'legacy'` (the nameless
+ * `~/.config/productbrain/.env` fallback) has no direct analog in `ReportedProfileSource` — it
+ * maps to `'default'`, the closest existing "implicit, no deliberate per-repo pin" qualifier.
+ */
+function adminSourceToReportedSource(source) {
+    switch (source) {
+        case 'env': return 'env-key';
+        case 'local-profile': return 'local';
+        case 'global-profile': return 'global';
+        case 'legacy': return 'default';
+    }
+}
+/** Admin's own once-per-process guard — separate from `hasAttemptedEffectiveTenantNotice`
+ * above, because `resolveAdminConfig()`'s cascade is a different resolution than the one that
+ * guard's notice announces.
+ *
+ * Keyed by IDENTITY (`source:profileName`), not a single boolean (TEN-3398 follow-up,
+ * `admin/probe.ts`): `pb admin probe --env prod --env dev` resolves TWO genuinely different
+ * named-profile identities in one process, by design (the whole point is comparing them side
+ * by side) — a single shared flag would announce the first and silently swallow the second,
+ * hiding exactly which tenant the comparison's second half hit. A Set still gives every OTHER
+ * admin command (one identity resolved once via `resolveAdminConfig()`, called through
+ * `adminCall` any number of times) the same "announce once" behavior a boolean gave, since
+ * repeat calls carry the identical key. */
+const announcedAdminTenantKeys = new Set();
+function adminIdentityKey(admin) {
+    return `${admin.source}:${admin.profileName ?? ''}`;
+}
+/** Test-only: reset admin's once-per-identity guard between cases. */
+export function resetAdminTenantNoticeForTests() {
+    announcedAdminTenantKeys.clear();
+}
+/**
+ * Resolve identity and write `pb admin`'s target notice to STDERR — once per DISTINCT identity
+ * per process (TEN-3398 / WP-711 follow-up: `adminCall` previously carried no notice at all,
+ * the one gap left after WP-712/WP-714 S3 covered every other kernel path).
+ *
+ * Unlike `emitEffectiveTenantNotice`, this NEVER suppresses under `--json` and has no
+ * "unpinned fallback" vs "explicit binding" distinction: every `pb admin` command can be a
+ * destructive bulk operation (`manage:delete-workspace`, `seed:backfill-starter`), so the
+ * identity line is never noise to cut, in any mode.
+ */
+export function emitAdminTenantNotice(admin) {
+    const key = adminIdentityKey(admin);
+    if (announcedAdminTenantKeys.has(key))
+        return;
+    announcedAdminTenantKeys.add(key);
+    const notice = formatEffectiveTenantNotice({
+        profile: admin.profileName,
+        source: adminSourceToReportedSource(admin.source),
+    });
+    if (notice)
+        process.stderr.write(notice + '\n');
+}
+/**
+ * Prose description of `pb admin`'s CURRENT tenant, for embedding in the
+ * `assertSessionStillBound` refusal message — mirrors `describeCurrentTenantForRefusal`'s role
+ * on the non-admin path, but resolved off `resolveAdminConfig()`'s own identity rather than
+ * `resolveReportedProfile()`, for the same reason `adminSourceToReportedSource` exists.
+ */
+export function describeAdminTenantForRefusal(admin) {
+    return describeCurrentTenant(admin.profileName, adminSourceToReportedSource(admin.source));
+}
+/**
+ * Announce AND guard one `pb admin` call in a single call (TEN-3398 / WP-711 follow-up) — kept
+ * here, not `client.ts`'s `adminCall` (STD-2/DEC-1504 module-health budget), so `adminCall`
+ * stays a one-liner and this module owns the whole admin-identity story end to end.
+ */
+export function guardAdminCall(admin, session, fingerprint) {
+    emitAdminTenantNotice(admin);
+    assertSessionStillBound(session, fingerprint, () => describeAdminTenantForRefusal(admin));
+}
+//# sourceMappingURL=workspaceNotice.js.map

package/dist/lib/workspaceNotice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceNotice.js","sourceRoot":"","sources":["../../src/lib/workspaceNotice.ts"],"names":[],"mappings":"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"}

package/dist/{setup/perimeter.d.ts → lib/writePerimeter.d.ts}

@@ -1,8 +1,13 @@
 /**
- * Setup write perimeter — WP-421 S7 (STD-236, doneWhen #22).
+ * Write perimeter — WP-421 S7 (STD-236, doneWhen #22). Re-homed from
+ * `setup/perimeter.ts` in WP-776 S3d/S3f: despite its original name, this guard was never
+ * setup-asset-specific — its job ("PB never writes outside its declared surfaces," STD-234)
+ * covers every handshake adapter write (`.claude/`, `.cursor/`, `.codex/`, etc.), which is why
+ * it survives the deletion of the setup-assets system while the module it used to live under
+ * does not.
  *
- * Single runtime guard for every disk write the setup machinery makes. Writes
- * are permitted ONLY within paths that the manifest explicitly declares safe:
+ * Single runtime guard for every disk write `pb handshake` makes. Writes are
+ * permitted ONLY within paths that the manifest explicitly declares safe:
  *
  *   - `path.resolve(process.cwd(), '.productbrain')` — hard-coded canonical
  *     authoring root. Always allowed regardless of manifest contents (this is
@@ -10,17 +15,12 @@
  *   - `path.resolve(process.cwd(), surface)` for every `surface` in
  *     `manifest.surfaces[]` — explicit per-workspace allowlist.
  *
- * Anything else throws `setup-perimeter-violation`. This is the single
+ * Anything else throws `setup-perimeter-violation` (name kept stable for tests —
+ * renaming the error code is a separate, non-mechanical change). This is the single
  * choke point the S7 perimeter fixtures exercise (HOME-sandboxed) and is the
  * only place we encode the "PB never writes outside its declared surfaces"
  * promise (STD-234) as RUNTIME enforcement rather than convention.
  *
- * Wiring follow-up: this module is NEW in S7. Adapter writers in
- * `packages/cli/src/surfaces/adapters/*.ts` and the dormant-marker
- * `appendFileSync` paths in `commands/handshake.ts` should call this guard
- * before each write. That cross-cutting wiring is intentionally out of scope
- * for S7 — see TEN capture in the slice notes (residual finding).
- *
  * Chain: STD-234 (write perimeter), STD-236 (this guard), DEC-952 (adapters),
  *        DEC-955 (manifest defaults).
  */
@@ -69,4 +69,4 @@ export declare function assertSetupWritePath(absPath: string, manifest: Perimete
  * Empty/non-string/NUL paths return false (the assert variant throws on those).
  */
 export declare function isSetupWritePathAllowed(absPath: string, manifest: PerimeterManifest, options?: PerimeterOptions): boolean;
-//# sourceMappingURL=perimeter.d.ts.map
+//# sourceMappingURL=writePerimeter.d.ts.map

package/dist/lib/writePerimeter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writePerimeter.d.ts","sourceRoot":"","sources":["../../src/lib/writePerimeter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,2EAA2E;AAC3E,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AA8B9E;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,GAAE,gBAAqB,GAC7B,IAAI,CAuBN;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAmBT"}

package/dist/{setup/perimeter.js → lib/writePerimeter.js}

@@ -1,8 +1,13 @@
 /**
- * Setup write perimeter — WP-421 S7 (STD-236, doneWhen #22).
+ * Write perimeter — WP-421 S7 (STD-236, doneWhen #22). Re-homed from
+ * `setup/perimeter.ts` in WP-776 S3d/S3f: despite its original name, this guard was never
+ * setup-asset-specific — its job ("PB never writes outside its declared surfaces," STD-234)
+ * covers every handshake adapter write (`.claude/`, `.cursor/`, `.codex/`, etc.), which is why
+ * it survives the deletion of the setup-assets system while the module it used to live under
+ * does not.
  *
- * Single runtime guard for every disk write the setup machinery makes. Writes
- * are permitted ONLY within paths that the manifest explicitly declares safe:
+ * Single runtime guard for every disk write `pb handshake` makes. Writes are
+ * permitted ONLY within paths that the manifest explicitly declares safe:
  *
  *   - `path.resolve(process.cwd(), '.productbrain')` — hard-coded canonical
  *     authoring root. Always allowed regardless of manifest contents (this is
@@ -10,17 +15,12 @@
  *   - `path.resolve(process.cwd(), surface)` for every `surface` in
  *     `manifest.surfaces[]` — explicit per-workspace allowlist.
  *
- * Anything else throws `setup-perimeter-violation`. This is the single
+ * Anything else throws `setup-perimeter-violation` (name kept stable for tests —
+ * renaming the error code is a separate, non-mechanical change). This is the single
  * choke point the S7 perimeter fixtures exercise (HOME-sandboxed) and is the
  * only place we encode the "PB never writes outside its declared surfaces"
  * promise (STD-234) as RUNTIME enforcement rather than convention.
  *
- * Wiring follow-up: this module is NEW in S7. Adapter writers in
- * `packages/cli/src/surfaces/adapters/*.ts` and the dormant-marker
- * `appendFileSync` paths in `commands/handshake.ts` should call this guard
- * before each write. That cross-cutting wiring is intentionally out of scope
- * for S7 — see TEN capture in the slice notes (residual finding).
- *
  * Chain: STD-234 (write perimeter), STD-236 (this guard), DEC-952 (adapters),
  *        DEC-955 (manifest defaults).
  */
@@ -125,4 +125,4 @@ function createPerimeterError(reason, path) {
     err.path = path;
     return err;
 }
-//# sourceMappingURL=perimeter.js.map
+//# sourceMappingURL=writePerimeter.js.map

package/dist/lib/writePerimeter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writePerimeter.js","sourceRoot":"","sources":["../../src/lib/writePerimeter.ts"],"names":[],"mappings":"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"}

package/dist/registerEntryCommands.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `pb entry propose|accept|discard|resolve` — the entry-lifecycle verbs, noun-scoped per
+ * DEC-1574 (WP-640 S4). Split out of index.ts (STD-2/DEC-1504: index.ts is
+ * grandfathered over-budget and shrink-only) — same "own every command group in
+ * its own file" split index.ts's other multi-command surfaces would benefit from.
+ *
+ * `propose` is a discoverable alias over the SAME draft-creating door `pb capture`
+ * already uses (DEC-1583: capturing creates a draft, which IS the propose act —
+ * both roads lead to one draft door; capture is NOT renamed or removed). `accept`
+ * is `pb promote`'s exact server route (chain.commitEntry) under its new name —
+ * pure rename, zero behavior change. `discard` and `resolve` are the two
+ * category verbs over `pb update --status archived` (TASK-400): the verb decides Discarded or Past;
+ * the optional `--reason` is free text recorded in the history note (DEC-1814), never a data field.
+ */
+import type { Command } from 'commander';
+export declare function registerEntryCommands(program: Command): void;
+export declare function registerRelateCommands(program: Command): void;
+//# sourceMappingURL=registerEntryCommands.d.ts.map

package/dist/registerEntryCommands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registerEntryCommands.d.ts","sourceRoot":"","sources":["../src/registerEntryCommands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqG5D;AAOD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgB7D"}

package/dist/registerEntryCommands.js

@@ -0,0 +1,123 @@
+import { runCapture } from './commands/capture.js';
+import { runEntryAccept } from './commands/entryAccept.js';
+import { runEntryDiscard, runEntryResolve } from './commands/entryDiscardResolve.js';
+import { runEntryOwn } from './commands/entryOwn.js';
+import { runEntryPreflight } from './commands/entryPreflight.js';
+import { runEntryTick } from './commands/entryTick.js';
+import { runRelate, runUnrelate } from './commands/relate.js';
+export function registerEntryCommands(program) {
+    const entryCmd = program
+        .command('entry')
+        .description('Entry-lifecycle commands — noun-scoped per DEC-1574 (propose | accept | discard | resolve | tick)');
+    entryCmd
+        .command('preflight')
+        .description('Read structural requirements before composing an entry; saves nothing')
+        .requiredOption('-c, --collection <slug>', 'Collection to inspect')
+        .option('--canonical-key <key>', 'Explicit semantic type')
+        .option('-l, --link <type:entry-id>', 'Selected context (repeatable); e.g. validates:KR-1 and commits_to:STR-1', (value, previous) => [...previous, value], [])
+        .option('-t, --link-type <type>', 'Type for any --link supplied as a bare entry ID')
+        .action(runEntryPreflight);
+    entryCmd
+        .command('propose [text...]')
+        .description('Propose (capture) a new draft entry — same draft door as `pb capture` (DEC-1583)')
+        .option('-n, --name <name>', 'Entry name (defaults to capture text)')
+        .option('-d, --description <desc>', 'Entry description, in Markdown (defaults to capture text)')
+        .option('-c, --collection <slug>', 'Explicit collection (skip auto-classification)')
+        .option('-f, --field <key=value>', 'Set a data field (repeatable; checklist: -f doneWhen="a" -f doneWhen="b", one item per flag)', (val, prev) => [...prev, val], [])
+        .option('-l, --link <entry-id>', 'Link new entry to an existing entry (TEN-705)')
+        .option('-t, --link-type <relation-type>', 'Relation type for --link — REQUIRED when --link is used (WP-688 S4): no default, the door refuses and lists the source entry\'s legal verbs if omitted')
+        .option('--source-ref <ref>', 'Source reference URI (BET-240 E2)')
+        .option('--source-excerpt <text>', 'Verbatim source excerpt (BET-240 E2)')
+        .option('--draft', 'Force the entry to draft regardless of workspace governance mode (TEN-2226)')
+        .option('--json', 'Output machine-readable JSON (deprecated: use global --json flag)')
+        .option('--strict', 'Prompt y/N before capturing when a possible duplicate is detected (WP-319)')
+        // WP-640 SWEEP (#653 review): `propose` is advertised as the same draft door as
+        // `pb capture` (DEC-1583), but this rung-2 ownership option was never registered or
+        // forwarded here — an ownership-scoped propose hit "unknown option" instead of reaching
+        // runCapture. Mirrors index.ts's `capture` registration exactly.
+        // WP-753 O1b (DEC-1715): --owner-team is deleted — an unnamed create resolves a default
+        // owner itself (the session's acting role, else the nearest Team Lead); --owner-role
+        // survives as the explicit override, its team the one you hold the role in (root first, else the shallowest).
+        .option('--owner-role <entry-id>', 'Existing Role entry ID to create AS OWNER of (WP-513 rung 2; you must hold it, and its team is the one you hold it in: root first, else the shallowest)')
+        .option('--team <team-ref>', 'For a role: the team it is born in. For a team: its parent. Defaults to the root team (TASK-681, DEC-1976)')
+        .action(async (textParts = [], opts) => {
+        const text = textParts.join(' ').trim();
+        if (!text && !opts.name) {
+            entryCmd.commands.find((c) => c.name() === 'propose')?.help();
+            return;
+        }
+        await runCapture({
+            text: text || opts.name || '', name: opts.name, description: opts.description, collection: opts.collection,
+            field: opts.field, link: opts.link, linkType: opts.linkType, sourceRef: opts.sourceRef, sourceExcerpt: opts.sourceExcerpt,
+            draft: opts.draft, json: opts.json, strict: opts.strict,
+            ownerRole: opts.ownerRole, team: opts.team,
+        });
+    });
+    entryCmd
+        .command('accept <entry-ids...>')
+        .description('Accept one or more draft entries onto the Chain (commit to SSOT). Batch: a single failure does not abort the rest (INS-1813).')
+        .option('-m, --message <text>', 'Commit message (applied to every entry in the batch)')
+        .option('--override-reason <text>', 'Typed override (≥12 chars) clearing a steering coherency block at publish — recorded with author attribution (WP-465)')
+        .option('--acknowledge <response>', 'Respond to a coherency challenge: linked | accepted-fix | diverged (WP-465)')
+        .option('--ack-entry <entry-id>', 'Authorizing entry for --acknowledge linked / accepted-fix')
+        .option('--ack-reason <text>', 'Divergence rationale (≥12 chars) for --acknowledge diverged')
+        .action(async (entryIds, opts) => {
+        await runEntryAccept({ entryIds, message: opts.message, overrideReason: opts.overrideReason, acknowledge: opts.acknowledge, ackEntry: opts.ackEntry, ackReason: opts.ackReason });
+    });
+    entryCmd
+        .command('discard <entry-id>')
+        .description('Discard a draft or current entry: it moves to the collection\'s Discarded word (TASK-400)')
+        .option('--reason <text>', 'Free text recorded in the history note')
+        .option('--note <text>', 'Change note for history')
+        .action(async (entryId, opts) => {
+        await runEntryDiscard({ entryId, reason: opts.reason, note: opts.note });
+    });
+    entryCmd
+        .command('resolve <entry-id>')
+        .description('Resolve a current entry: it moves to the collection\'s Past archive word (TASK-400)')
+        .option('--reason <text>', 'Free text recorded in the history note')
+        .option('--note <text>', 'Change note for history')
+        .action(async (entryId, opts) => {
+        await runEntryResolve({ entryId, reason: opts.reason, note: opts.note });
+    });
+    // TASK-382 (WP-770 K4): ticking a Done-when item records who/when and mints no version.
+    entryCmd
+        .command('tick <entry-id> <item-id>')
+        .description('Tick a Done-when item — records who and when, not an edit (the role that owns the record; the Team Lead only when it has no owner)')
+        .option('--undo', 'Untick the item instead')
+        .action(async (entryId, itemId, opts) => {
+        await runEntryTick({ entryId, itemId, undo: opts.undo });
+    });
+    // DEC-1710: the retired `pb organisation work own` re-homed under the entry noun — same
+    // judged door (organisation.setOwnership), no `own`'s `unown` sibling (an entry is never
+    // unowned; reassignment is the only way ownership changes).
+    entryCmd
+        .command('own <entry-id>')
+        .description('Assign an entry to one exact team and role (DEC-1710; judged by organisation.setOwnership)')
+        .requiredOption('--team <team-id>', 'Existing Team entry ID')
+        .requiredOption('--role <role-id>', 'Existing Role entry ID')
+        .action(async (entryId, opts) => {
+        await runEntryOwn(entryId, opts);
+    });
+}
+// --- Relate / Unrelate commands (TEN-704) — moved from index.ts (WP-688 S2a): index.ts is
+// grandfathered shrink-only (STD-2/DEC-1504), and this file already owns the "own every command
+// group in its own file" registrar pattern. `relate`/`unrelate` stay TOP-LEVEL commands (not
+// nested under `entry`) — this is a file-location move for LOC budget, not a DEC-1574 rename.
+export function registerRelateCommands(program) {
+    program
+        .command('relate <from-id> <type> <to-id>')
+        .description('Add a typed relation between two entries (requires active session)')
+        .option('--if-missing', 'Only create relation if it does not already exist')
+        .option('--dry-run', 'Preview the write (advisories, wouldBlock) without creating the relation (WP-688 S2a)')
+        .action(async (fromId, type, toId, opts) => {
+        await runRelate({ fromId, type, toId, ifMissing: opts.ifMissing, dryRun: opts.dryRun });
+    });
+    program
+        .command('unrelate <from-id> <type> <to-id>')
+        .description('Remove a typed relation between two entries (requires active session)')
+        .action(async (fromId, type, toId) => {
+        await runUnrelate({ fromId, type, toId });
+    });
+}
+//# sourceMappingURL=registerEntryCommands.js.map

package/dist/registerEntryCommands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registerEntryCommands.js","sourceRoot":"","sources":["../src/registerEntryCommands.ts"],"names":[],"mappings":"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"}

package/dist/registerHistoryCommand.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `pb history <entry-id>` — WP-753 V2 (TASK-203). Split out of index.ts (STD-2/DEC-1504:
+ * index.ts is grandfathered over-budget and shrink-only) — same "own every command group in
+ * its own file" split registerEntryCommands.ts already documents.
+ */
+import type { Command } from 'commander';
+export declare function registerHistoryCommand(program: Command): void;
+//# sourceMappingURL=registerHistoryCommand.d.ts.map

package/dist/registerHistoryCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registerHistoryCommand.d.ts","sourceRoot":"","sources":["../src/registerHistoryCommand.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGzC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAW7D"}