@pugi/cli 0.1.0-alpha.9 → 0.1.0-beta.10

package/dist/core/repl/store/types.js

@@ -0,0 +1,44 @@
+/**
+ * Persistent REPL session store — Sprint α6.4 (PR-PUGI-CLI-SESSION-STORE).
+ *
+ * Public types consumed by the REPL session module + the `pugi sessions`
+ * / `pugi resume` dispatchers. Wire format is stable:
+ *
+ *   - `SessionRow` mirrors the SQLite `sessions` table one-to-one and is
+ *     also the JSON shape returned by `pugi sessions --json`. Field names
+ *     are camelCase (PascalCase types, camelCase fields per CLAUDE.md
+ *     conventions). The SQL columns themselves stay snake_case because
+ *     they originate from raw SQL.
+ *
+ *   - `SessionEvent` is the on-disk shape of one line in
+ *     `events.<n>.jsonl`. `kind` is a closed union; `payload` is an
+ *     opaque JSON value so the producer can attach whatever fields the
+ *     event type requires without forcing the store to change.
+ *
+ *   - `SessionListOptions` / `SessionLoadEventsOptions` /
+ *     `SessionSearchOptions` are inputs the store accepts. Defaults are
+ *     spec'd inline so the test plan can pin them without reading the
+ *     implementation.
+ *
+ * The blob store + `pugi undo` + named checkpoints are α6.4b follow-ups
+ * — out of scope for THIS PR per spec. The types here intentionally do
+ * NOT model blob refs so a future blob-store landing can extend without
+ * a wire break.
+ */
+/**
+ * Concrete shape of the lock detection error so the caller can branch
+ * on `error.code === 'EBUSY_SESSION_LOCK'` rather than parsing the
+ * message. The store is the only thrower of this error.
+ */
+export class SessionLockBusyError extends Error {
+    code = 'EBUSY_SESSION_LOCK';
+    holderPid;
+    lockPath;
+    constructor(holderPid, lockPath) {
+        super(`Another pugi process (pid ${holderPid}) holds the session lock at ${lockPath}.`);
+        this.name = 'SessionLockBusyError';
+        this.holderPid = holderPid;
+        this.lockPath = lockPath;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/core/repl/store/uuid-v7.js

@@ -0,0 +1,68 @@
+/**
+ * UUID v7 generator — Sprint α6.4 (PR-PUGI-CLI-SESSION-STORE).
+ *
+ * uuid v7 (RFC 9562 draft) is a time-sortable 128-bit identifier whose
+ * first 48 bits are the unix-epoch milliseconds, the next 4 bits are
+ * the version (0b0111), the next 12 bits are sub-millisecond random
+ * entropy, the next 2 bits are the IETF variant (0b10), and the last
+ * 62 bits are random.
+ *
+ * Why v7 and not v4 (random) or v6 (gregorian time):
+ *
+ *   - The session id IS the primary key of the SQLite table. We want
+ *     inserts to land at the end of the b-tree to keep page fanout
+ *     small. v4 fragments the tree (uniformly random keys); v7 sorts
+ *     in time order so inserts are append-only.
+ *   - `pugi sessions` sorts by `updated_at DESC` for display, but the
+ *     pagination cursor uses the session id directly — a v7 id IS the
+ *     creation timestamp, so the cursor is a single column compare
+ *     instead of (updated_at, id) tuple.
+ *   - Operators see ids in `/resume` picker; v7 prefix is monotonically
+ *     increasing so the most recent session lands at the bottom of an
+ *     id sort, matching the human expectation of "newest last".
+ *
+ * Node 22 does not ship a v7 generator (`crypto.randomUUID()` is v4
+ * only). We implement it inline with `crypto.randomBytes(10)` for the
+ * entropy bits — 10 bytes covers the 12-bit random + 62-bit random
+ * fields with one syscall.
+ *
+ * Format: `xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx` where `y` is 8/9/a/b.
+ */
+import { randomBytes } from 'node:crypto';
+/**
+ * Mint a fresh uuid v7. The `now` parameter is injectable for tests so
+ * the generated id is deterministic when the test fixes the clock.
+ * Production callers pass `Date.now`.
+ */
+export function uuidV7(now = Date.now) {
+    const ms = Math.floor(now());
+    // 48-bit timestamp (6 bytes).
+    const tsHex = ms.toString(16).padStart(12, '0');
+    // 10 bytes of entropy: 12 random bits go into octet 6 (after the 4
+    // version bits), 2 variant bits go into octet 8 (high nibble 8/9/a/b),
+    // the remaining 62 bits fill octets 9..15.
+    const rand = randomBytes(10);
+    // Set version (high nibble of octet 6) to 7.
+    rand[0] = ((rand[0] ?? 0) & 0x0f) | 0x70;
+    // Set IETF variant (high two bits of octet 8) to 0b10.
+    rand[2] = ((rand[2] ?? 0) & 0x3f) | 0x80;
+    const hex = Array.from(rand, (b) => b.toString(16).padStart(2, '0')).join('');
+    // Assemble: 8-4-4-4-12.
+    return (`${tsHex.slice(0, 8)}-${tsHex.slice(8, 12)}-${hex.slice(0, 4)}-`
+        + `${hex.slice(4, 8)}-${hex.slice(8, 20)}`);
+}
+/**
+ * Extract the unix-ms timestamp from a uuid v7. Returns null when the
+ * input is not a v7 id (wrong version nibble, wrong shape). Used by
+ * `pugi sessions` to render "created N seconds ago" without reading
+ * the SQLite row.
+ */
+export function uuidV7Timestamp(id) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+        .test(id)) {
+        return null;
+    }
+    const hex = id.slice(0, 8) + id.slice(9, 13);
+    return Number.parseInt(hex, 16);
+}
+//# sourceMappingURL=uuid-v7.js.map

