@productbrain/cli 0.1.0-beta.72 → 0.1.0-beta.7221

package/dist/surfaces/__tests__/claude-skill-pointer-drift.test.js

@@ -0,0 +1,179 @@
+/**
+ * Claude skill pointer drift test — WP-761 E4a (TASK-251).
+ *
+ * PR #1039 review round 2 found three canonical skill bodies wrong or
+ * dangerous to invoke (git-cleanup, create-blog, prototype). Round 3 found
+ * three more (flag-cleanup, community-post, retro) plus a fourth
+ * (triage) already fixed content-wise but never load-bearing for this WP,
+ * plus a real gap in this test's own body-match assertion. The mechanism
+ * that kept drawing these findings — "expose every canonical skill as a
+ * Claude pointer, unaudited" — is cut here, not patched again: **a delivery
+ * route ships ONLY the skills WP-761 itself makes load-bearing.**
+ *
+ * INCLUDED is the whole population. Four skills today — `shaping` (WP-761
+ * TASK-245 / E1 edits this file directly), `defect-driven-review` (WP-761
+ * TASK-242 / E2 edits this file directly), and `after-merge` / `handover`
+ * (WP-761 E0 moved both out of `.claude/rules/` and into
+ * `.productbrain/skills/` as on-demand skills — landed). No other canonical
+ * skill gets a pointer from this test's population, regardless of how good
+ * its content is — being exposed here is not "this skill happens to be
+ * fine," it's "this WP depends on it," and nothing else has been audited
+ * well enough yet to make that claim.
+ *
+ * EXCLUDED_SKILLS is kept as the historical record of skills that were
+ * exposed and then found broken (round 2's three) — not consulted by the
+ * population logic below (INCLUDED already leaves them out), but still
+ * asserted to have no pointer, so a future edit can't silently re-expose
+ * a known-broken skill by, say, copy-pasting an old INCLUDED entry.
+ *
+ * Each pointer's frontmatter `name` and `description`, and its body's
+ * target line, are a deliberate denormalized copy of the canonical's
+ * (constitution §12):
+ *
+ *   - Source of truth: .productbrain/skills/<name>.md's `name:`/`description:`
+ *     and its being the file the pointer's body names.
+ *   - Query need: the loader must see a name and description in the pointer
+ *     to auto-match a request, and it cannot read a file it has not loaded.
+ *   - Sync contract: this test. It parses both frontmatter blocks and
+ *     asserts the name and description strings are equal, and that the
+ *     pointer body (frontmatter stripped) is EXACTLY the expected one-line
+ *     target — not merely contains it, so nothing can be prepended,
+ *     appended, or hidden in frontmatter — in both directions, naming the
+ *     skill on drift.
+ *
+ * Never imports the production frontmatter parser (WP-431 S4 precedent, see
+ * pb-setup-passthrough.test.ts) — an independent reader means this test
+ * doesn't share a blind spot with whatever a future generator produces.
+ * It does use the generic `yaml` library (already a repo dependency,
+ * root package.json, resolved via workspace hoisting) to parse the
+ * frontmatter block itself — that's a third-party parser, not production
+ * code, so it doesn't reintroduce the shared-blind-spot risk WP-431 S4
+ * guarded against; see readFrontmatter below (TEN-3784 finding 4: the old
+ * whitespace-joining reader couldn't tell a folded (`>-`) description from
+ * a literal (`|-`) one, or preserve a paragraph break).
+ */
+import { describe, expect, it } from 'vitest';
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { parse as parseYaml } from 'yaml';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// repo root: packages/cli/src/surfaces/__tests__ -> ../../../../..
+const REPO_ROOT = join(__dirname, '..', '..', '..', '..', '..');
+const CANONICAL_DIR = join(REPO_ROOT, '.productbrain', 'skills');
+const POINTER_ROOT = join(REPO_ROOT, '.claude', 'skills');
+/**
+ * The whole pointer population: name -> which WP-761 slice makes it
+ * load-bearing. Add an entry only when a slice of THIS work package edits
+ * or depends on the file directly — never for "this skill looks fine."
+ */
+const INCLUDED_SKILLS = {
+    shaping: 'WP-761 TASK-245 (E1) edits this file directly — adds a canonical subtraction step and RULE-288/RULE-419 citations.',
+    'defect-driven-review': 'WP-761 TASK-242 (E2) edits this file directly — adds Reviewer 2 item 9 and the Artifact clause.',
+    'after-merge': 'WP-761 E0 moves this rule out of .claude/rules/ into .productbrain/skills/ as an on-demand skill — the largest single subtraction of always-loaded bytes available to this WP.',
+    handover: 'WP-761 E0 moves this rule out of .claude/rules/ into .productbrain/skills/ as an on-demand skill, alongside after-merge.',
+};
+/**
+ * Historical record only (PR #1039 review round 2) — these were exposed,
+ * found wrong or dangerous to invoke, and removed. Not consulted by
+ * INCLUDED_SKILLS above (which already excludes them by omission); asserted
+ * below so a future edit can't silently re-expose one.
+ *
+ * `prototype` (round 2's third finding) is NOT here: E4a-2 deleted the
+ * canonical skill outright (no scaffold/manifest/sync-script has ever
+ * existed in this repo — confirmed live), so there is no file left to
+ * exclude a pointer for. https://github.com/ProductBrain/Product-OS/pull/1039#discussion_r4070378892
+ */
+const EXCLUDED_SKILLS = {
+    'git-cleanup': 'Step 7 pushes `git push origin main` directly — the forbidden direct-to-main path (worktree contract, .claude/rules/git-workflow.md). https://github.com/ProductBrain/Product-OS/pull/1039#discussion_r4070378871',
+    'create-blog': 'Step 3 hardcodes an absolute Mac path ("/Users/randyhereman/Coding/Product-OS/docs/blog/readme.md") for the mandatory voice-guide gate — fails on any other checkout. https://github.com/ProductBrain/Product-OS/pull/1039#discussion_r4070378884',
+};
+/**
+ * Parses one canonical/pointer file's frontmatter block via the `yaml`
+ * library (TEN-3784 finding 4) and returns it as a plain object. Folded
+ * (`>-`) vs literal (`|-`) block scalars and paragraph breaks are resolved
+ * per real YAML semantics, unlike the old whitespace-joining reader this
+ * replaces.
+ */
+function readFrontmatter(raw) {
+    const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!fmMatch)
+        return {};
+    const parsed = parseYaml(fmMatch[1]);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+}
+/** Strips the frontmatter block, returning only the body, trimmed. */
+function stripFrontmatter(raw) {
+    const fmMatch = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+    return (fmMatch ? raw.slice(fmMatch[0].length) : raw).trim();
+}
+describe('Claude skill pointer drift (WP-761 E4a)', () => {
+    it('INCLUDED_SKILLS <-> pointer: every listed skill has a pointer with matching name, description, and exact body', () => {
+        const names = Object.keys(INCLUDED_SKILLS).sort();
+        const mismatches = [];
+        const failedNames = new Set();
+        for (const name of names) {
+            const canonicalPath = join(CANONICAL_DIR, `${name}.md`);
+            const pointerPath = join(POINTER_ROOT, name, 'SKILL.md');
+            if (!existsSync(canonicalPath)) {
+                mismatches.push(`${name}: INCLUDED but no canonical file at .productbrain/skills/${name}.md`);
+                failedNames.add(name);
+                continue;
+            }
+            if (!existsSync(pointerPath)) {
+                mismatches.push(`${name}: INCLUDED but no pointer at .claude/skills/${name}/SKILL.md`);
+                failedNames.add(name);
+                continue;
+            }
+            const canonicalRaw = readFileSync(canonicalPath, 'utf8');
+            const pointerRaw = readFileSync(pointerPath, 'utf8');
+            const canonicalFm = readFrontmatter(canonicalRaw);
+            const pointerFm = readFrontmatter(pointerRaw);
+            const canonicalName = canonicalFm.name;
+            const pointerName = pointerFm.name;
+            if (pointerName !== name) {
+                mismatches.push(`${name}: pointer name field is "${String(pointerName)}", expected "${name}"`);
+                failedNames.add(name);
+            }
+            if (canonicalName !== name) {
+                mismatches.push(`${name}: canonical name field is "${String(canonicalName)}", expected "${name}"`);
+                failedNames.add(name);
+            }
+            const canonicalDesc = canonicalFm.description;
+            const pointerDesc = pointerFm.description;
+            if (canonicalDesc !== pointerDesc) {
+                mismatches.push(`${name}: description drift — canonical="${canonicalDesc}" pointer="${pointerDesc}"`);
+                failedNames.add(name);
+            }
+            // Exact body match (frontmatter stripped) — not `.includes()`. A
+            // pointer that prepends/appends stale or unsafe instructions, or
+            // hides the target line inside frontmatter, must go red here.
+            const expectedBody = `Read and follow .productbrain/skills/${name}.md`;
+            const actualBody = stripFrontmatter(pointerRaw);
+            if (actualBody !== expectedBody) {
+                mismatches.push(`${name}: pointer body is "${actualBody}", expected exactly "${expectedBody}"`);
+                failedNames.add(name);
+            }
+        }
+        const matched = names.length - failedNames.size;
+        expect(mismatches, `${matched}/${names.length} INCLUDED skills have a fully matching pointer`).toEqual([]);
+        expect(names.length).toBeGreaterThan(0);
+    });
+    it('pointer -> INCLUDED_SKILLS: every pointer directory is a declared INCLUDED entry (no undeclared exposure)', () => {
+        const includedNames = new Set(Object.keys(INCLUDED_SKILLS));
+        const pointerNames = existsSync(POINTER_ROOT)
+            ? readdirSync(POINTER_ROOT, { withFileTypes: true })
+                .filter((e) => e.isDirectory())
+                .map((e) => e.name)
+                .sort()
+            : [];
+        const undeclared = pointerNames.filter((name) => !includedNames.has(name));
+        expect(undeclared, `${pointerNames.length - undeclared.length}/${pointerNames.length} pointers are declared in INCLUDED_SKILLS`).toEqual([]);
+        expect(pointerNames.length, `pointer count (${pointerNames.length}) vs INCLUDED count (${includedNames.size})`).toBe(includedNames.size);
+    });
+    it('EXCLUDED_SKILLS stay excluded: no pointer directory exists for any historical-record entry', () => {
+        const stillExposed = Object.keys(EXCLUDED_SKILLS).filter((name) => existsSync(join(POINTER_ROOT, name, 'SKILL.md')));
+        expect(stillExposed, `${Object.keys(EXCLUDED_SKILLS).length - stillExposed.length}/${Object.keys(EXCLUDED_SKILLS).length} excluded skills correctly have no pointer`).toEqual([]);
+    });
+});
+//# sourceMappingURL=claude-skill-pointer-drift.test.js.map

package/dist/surfaces/__tests__/claude-skill-pointer-drift.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-skill-pointer-drift.test.js","sourceRoot":"","sources":["../../../src/surfaces/__tests__/claude-skill-pointer-drift.test.ts"],"names":[],"mappings":"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"}

package/dist/surfaces/__tests__/pb-setup-passthrough.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pb-setup-passthrough.test.d.ts.map

package/dist/surfaces/__tests__/pb-setup-passthrough.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pb-setup-passthrough.test.d.ts","sourceRoot":"","sources":["../../../src/surfaces/__tests__/pb-setup-passthrough.test.ts"],"names":[],"mappings":""}

package/dist/surfaces/__tests__/pb-setup-passthrough.test.js

@@ -0,0 +1,131 @@
+/**
+ * pb-setup canonical skill — SurfaceAdapter passthrough goldens (WP-431 S4).
+ *
+ * doneWhen #1: the canonical .productbrain/skills/pb-setup.md projects through
+ * each adapter's `transform` such that the body content is preserved verbatim
+ * (no surface-specific rewriting of the body). Per DEC-997, the skill body is
+ * the universal SSOT and uses the in-body surface-routing block to drive both
+ * CLI and chat-only flows; the adapter's job is wrapping (frontmatter,
+ * marker), not rewriting the body itself.
+ *
+ * Parity assertions per adapter:
+ *   - claude:  body emitted verbatim (no wrapping). No claude WRITE path for the skill kind
+ *              (E4b, WP-761/TASK-249) — path assertion removed, not exercised.
+ *   - cursor:  body preserved inside a Cursor SKILL.md wrapper. Path matches
+ *              `.cursor/skills/pb-setup/SKILL.md`. Triggers appear in the
+ *              wrapper's description.
+ *   - codex:   body preserved inside a Codex skill projection wrapper. Path
+ *              matches `.codex/skills/pb-setup.md`. Triggers appear in the
+ *              wrapper.
+ *   - copilot: skills not projected (skillsFormat: 'none'). Transform returns
+ *              empty string for skill kind (matches handshake.ts behavior).
+ *
+ * The test reads the canonical file from disk so a content drift in the
+ * source markdown surfaces here.
+ */
+import { describe, expect, it } from 'vitest';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { claudeAdapter } from '../adapters/claude.js';
+import { cursorAdapter } from '../adapters/cursor.js';
+import { codexAdapter } from '../adapters/codex.js';
+import { copilotAdapter } from '../adapters/copilot.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// repo root: packages/cli/src/surfaces/__tests__ -> ../../../../..
+const REPO_ROOT = join(__dirname, '..', '..', '..', '..', '..');
+const CANONICAL_PATH = join(REPO_ROOT, '.productbrain', 'skills', 'pb-setup.md');
+/**
+ * Minimal frontmatter parser tuned to the pb-setup skill shape. We avoid
+ * importing the production parser to keep this test independent of internal
+ * helper drift (the goldens are about the `transform` contract, not the
+ * parser).
+ */
+function loadCanonicalPbSetup() {
+    if (!existsSync(CANONICAL_PATH)) {
+        throw new Error(`Canonical pb-setup.md not found at ${CANONICAL_PATH}`);
+    }
+    const raw = readFileSync(CANONICAL_PATH, 'utf8');
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match)
+        throw new Error('pb-setup.md missing frontmatter');
+    const yaml = match[1];
+    const body = match[2];
+    const nameMatch = yaml.match(/^name:\s*(.+)$/m);
+    const descMatch = yaml.match(/description:\s*>-\s*\n((?:\s+.+\n?)+?)(?=^\w|^---|\Z)/m);
+    const triggers = [];
+    const trigBlock = yaml.match(/^triggers:\s*\n((?:\s+-\s.+\n?)+)/m);
+    if (trigBlock) {
+        for (const line of trigBlock[1].split('\n')) {
+            const m = line.match(/^\s+-\s+(.+)$/);
+            if (m)
+                triggers.push(m[1].trim().replace(/^["']|["']$/g, ''));
+        }
+    }
+    return {
+        name: (nameMatch?.[1] ?? 'pb-setup').trim(),
+        description: descMatch
+            ? descMatch[1].split('\n').map((l) => l.trim()).filter(Boolean).join(' ')
+            : '',
+        triggers,
+        body,
+        sourcePath: CANONICAL_PATH,
+    };
+}
+describe('pb-setup canonical skill — SurfaceAdapter passthrough', () => {
+    const canonical = loadCanonicalPbSetup();
+    it('canonical file exists with expected name and triggers', () => {
+        expect(canonical.name).toBe('pb-setup');
+        expect(canonical.triggers).toContain('pb setup');
+        expect(canonical.body.length).toBeGreaterThan(500);
+    });
+    it('claude adapter: body verbatim (no claude WRITE path for the skill kind, E4b)', () => {
+        const out = claudeAdapter.transform({ canonical: { kind: 'skill', ...canonical } });
+        expect(out).toBe(canonical.body);
+    });
+    it('cursor adapter: body content preserved inside wrapper, triggers injected, path .cursor/skills/pb-setup/SKILL.md', () => {
+        const out = cursorAdapter.transform({ canonical: { kind: 'skill', ...canonical } });
+        // Body content must appear verbatim (the cursor regex does not match
+        // `.productbrain/{skills,rules,hooks}/...md` — the body has no
+        // `.productbrain/skills/<name>.md` literal references that would be
+        // rewritten, so passthrough holds).
+        expect(out).toContain(canonical.body);
+        // Cursor wraps with its own frontmatter + marker comment.
+        expect(out.startsWith('---\nname: pb-setup')).toBe(true);
+        expect(out).toContain('source: .productbrain/skills/pb-setup.md');
+        // Triggers travel into the description per Cursor's convention.
+        expect(out).toContain('"pb setup"');
+        const path = cursorAdapter.paths({ kind: 'skill', basename: canonical.name }).projectionPath;
+        expect(path).toBe('.cursor/skills/pb-setup/SKILL.md');
+    });
+    it('codex adapter: body content preserved inside wrapper, triggers attached, path .codex/skills/pb-setup.md', () => {
+        const out = codexAdapter.transform({ canonical: { kind: 'skill', ...canonical } });
+        expect(out).toContain(canonical.body);
+        expect(out).toContain('source: .productbrain/skills/pb-setup.md');
+        // Codex wraps with a `# <name>` heading, description, and a Triggers line.
+        expect(out).toContain('# pb-setup');
+        expect(out).toContain('**Triggers:**');
+        expect(out).toContain('`pb setup`');
+        const path = codexAdapter.paths({ kind: 'skill', basename: canonical.name }).projectionPath;
+        expect(path).toBe('.codex/skills/pb-setup.md');
+    });
+    it('copilot adapter: skills not projected (skillsFormat: none), transform returns empty', () => {
+        const out = copilotAdapter.transform({ canonical: { kind: 'skill', ...canonical } });
+        expect(out).toBe('');
+        // Copilot's only target file is the aggregate copilot-instructions.md.
+        const path = copilotAdapter.paths({ kind: 'skill', basename: canonical.name }).projectionPath;
+        expect(path).toBe('.github/copilot-instructions.md');
+    });
+    it('canonical body is free of `.productbrain/{skills,rules}/<name>.md` literal refs that would trigger surface path rewrites', () => {
+        // Per DEC-997, the canonical skill body should not depend on adapter path
+        // rewriting — the in-body surface-routing block carries all surface logic.
+        // Guard: if a future edit adds such a literal reference, this test catches
+        // it BEFORE the cursor/codex transform mangles it through the regex.
+        const skillsRefs = canonical.body.match(/\.productbrain\/skills\/[\w.-]+\.md/g) ?? [];
+        const rulesRefs = canonical.body.match(/\.productbrain\/rules\/[\w.-]+\.md/g) ?? [];
+        expect(skillsRefs).toEqual([]);
+        expect(rulesRefs).toEqual([]);
+    });
+});
+//# sourceMappingURL=pb-setup-passthrough.test.js.map

package/dist/surfaces/__tests__/pb-setup-passthrough.test.js.map

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

package/dist/surfaces/__tests__/telemetry.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=telemetry.test.d.ts.map

package/dist/surfaces/__tests__/telemetry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.test.d.ts","sourceRoot":"","sources":["../../../src/surfaces/__tests__/telemetry.test.ts"],"names":[],"mappings":""}

package/dist/surfaces/__tests__/telemetry.test.js

@@ -0,0 +1,55 @@
+/**
+ * Reverse-map telemetry fallback — WP-421 S2c.
+ * When canonicalPathFor returns null on a known surface, the consumer must
+ * emit `surface-reverse-map-missing` telemetry and surface the generic upstream
+ * message ("edit upstream in .productbrain/skills|rules|hooks/").
+ */
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+const trackEventMock = vi.fn();
+vi.mock('../../lib/telemetry.js', () => ({
+    trackEvent: (...args) => trackEventMock(...args),
+}));
+import { reportReverseMapMissing, getReverseMapFallbackMessage, } from '../telemetry.js';
+import { canonicalPathForAnySurface } from '../registry.js';
+describe('reportReverseMapMissing', () => {
+    beforeEach(() => {
+        trackEventMock.mockClear();
+    });
+    it('emits surface-reverse-map-missing with surface + projectionPath', () => {
+        const warnings = [];
+        reportReverseMapMissing({ surface: 'copilot', projectionPath: '.github/copilot-instructions.md' }, (msg) => warnings.push(msg));
+        expect(trackEventMock).toHaveBeenCalledWith('surface-reverse-map-missing', {
+            surface: 'copilot',
+            projectionPath: '.github/copilot-instructions.md',
+        });
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0]).toContain('[surface-reverse-map-missing]');
+        expect(warnings[0]).toContain('copilot');
+        expect(warnings[0]).toContain(getReverseMapFallbackMessage());
+    });
+    it('exposes the canonical fallback message', () => {
+        expect(getReverseMapFallbackMessage()).toContain('.productbrain/skills');
+        expect(getReverseMapFallbackMessage()).toContain('rules');
+        expect(getReverseMapFallbackMessage()).toContain('hooks');
+    });
+});
+describe('canonicalPathForAnySurface', () => {
+    it('returns the first matching adapter for a known projection path', () => {
+        const cursorMatch = canonicalPathForAnySurface('.cursor/rules/foo.mdc');
+        expect(cursorMatch).toEqual({
+            surface: 'cursor',
+            canonicalPath: '.productbrain/rules/foo.md',
+        });
+        const claudeMatch = canonicalPathForAnySurface('.claude/skills/orient.md');
+        expect(claudeMatch).toEqual({
+            surface: 'claude',
+            canonicalPath: '.productbrain/skills/orient.md',
+        });
+    });
+    it('returns null for an unknown projection path (caller emits telemetry)', () => {
+        expect(canonicalPathForAnySurface('some/unknown/path.txt')).toBeNull();
+        // Copilot's aggregate file legitimately has no reverse map → null.
+        expect(canonicalPathForAnySurface('.github/copilot-instructions.md')).toBeNull();
+    });
+});
+//# sourceMappingURL=telemetry.test.js.map