package/dist/core/repl/workspace-context.js

@@ -29,6 +29,16 @@ import { basename, resolve as resolvePath } from 'node:path';
 import { slugForCwd } from './history.js';
 /** Cap on the PUGI.md head we forward. Mirrors the admin-api clamp. */
 const PUGI_MD_HEAD_LIMIT = 200;
+/**
+ * Workspace label shown when the cwd has no project markers (no .git,
+ * no package.json, no PUGI.md). Per CEO 2026-05-25 dogfood, the
+ * previous behaviour leaked the parent directory basename (e.g.
+ * `codeforge-io`) into the splash as if it were a real workspace,
+ * confusing Mira/Pugi about what repo she was looking at. The
+ * unbound label is a single explicit string so the splash + status bar
+ * read the same warning. (α6.14.2 wave 5.)
+ */
+export const UNBOUND_WORKSPACE_LABEL = '(not bound - run /init OR cd into project)';
 /**
  * Resolve a `ReplWorkspaceContext` from the operator's working directory.
  * Returns a bundle with at least `workspaceCwd` + `workspaceSlug` +
@@ -38,13 +48,74 @@ const PUGI_MD_HEAD_LIMIT = 200;
 export function resolveWorkspaceContext(cwd) {
     const normalised = resolvePath(cwd);
     const slug = slugForCwd(normalised);
-    const summary = readPugiSummary(normalised) ?? basename(normalised) ?? 'workspace';
+    // α6.14.2 wave 5: when the cwd has no project markers, prefer the
+    // explicit "not bound" summary so admin-api's prompt builder knows
+    // not to fabricate a workspace context for Mira/Pugi. The cwd +
+    // slug still travel so the server can record where the operator
+    // launched from for telemetry, but the summary no longer leaks a
+    // stray parent-dir basename as if it were a real workspace.
+    const summary = isBoundWorkspace(normalised)
+        ? (readPugiSummary(normalised) ?? basename(normalised) ?? 'workspace')
+        : UNBOUND_WORKSPACE_LABEL;
     return {
         workspaceCwd: normalised,
         workspaceSlug: slug,
         workspaceSummary: summary,
     };
 }
+/**
+ * Project-marker probe used by the REPL splash + status bar to decide
+ * whether the cwd is a real workspace or a stray parent dir the
+ * operator wandered into. The probe is intentionally cheap — three
+ * `existsSync` calls — and the order matches the brand convention:
+ *
+ *   1. `.git`              — any clone of a real repo
+ *   2. `package.json`      — JS/TS workspace root
+ *   3. `PUGI.md`           — a Pugi-initialised workspace (root or
+ *                            `.pugi/PUGI.md`)
+ *
+ * Hitting any one of these counts the cwd as "bound" — the operator
+ * intentionally landed in a project. Hitting none means they ran
+ * `pugi` from `$HOME` or from the parent of a checkout; in that case
+ * the splash surfaces an explicit "not bound" label instead of leaking
+ * the parent-dir basename as if it were a workspace. The check
+ * mirrors the Claude Code "no CLAUDE.md → silent context" rule —
+ * never fake-bind. (α6.14.2 wave 5 — CEO dogfood fix.)
+ */
+export function isBoundWorkspace(cwd) {
+    const normalised = resolvePath(cwd);
+    // Case-sensitive checks; the resolver lower-cases PUGI.md when it
+    // reads the head, but the existence probe stays strict so a stray
+    // `pugi.md` does not accidentally pass without `pugi init` having
+    // run.
+    if (existsSync(resolvePath(normalised, '.git')))
+        return true;
+    if (existsSync(resolvePath(normalised, 'package.json')))
+        return true;
+    if (existsSync(resolvePath(normalised, 'PUGI.md')))
+        return true;
+    if (existsSync(resolvePath(normalised, '.pugi', 'PUGI.md')))
+        return true;
+    return false;
+}
+/**
+ * Resolve the workspace label shown on the splash + the REPL header.
+ * When the cwd has project markers, returns the directory basename;
+ * otherwise returns the explicit "not bound" warning so the operator
+ * understands no real workspace was detected. The label is the only
+ * string the splash and status bar agree on, so we centralise the
+ * decision here instead of re-deriving in two places.
+ * (α6.14.2 wave 5.)
+ */
+export function resolveWorkspaceLabel(cwd) {
+    if (!isBoundWorkspace(cwd))
+        return UNBOUND_WORKSPACE_LABEL;
+    const normalised = resolvePath(cwd);
+    const segment = basename(normalised);
+    if (!segment || segment.length === 0)
+        return 'workspace';
+    return segment;
+}
 /**
  * Read the first ~200 chars of `.pugi/PUGI.md` if the file exists. The
  * project's own description is the highest-signal one-line summary we

package/dist/core/skills/defaults.js

@@ -0,0 +1,457 @@
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { installSkill, workspaceSkillDir, } from './loader.js';
+import { hashSkillDir, recordTrust } from './trust.js';
+/**
+ * Static catalog of the three bundled defaults. Exported so the tests
+ * (and any future `pugi skills install --bundled` opt-in path) can
+ * iterate over the canonical list without re-listing skill names.
+ */
+export const DEFAULT_SKILLS = [
+    {
+        name: 'brand-voice',
+        description: 'Pugi brand voice: English in code/commits, terse in chat, no AI attribution, no emoji slop.',
+        version: '1.0.0',
+        source: 'pugi-original',
+        sourceUrl: 'https://github.com/pugi-io/pugi/blob/main/apps/pugi-cli/src/core/skills/defaults.ts',
+        license: 'MIT',
+        body: [
+            '# Brand voice',
+            '',
+            'Apply this rule set to every commit message, PR body, code comment,',
+            'generated docstring, and chat reply Pugi produces on this workspace.',
+            '',
+            '## Language split',
+            '',
+            '- Code, comments, commit messages, PR titles + bodies, technical docs,',
+            "  generated tests, log strings: **English**. Do not switch mid-line.",
+            '- Operator-facing chat replies follow the workspace `settings.json`',
+            '  `workflow.chatLang` (defaults to English when unset).',
+            '',
+            '## No AI attribution',
+            '',
+            '- Never add `Co-Authored-By: Claude` (or Codex, Gemini, Cursor) trailers',
+            '  to commits or PR bodies.',
+            '- Never write "Generated with Claude Code", "Made with AI", or any',
+            '  variant in PR descriptions, README content, or release notes.',
+            '- Pugi itself is the byline; the underlying model is implementation',
+            '  detail and stays out of customer-visible text.',
+            '',
+            '## No emoji decoration',
+            '',
+            '- Skip decorative emoji in commit messages, PR bodies, code comments,',
+            '  log lines, and chat replies.',
+            '- Functional unicode that carries meaning (math symbols, currency,',
+            '  language scripts) is fine.',
+            '',
+            '## No em dashes',
+            '',
+            '- Prefer regular hyphens or restructure the sentence. The em dash',
+            '  character reads as ChatGPT-flavoured and we keep our voice distinct.',
+            '',
+            '## Verb grammar',
+            '',
+            'Pugi exposes four customer verbs: `idea`, `plan`, `build`, `review`.',
+            'When generating help text, READMEs, or onboarding docs reference these',
+            'exact verbs in this exact order. Do not invent synonyms like "scaffold",',
+            '"draft", "ship", or "execute" for the same surface.',
+            '',
+        ].join('\n'),
+    },
+    {
+        name: 'endpoint-probe',
+        description: 'Verify every URL with a HEAD probe before codegen writes it so Pugi never ships a fabricated endpoint.',
+        version: '1.0.0',
+        source: 'pugi-original',
+        sourceUrl: 'https://github.com/pugi-io/pugi/blob/main/apps/pugi-cli/src/core/skills/defaults.ts',
+        license: 'MIT',
+        body: [
+            '# Endpoint probe',
+            '',
+            'When the model is about to write a URL into source code, configuration,',
+            'documentation, or a generated README, treat that URL as unverified',
+            'until a real HTTP probe confirms it resolves.',
+            '',
+            '## Rule',
+            '',
+            '1. Before any tool call that writes a URL (`write`, `edit`, `patch`),',
+            '   enumerate the URLs the diff introduces.',
+            '2. For each URL whose host is reachable from the workspace, issue a',
+            '   `HEAD` request (or `GET` when the host blocks `HEAD`).',
+            '3. Treat the URL as **valid** only when the response is 2xx, 3xx, or',
+            '   a documented 401/403 (auth-gated endpoint we expect).',
+            '4. Treat the URL as **invalid** on `ENOTFOUND`, `ECONNREFUSED`,',
+            '   timeout, or 4xx/5xx other than the documented auth codes. In that',
+            '   case do not write the URL; ask the operator for the correct one or',
+            '   pull it from `.pugi/settings.json` / `.env`.',
+            '',
+            '## Why this matters',
+            '',
+            'Pugi has historically shipped READMEs with installer URLs that 404,',
+            'API base URLs that point at deprecated tunnels, and "see docs at X"',
+            'links to pages that never existed. Each is a trust event: the next',
+            'operator pastes the URL, hits the 404, and assumes the whole CLI is',
+            'broken. A HEAD probe costs one round-trip and closes that class.',
+            '',
+            '## Skip cases',
+            '',
+            '- Localhost URLs (`http://127.0.0.1:*`, `http://localhost:*`): skip',
+            '  the probe; verify visually that the port matches the workspace dev',
+            '  server config instead.',
+            '- Example URLs in comments explicitly marked `// example:` or',
+            '  `# example:`: skip the probe; the operator has flagged the URL as',
+            '  illustrative.',
+            '',
+        ].join('\n'),
+    },
+    {
+        name: 'readme-sync',
+        description: 'When package.json bin/name/scripts change, cross-check README install + usage so shipped docs never drift from the binary.',
+        version: '1.0.0',
+        source: 'pugi-original',
+        sourceUrl: 'https://github.com/pugi-io/pugi/blob/main/apps/pugi-cli/src/core/skills/defaults.ts',
+        license: 'MIT',
+        body: [
+            '# README sync',
+            '',
+            'Whenever a `build` task renames a package or its binary, the README',
+            'must move with it. Stale install snippets are the most common Pugi',
+            'regression: the binary ships as `@pugi/cli` but the README still',
+            'tells the operator to `npm i -g @codeforge/cli`, and the install',
+            "fails before they ever see `pugi --version`.",
+            '',
+            '## Rule',
+            '',
+            'Whenever a diff touches `package.json` and changes any of:',
+            '',
+            '  - `name`',
+            '  - `bin`',
+            '  - `scripts.start` / `scripts.dev`',
+            '  - top-level `homepage` / `repository.url`',
+            '',
+            'then the same diff MUST also update the corresponding sections of the',
+            "package's `README.md` (and, when the package has a docs landing page,",
+            'the install snippet on that landing page too).',
+            '',
+            '## Verification snippet',
+            '',
+            'Before marking a `build` step done, run this check on every touched',
+            'package directory:',
+            '',
+            '```',
+            'pkg_name=$(jq -r .name package.json)',
+            'bin_name=$(jq -r ".bin | if type==\\"string\\" then \\"unknown\\" else keys[0] end" package.json)',
+            'grep -F "npm i -g $pkg_name" README.md || echo "MISMATCH: README missing install for $pkg_name"',
+            'grep -F "$bin_name " README.md || echo "MISMATCH: README missing usage for $bin_name"',
+            '```',
+            '',
+            'When either grep prints `MISMATCH`, fix the README before the commit',
+            'is considered ready for `review`.',
+            '',
+            '## Idempotence',
+            '',
+            'This rule applies to every package in the workspace, not just the',
+            "first one the operator mentions. A monorepo-wide rename (`@codeforge/*`",
+            "to `@pugi/*`) has to sync every README, not just the customer-facing",
+            'CLI README.',
+            '',
+        ].join('\n'),
+    },
+    {
+        name: 'zoom-out',
+        description: 'Ask Pugi to zoom out and give broader context or a higher-level perspective. Use when the model is unfamiliar with a section of code or needs to understand how it fits into the bigger picture.',
+        version: '1.0.0',
+        source: 'mattpocock/skills',
+        sourceUrl: 'https://github.com/mattpocock/skills/blob/main/skills/engineering/zoom-out/SKILL.md',
+        license: 'MIT',
+        body: [
+            '# Zoom out',
+            '',
+            '**Source:** [mattpocock/skills](https://github.com/mattpocock/skills/blob/main/skills/engineering/zoom-out/SKILL.md) - MIT licensed, authored by Matt Pocock. Ported verbatim into the Pugi bundle on 2026-05-26.',
+            '',
+            'I do not know this area of code well. Go up a layer of abstraction.',
+            'Give me a map of all the relevant modules and callers, using the',
+            "project's domain glossary vocabulary.",
+            '',
+        ].join('\n'),
+    },
+    {
+        name: 'diagnose',
+        description: 'Disciplined six-phase diagnosis loop for hard bugs and performance regressions: build feedback loop, reproduce, hypothesise, instrument, fix + regression-test, cleanup + post-mortem. Use when the operator reports a bug, a flake, or a perf regression.',
+        version: '1.0.0',
+        source: 'mattpocock/skills',
+        sourceUrl: 'https://github.com/mattpocock/skills/blob/main/skills/engineering/diagnose/SKILL.md',
+        license: 'MIT',
+        body: [
+            '# Diagnose',
+            '',
+            '**Source:** [mattpocock/skills](https://github.com/mattpocock/skills/blob/main/skills/engineering/diagnose/SKILL.md) - MIT licensed, authored by Matt Pocock. Ported into the Pugi bundle on 2026-05-26 with minor de-namespacing (cross-skill links rewritten, project-glossary references generalised).',
+            '',
+            'A discipline for hard bugs. Skip phases only when explicitly justified.',
+            '',
+            'When exploring the codebase, use the project domain glossary (if one',
+            'exists) to build a clear mental model of the relevant modules, and',
+            'check ADRs in the area you are touching.',
+            '',
+            '## Phase 1 - Build a feedback loop',
+            '',
+            '**This is the skill.** Everything else is mechanical. If you have a',
+            'fast, deterministic, agent-runnable pass/fail signal for the bug, you',
+            'will find the cause - bisection, hypothesis-testing, and instrumentation',
+            'all just consume that signal. If you do not have one, no amount of',
+            'staring at code will save you.',
+            '',
+            'Spend disproportionate effort here. **Be aggressive. Be creative.',
+            'Refuse to give up.**',
+            '',
+            '### Ways to construct one, in roughly this order',
+            '',
+            '1. **Failing test** at whatever seam reaches the bug - unit, integration, e2e.',
+            '2. **Curl / HTTP script** against a running dev server.',
+            '3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.',
+            '4. **Headless browser script** (Playwright / Puppeteer) - drives the UI, asserts on DOM/console/network.',
+            '5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.',
+            '6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.',
+            '7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.',
+            '8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.',
+            '9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.',
+            '10. **HITL bash script.** Last resort. If a human must click, drive _them_ with a templated loop script so the loop is still structured. Captured output feeds back to you.',
+            '',
+            'Build the right feedback loop, and the bug is 90% fixed.',
+            '',
+            '### Iterate on the loop itself',
+            '',
+            'Treat the loop as a product. Once you have _a_ loop, ask:',
+            '',
+            '- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)',
+            '- Can I make the signal sharper? (Assert on the specific symptom, not "did not crash".)',
+            '- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)',
+            '',
+            'A 30-second flaky loop is barely better than no loop. A 2-second',
+            'deterministic loop is a debugging superpower.',
+            '',
+            '### Non-deterministic bugs',
+            '',
+            'The goal is not a clean repro but a **higher reproduction rate**. Loop',
+            'the trigger 100x, parallelise, add stress, narrow timing windows, inject',
+            'sleeps. A 50% flake is debuggable; 1% is not - keep raising the rate',
+            'until it is debuggable.',
+            '',
+            '### When you genuinely cannot build a loop',
+            '',
+            'Stop and say so explicitly. List what you tried. Ask the operator for:',
+            '(a) access to whatever environment reproduces it, (b) a captured artifact',
+            '(HAR file, log dump, core dump, screen recording with timestamps), or',
+            '(c) permission to add temporary production instrumentation. Do **not**',
+            'proceed to hypothesise without a loop.',
+            '',
+            'Do not proceed to Phase 2 until you have a loop you believe in.',
+            '',
+            '## Phase 2 - Reproduce',
+            '',
+            'Run the loop. Watch the bug appear.',
+            '',
+            'Confirm:',
+            '',
+            '- The loop produces the failure mode the **operator** described - not a different failure that happens to be nearby. Wrong bug = wrong fix.',
+            '- The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).',
+            '- You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.',
+            '',
+            'Do not proceed until you reproduce the bug.',
+            '',
+            '## Phase 3 - Hypothesise',
+            '',
+            'Generate **3-5 ranked hypotheses** before testing any of them.',
+            'Single-hypothesis generation anchors on the first plausible idea.',
+            '',
+            'Each hypothesis must be **falsifiable**: state the prediction it makes.',
+            '',
+            '> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."',
+            '',
+            'If you cannot state the prediction, the hypothesis is a vibe - discard',
+            'or sharpen it.',
+            '',
+            '**Show the ranked list to the operator before testing.** They often',
+            'have domain knowledge that re-ranks instantly ("we just deployed a',
+            'change to #3"), or know hypotheses they have already ruled out. Cheap',
+            'checkpoint, big time saver. Do not block on it - proceed with your',
+            'ranking if the operator is AFK.',
+            '',
+            '## Phase 4 - Instrument',
+            '',
+            'Each probe must map to a specific prediction from Phase 3. **Change',
+            'one variable at a time.**',
+            '',
+            'Tool preference:',
+            '',
+            '1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.',
+            '2. **Targeted logs** at the boundaries that distinguish hypotheses.',
+            '3. Never "log everything and grep".',
+            '',
+            '**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`.',
+            'Cleanup at the end becomes a single grep. Untagged logs survive;',
+            'tagged logs die.',
+            '',
+            '**Perf branch.** For performance regressions, logs are usually wrong.',
+            'Instead: establish a baseline measurement (timing harness,',
+            '`performance.now()`, profiler, query plan), then bisect. Measure first,',
+            'fix second.',
+            '',
+            '## Phase 5 - Fix + regression test',
+            '',
+            'Write the regression test **before the fix** - but only if there is a',
+            '**correct seam** for it.',
+            '',
+            'A correct seam is one where the test exercises the **real bug pattern**',
+            'as it occurs at the call site. If the only available seam is too',
+            'shallow (single-caller test when the bug needs multiple callers, unit',
+            'test that cannot replicate the chain that triggered the bug), a',
+            'regression test there gives false confidence.',
+            '',
+            '**If no correct seam exists, that itself is the finding.** Note it. The',
+            'codebase architecture is preventing the bug from being locked down.',
+            'Flag this for the next phase.',
+            '',
+            'If a correct seam exists:',
+            '',
+            '1. Turn the minimised repro into a failing test at that seam.',
+            '2. Watch it fail.',
+            '3. Apply the fix.',
+            '4. Watch it pass.',
+            '5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.',
+            '',
+            '## Phase 6 - Cleanup + post-mortem',
+            '',
+            'Required before declaring done:',
+            '',
+            '- Original repro no longer reproduces (re-run the Phase 1 loop)',
+            '- Regression test passes (or absence of seam is documented)',
+            '- All `[DEBUG-...]` instrumentation removed (`grep` the prefix)',
+            '- Throwaway prototypes deleted (or moved to a clearly-marked debug location)',
+            '- The hypothesis that turned out correct is stated in the commit / PR message - so the next debugger learns',
+            '',
+            '**Then ask: what would have prevented this bug?** If the answer',
+            'involves architectural change (no good test seam, tangled callers,',
+            'hidden coupling) note the specifics for a follow-up refactor. Make the',
+            'recommendation **after** the fix is in, not before - you have more',
+            'information now than when you started.',
+            '',
+        ].join('\n'),
+    },
+    {
+        name: 'grill-me',
+        description: 'Interview the operator relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when the operator wants to stress-test a plan or says "grill me".',
+        version: '1.0.0',
+        source: 'mattpocock/skills',
+        sourceUrl: 'https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md',
+        license: 'MIT',
+        body: [
+            '# Grill me',
+            '',
+            '**Source:** [mattpocock/skills](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md) - MIT licensed, authored by Matt Pocock. Ported verbatim into the Pugi bundle on 2026-05-26 (terminology swap: "user" -> "operator" to match Pugi vocabulary).',
+            '',
+            'Interview the operator relentlessly about every aspect of this plan',
+            'until we reach a shared understanding. Walk down each branch of the',
+            'design tree, resolving dependencies between decisions one-by-one. For',
+            'each question, provide your recommended answer.',
+            '',
+            'Ask the questions one at a time.',
+            '',
+            'If a question can be answered by exploring the codebase, explore the',
+            'codebase instead.',
+            '',
+        ].join('\n'),
+    },
+];
+/**
+ * Build the canonical `SKILL.md` text for a bundled default. We hand-roll
+ * the frontmatter (instead of going through a YAML library) so the file
+ * round-trips byte-identical for the same `DEFAULT_SKILLS` entry. Stable
+ * bytes means a stable sha256: re-running `pugi init` against a clean
+ * workspace produces the same trust signature.
+ */
+function renderSkillMarkdown(spec) {
+    const frontmatter = [
+        '---',
+        `name: ${spec.name}`,
+        `description: ${spec.description}`,
+        'metadata:',
+        '  type: skill',
+        `  version: ${spec.version}`,
+        '---',
+        '',
+    ].join('\n');
+    return `${frontmatter}${spec.body}`;
+}
+/**
+ * Install every bundled default skill into the workspace `.pugi/skills/`
+ * directory. Idempotent: a skill whose target directory already exists
+ * (i.e. operator has customised it) is left untouched.
+ *
+ * Trust records are written under the workspace scope with
+ * `signedBy: pugi-bundled` so `pugi skills list` reports them as
+ * `[trusted]` without the operator having to run `pugi skills trust`
+ * manually after init.
+ */
+export async function installDefaultSkills(input) {
+    const summaries = [];
+    const scope = 'workspace';
+    for (const spec of DEFAULT_SKILLS) {
+        const targetDir = workspaceSkillDir(input.workspaceRoot, spec.name);
+        if (existsSync(targetDir)) {
+            // Idempotent: never overwrite a skill the operator has already
+            // edited. The `init` command is re-runnable by design.
+            summaries.push({ name: spec.name, status: 'skipped-existing', dir: targetDir });
+            input.log?.(`[pugi init] skill "${spec.name}" already present, leaving as-is.\n`);
+            continue;
+        }
+        // Materialise the bundled body in a tmp dir so `installSkill` can copy
+        // it through its standard payload path (includes its own SKILL.md
+        // existence check + symlink hardening via verbatimSymlinks).
+        const payloadDir = mkdtempSync(join(tmpdir(), 'pugi-default-skill-'));
+        try {
+            writeFileSync(join(payloadDir, 'SKILL.md'), renderSkillMarkdown(spec), {
+                encoding: 'utf8',
+                mode: 0o600,
+            });
+            const installedDir = installSkill({
+                payloadDir,
+                name: spec.name,
+                scope,
+                workspaceRoot: input.workspaceRoot,
+            });
+            const sha256 = hashSkillDir(installedDir);
+            await recordTrust({
+                kind: 'skill',
+                scope,
+                name: spec.name,
+                sha256,
+                // Source records the provenance for the trust ledger so a future
+                // `pugi skills info brand-voice` shows where it came from without
+                // pointing at a URL that never existed.
+                source: 'pugi-bundled-default',
+                signedBy: 'pugi-bundled',
+            });
+            summaries.push({ name: spec.name, status: 'installed', dir: installedDir });
+            input.log?.(`[pugi init] installed default skill "${spec.name}" -> ${installedDir}\n`);
+        }
+        finally {
+            rmSync(payloadDir, { recursive: true, force: true });
+        }
+    }
+    return summaries;
+}
+/**
+ * Internal helper used by tests to keep parity with the runtime. Exposed
+ * so a test fixture can write a SKILL.md byte-for-byte matching what the
+ * installer would have produced.
+ */
+export function renderDefaultSkillMarkdown(name) {
+    const spec = DEFAULT_SKILLS.find((entry) => entry.name === name);
+    if (!spec) {
+        throw new Error(`renderDefaultSkillMarkdown: no bundled default named "${name}"`);
+    }
+    return renderSkillMarkdown(spec);
+}
+//# sourceMappingURL=defaults.js.map