package/dist/surfaces/__tests__/telemetry.test.js.map

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

package/dist/surfaces/adapter.d.ts

@@ -0,0 +1,70 @@
+/**
+ * SurfaceAdapter — WP-421 S2c (DEC-952).
+ *
+ * One canonical asset in `.productbrain/{skills,rules,hooks}/`; per-surface adapters
+ * detect/paths/transform/goldens. New surface = adapter file + registry line.
+ *
+ * canonicalPathFor is the REVERSE map: given a projection path on a surface
+ * (e.g. `.cursor/rules/foo.mdc`), return the canonical authoring path
+ * (e.g. `.productbrain/rules/foo.md`). Returns null when the path does not
+ * belong to this adapter — callers should use the telemetry fallback in
+ * `surfaces/telemetry.ts` to emit `surface-reverse-map-missing`.
+ */
+import type { CanonicalRule, CanonicalSkill } from '../generators/portable-knowledge.js';
+/** Discriminated union covering canonical asset bodies the adapters consume. */
+export type CanonicalAssetBody = ({
+    kind: 'skill';
+} & CanonicalSkill) | ({
+    kind: 'rule';
+} & CanonicalRule);
+/** Optional Chain grounding context the transform may consult when shaping output. */
+export interface ChainGroundingContext {
+    workspaceStage?: string;
+    totalRelations?: number;
+    detectedStack?: string[];
+    /** Free-form context bag for future grounding signals — adapters MUST tolerate unknown keys. */
+    [key: string]: unknown;
+}
+export interface SurfaceAssetRef {
+    kind: 'skill' | 'rule' | 'hook';
+    basename: string;
+}
+export interface SurfacePaths {
+    /** Path relative to repoRoot where the projection is written. */
+    projectionPath: string;
+}
+export interface SurfaceAdapter {
+    /** Stable machine identity (matches SurfaceName in registry.ts). */
+    name: string;
+    /** Human-friendly display label. */
+    displayName: string;
+    /**
+     * Does this surface exist in the project? Used to decide whether to project at all.
+     * Pure: only inspects repoRoot — no network, no Chain calls.
+     */
+    detect(repoRoot: string): Promise<boolean> | boolean;
+    /** Where the projection is written for a given canonical asset. */
+    paths(asset: SurfaceAssetRef): SurfacePaths;
+    /** Take a canonical asset (+ optional grounding) and produce surface-formatted content. */
+    transform(input: {
+        canonical: CanonicalAssetBody;
+        grounding?: ChainGroundingContext;
+    }): string;
+    /**
+     * Round-trip golden fixtures: pinned (canonical, expected) pairs.
+     * Each adapter MUST define at least one. Tests assert transform(canonical) === expected.
+     */
+    goldens: SurfaceGolden[];
+    /**
+     * REVERSE map from a projection path back to the canonical authoring path
+     * in `.productbrain/`. Used by tampered-bucket prompts to point users at the
+     * upstream source. Returns null when the path is unknown to this adapter.
+     */
+    canonicalPathFor(projectionPath: string): string | null;
+}
+export interface SurfaceGolden {
+    name: string;
+    canonical: CanonicalAssetBody;
+    expected: string;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/surfaces/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/surfaces/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAEzF,gFAAgF;AAChF,MAAM,MAAM,kBAAkB,GAC1B,CAAC;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,cAAc,CAAC,GACpC,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,CAAC,CAAC;AAEvC,sFAAsF;AACtF,MAAM,WAAW,qBAAqB;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,gGAAgG;IAChG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAErD,mEAAmE;IACnE,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,YAAY,CAAC;IAE5C,2FAA2F;IAC3F,SAAS,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,kBAAkB,CAAC;QAAC,SAAS,CAAC,EAAE,qBAAqB,CAAA;KAAE,GAAG,MAAM,CAAC;IAE/F;;;OAGG;IACH,OAAO,EAAE,aAAa,EAAE,CAAC;IAEzB;;;;OAIG;IACH,gBAAgB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACzD;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,kBAAkB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;CAClB"}

package/dist/surfaces/adapter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=adapter.js.map

package/dist/surfaces/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/surfaces/adapter.ts"],"names":[],"mappings":""}

package/dist/surfaces/adapters/claude.d.ts

@@ -0,0 +1,3 @@
+import type { SurfaceAdapter } from '../adapter.js';
+export declare const claudeAdapter: SurfaceAdapter;
+//# sourceMappingURL=claude.d.ts.map

package/dist/surfaces/adapters/claude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../../src/surfaces/adapters/claude.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAGV,cAAc,EAIf,MAAM,eAAe,CAAC;AAoDvB,eAAO,MAAM,aAAa,EAAE,cAQ3B,CAAC"}

package/dist/surfaces/adapters/claude.js

@@ -0,0 +1,72 @@
+/**
+ * Claude Code SurfaceAdapter — WP-421 S2c (DEC-952).
+ *
+ * Projects:
+ *   - hooks → .claude/settings.json (handled outside the per-asset transform path)
+ *
+ * The skill kind has no claude WRITE projection (E4b, WP-761/TASK-249): the repo's one
+ * statement of where a Claude skill is written is the directory-form pointer file
+ * (.claude/skills/<name>/SKILL.md, E4a); canonicalPathFor below still reverse-maps the
+ * legacy flat form for orphan detection.
+ *
+ * Rules (`.claude/rules/<name>.md`) and the skill router (`.claude/rules/skill-router.md`)
+ * are NOT projected here or anywhere else — DEC-1736 (WP-759/TASK-234): `pb handshake`
+ * stops writing `.claude/rules/*`.
+ */
+import { existsSync } from 'fs';
+import { join } from 'path';
+function transform(input) {
+    const { canonical } = input;
+    if (canonical.kind === 'rule') {
+        // The rule kind has no claude projection (DEC-1736, WP-759/TASK-234) — an unhandled kind
+        // here is a caller bug, not a silent no-op.
+        throw new Error('claude adapter does not project the rule kind');
+    }
+    // Skill kind: transform still returns the canonical body verbatim (used by goldens and by
+    // callers projecting through other means); there is no claude WRITE path for it (see paths()).
+    return canonical.body;
+}
+function paths(asset) {
+    switch (asset.kind) {
+        case 'hook':
+            return { projectionPath: '.claude/settings.json' };
+        default:
+            // DEC-1736: the rule kind has no claude projection path.
+            // E4b (WP-761/TASK-249): the skill kind has no claude WRITE path either — the
+            // flat .claude/skills/<name>.md declaration is deleted so the repo holds exactly
+            // one statement of where a Claude skill is written (the E4a directory-form pointer).
+            throw new Error(`claude adapter has no projection path for asset kind "${asset.kind}"`);
+    }
+}
+const goldenSkill = {
+    name: 'sample-skill',
+    description: 'Sample skill for golden test',
+    triggers: ['/sample'],
+    body: 'Reference .productbrain/skills/other.md inside the body.\n',
+    sourcePath: '/abs/.productbrain/skills/sample-skill.md',
+};
+const goldens = [
+    {
+        name: 'skill-verbatim-body',
+        canonical: { kind: 'skill', ...goldenSkill },
+        expected: goldenSkill.body,
+    },
+];
+function canonicalPathFor(projectionPath) {
+    // Normalize: accept paths with or without leading "./".
+    const p = projectionPath.replace(/^\.\//, '');
+    const m = p.match(/^\.claude\/skills\/(.+)\.md$/);
+    if (m)
+        return `.productbrain/skills/${m[1]}.md`;
+    return null;
+}
+export const claudeAdapter = {
+    name: 'claude',
+    displayName: 'Claude Code',
+    detect: (repoRoot) => existsSync(join(repoRoot, '.claude')),
+    paths,
+    transform,
+    goldens,
+    canonicalPathFor,
+};
+//# sourceMappingURL=claude.js.map

package/dist/surfaces/adapters/claude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../../src/surfaces/adapters/claude.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAW5B,SAAS,SAAS,CAAC,KAA2E;IAC5F,MAAM,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IAC5B,IAAI,SAAS,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC9B,yFAAyF;QACzF,4CAA4C;QAC5C,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IACD,0FAA0F;IAC1F,+FAA+F;IAC/F,OAAO,SAAS,CAAC,IAAI,CAAC;AACxB,CAAC;AAED,SAAS,KAAK,CAAC,KAAsB;IACnC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,MAAM;YACT,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,CAAC;QACrD;YACE,yDAAyD;YACzD,8EAA8E;YAC9E,iFAAiF;YACjF,qFAAqF;YACrF,MAAM,IAAI,KAAK,CAAC,yDAAyD,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;IAC5F,CAAC;AACH,CAAC;AAED,MAAM,WAAW,GAAmB;IAClC,IAAI,EAAE,cAAc;IACpB,WAAW,EAAE,8BAA8B;IAC3C,QAAQ,EAAE,CAAC,SAAS,CAAC;IACrB,IAAI,EAAE,4DAA4D;IAClE,UAAU,EAAE,2CAA2C;CACxD,CAAC;AAEF,MAAM,OAAO,GAAoB;IAC/B;QACE,IAAI,EAAE,qBAAqB;QAC3B,SAAS,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE;QAC5C,QAAQ,EAAE,WAAW,CAAC,IAAI;KAC3B;CACF,CAAC;AAEF,SAAS,gBAAgB,CAAC,cAAsB;IAC9C,wDAAwD;IACxD,MAAM,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC9C,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAClD,IAAI,CAAC;QAAE,OAAO,wBAAwB,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAChD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C,IAAI,EAAE,QAAQ;IACd,WAAW,EAAE,aAAa;IAC1B,MAAM,EAAE,CAAC,QAAgB,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACnE,KAAK;IACL,SAAS;IACT,OAAO;IACP,gBAAgB;CACjB,CAAC"}

package/dist/surfaces/adapters/codex.d.ts

@@ -0,0 +1,3 @@
+import type { SurfaceAdapter } from '../adapter.js';
+export declare const codexAdapter: SurfaceAdapter;
+//# sourceMappingURL=codex.d.ts.map

package/dist/surfaces/adapters/codex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../../src/surfaces/adapters/codex.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAGV,cAAc,EAIf,MAAM,eAAe,CAAC;AA8CvB,eAAO,MAAM,YAAY,EAAE,cAS1B,CAAC"}