@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/core/context/invariants.js

@@ -3,10 +3,10 @@
  * compaction result is allowed to replace the original transcript.
  *
  * Per pattern card §2:
- *   - principle 4: never summarize secrets into durable memory
- *   - principle 5: do not erase open decisions
- *   - principle 6: cache stable prompt parts (static hash must survive
- *     compaction unchanged)
+ *  - principle 4: never summarize secrets into durable memory
+ *  - principle 5: do not erase open decisions
+ *  - principle 6: cache stable prompt parts (static hash must survive
+ *    compaction unchanged)
  *
  * Plus our own physical-integrity invariant: artifact refs emitted by
  * the compaction must point to files that exist on disk and match the
@@ -26,12 +26,12 @@ import { existsSync, readFileSync } from 'node:fs';
  *
  * Coverage spans two shapes:
  *
- *   1. Cooperative `keyword = value` / `keyword: value` pairs covering
- *      api_key, access_token, password, client_secret, private_key,
- *      .env.* etc.
- *   2. Provider-specific bare tokens that travel without a keyword:
- *      Bearer JWTs, AWS access keys, GitHub PATs, Slack tokens, Stripe
- *      keys, Anthropic/OpenAI keys, and PEM private key blocks.
+ *  1. Cooperative `keyword = value` / `keyword: value` pairs covering
+ *     api_key, access_token, password, client_secret, private_key,
+ *     .env.* etc.
+ *  2. Provider-specific bare tokens that travel without a keyword:
+ *     Bearer JWTs, AWS access keys, GitHub PATs, Slack tokens, Stripe
+ *     keys, Anthropic/OpenAI keys, and PEM private key blocks.
  *
  * High-entropy base64-shaped blobs after a `:` or `=` are also caught
  * as a defence in depth — operators who exfiltrate keys via raw JSON
@@ -44,12 +44,12 @@ const SECRET_PATTERNS = [
     // 1. Keyword=value / keyword: value — the cooperative shape.
     /(api[_-]?key|access[_-]?token|id[_-]?token|password|passwd|client[_-]?secret|private[_-]?key|\.env\.[A-Z_]+|(?<![a-z])token|(?<![a-z])secret)\s*[:=]\s*\S+/gi,
     // 2. Authorization: Bearer <jwt-or-opaque-token>. JWTs are eyJ... but
-    //    we accept any non-whitespace token after Bearer so opaque bearer
-    //    tokens are also caught.
+    //   we accept any non-whitespace token after Bearer so opaque bearer
+    //   tokens are also caught.
     /Authorization\s*:\s*Bearer\s+\S+/gi,
     /\bBearer\s+(?:eyJ[A-Za-z0-9_\-.]{16,}|[A-Za-z0-9_\-.]{20,})/g,
     // 3. AWS access keys. AKIA prefix is the long-lived IAM key shape;
-    //    aws_access_key_id is the typical .aws/credentials shape.
+    //   aws_access_key_id is the typical .aws/credentials shape.
     /\bAKIA[0-9A-Z]{16}\b/g,
     /aws_access_key_id\s*[:=]\s*\S+/gi,
     /aws_secret_access_key\s*[:=]\s*\S+/gi,
@@ -65,24 +65,24 @@ const SECRET_PATTERNS = [
     // 6. Stripe live/test secret keys.
     /\bsk_(?:live|test)_[A-Za-z0-9]{24,}\b/g,
     // 7. Anthropic and OpenAI API keys. Anthropic uses sk-ant-<32+chars>;
-    //    OpenAI legacy keys are sk-<40+chars>. Both share the sk- prefix
-    //    so we keep them in their own patterns to avoid catching every
-    //    Stripe sk_ as well (Stripe uses an underscore, not a dash).
+    //   OpenAI legacy keys are sk-<40+chars>. Both share the sk- prefix
+    //   so we keep them in their own patterns to avoid catching every
+    //   Stripe sk_ as well (Stripe uses an underscore, not a dash).
     /\bsk-ant-[A-Za-z0-9_-]{32,}\b/g,
     /\bsk-(?!ant-)[A-Za-z0-9]{40,}\b/g,
     // 8. PEM-encoded private key blocks. Matches RSA / EC / DSA / OPENSSH
-    //    and the bare PRIVATE KEY variant. The body may contain real
-    //    newlines (when scanning raw transcript content) OR literal `\n`
-    //    sequences (when scanning JSON.stringify'd summaries) — both are
-    //    covered by the broad character class.
+    //   and the bare PRIVATE KEY variant. The body may contain real
+    //   newlines (when scanning raw transcript content) OR literal `\n`
+    //   sequences (when scanning JSON.stringify'd summaries) — both are
+    //   covered by the broad character class.
     /-----BEGIN (?:RSA |EC |DSA |OPENSSH |ENCRYPTED |)PRIVATE KEY-----[\s\S\\n]*?-----END (?:RSA |EC |DSA |OPENSSH |ENCRYPTED |)PRIVATE KEY-----/g,
     // 8b. Lone PEM begin/end markers — survive even when the body is too
-    //     long to capture or escaped beyond recognition.
+    //    long to capture or escaped beyond recognition.
     /-----BEGIN (?:RSA |EC |DSA |OPENSSH |ENCRYPTED |)PRIVATE KEY-----/g,
     // 9. High-entropy base64-shaped blobs after a colon or equals. 40+ chars
-    //    of the base64url alphabet is well above the ~6 bytes/char threshold
-    //    where false positives become rare. Word-boundary anchored so prose
-    //    is not swept up.
+    //   of the base64url alphabet is well above the ~6 bytes/char threshold
+    //   where false positives become rare. Word-boundary anchored so prose
+    //   is not swept up.
     /[:=]\s*"?([A-Za-z0-9_\-+/]{40,}={0,2})"?(?=\s|,|\}|$)/g,
 ];
 /**
@@ -97,23 +97,23 @@ const DECISION_RX = /^\s*(?:DECISION|OPEN|BLOCKED|REJECTED):/;
  * violation must cause the engine to drop the compaction result.
  *
  * Inputs:
- *   - `before`: the compaction input snapshot the caller computed
- *   - `after`: the compaction result the tier function produced
- *   - `summaryText`: the concrete prose / structured summary the
- *     compaction wrote into the dynamic block (or empty string for
- *     microcompact tiers that only reshape existing content)
- *   - `staticHashBefore` / `staticHashAfter`: instructions+toolSchema
- *     hash from the context builder, captured before and after the
- *     compaction (compaction must never touch static blocks)
+ *  - `before`: the compaction input snapshot the caller computed
+ *  - `after`: the compaction result the tier function produced
+ *  - `summaryText`: the concrete prose / structured summary the
+ *    compaction wrote into the dynamic block (or empty string for
+ *    microcompact tiers that only reshape existing content)
+ *  - `staticHashBefore` / `staticHashAfter`: instructions+toolSchema
+ *    hash from the context builder, captured before and after the
+ *    compaction (compaction must never touch static blocks)
  */
 export function checkInvariants(args) {
     const { before, after, summaryText } = args;
     const violations = [];
     // 1. secrets-never-summarize — sweep the post-compaction summary text.
-    //    `summaryText` is what gets written to .pugi/session.db / replaces
-    //    the transcript turns. We grep there, not the input, because the
-    //    pre-compaction transcript is the operator's own data; we only
-    //    police what we are about to make durable.
+    //   `summaryText` is what gets written to .pugi/session.db / replaces
+    //   the transcript turns. We grep there, not the input, because the
+    //   pre-compaction transcript is the operator's own data; we only
+    //   police what we are about to make durable.
     if (summaryText.length > 0) {
         const firstMatch = findFirstSecret(summaryText);
         if (firstMatch !== null) {
@@ -124,10 +124,10 @@ export function checkInvariants(args) {
         }
     }
     // 2. open-decisions-preserved — every DECISION/OPEN/BLOCKED/REJECTED
-    //    line in the pre-compaction transcript must appear verbatim in
-    //    the post-compaction summary OR remain in the after-state's
-    //    `decisionsPreserved`. The compaction result surfaces the latter
-    //    so we cross-check both.
+    //   line in the pre-compaction transcript must appear verbatim in
+    //   the post-compaction summary OR remain in the after-state's
+    //   `decisionsPreserved`. The compaction result surfaces the latter
+    //   so we cross-check both.
     const beforeDecisions = [];
     for (const turn of before.transcript) {
         for (const line of turn.content.split('\n')) {
@@ -147,17 +147,17 @@ export function checkInvariants(args) {
         }
     }
     // 3. artifact-refs-resolvable — every artifact ref must point to a
-    //    file under .pugi/artifacts/ that exists and SHA256-matches the
-    //    ref. We compute the hash physically rather than trusting the
-    //    bookkeeping; if the disk write was corrupted, we want to know
-    //    before we promote the compaction.
+    //   file under .pugi/artifacts/ that exists and SHA256-matches the
+    //   ref. We compute the hash physically rather than trusting the
+    //   bookkeeping; if the disk write was corrupted, we want to know
+    //   before we promote the compaction.
     for (const ref of after.artifactsCreated) {
         const violation = verifyArtifact(ref);
         if (violation)
             violations.push(violation);
     }
     // 4. static-hash-unchanged — instructions and tool schema hashes
-    //    must be byte-identical before and after compaction.
+    //   must be byte-identical before and after compaction.
     if (args.staticHashBefore.instructionsHash !== args.staticHashAfter.instructionsHash) {
         violations.push({
             invariant: 'static-hash-unchanged',
@@ -219,16 +219,16 @@ function findFirstSecret(summaryText) {
 function redact(input) {
     // Two shapes to handle:
     //
-    //   1. Keyword=value / keyword: value — keep the keyword visible so
-    //      the operator can see which secret leaked, but mask the value.
-    //   2. Bare token (Bearer ..., AKIA..., PEM block, etc.) — keep the
-    //      first 2 and last 2 chars of the token; mask the middle. PEM
-    //      blocks are dropped entirely except for the BEGIN line.
+    //  1. Keyword=value / keyword: value — keep the keyword visible so
+    //     the operator can see which secret leaked, but mask the value.
+    //  2. Bare token (Bearer ..., AKIA..., PEM block, etc.) — keep the
+    //     first 2 and last 2 chars of the token; mask the middle. PEM
+    //     blocks are dropped entirely except for the BEGIN line.
     if (input.startsWith('-----BEGIN')) {
         // PEM blocks may arrive with real newlines, with escaped `\n`
         // (JSON-stringified payloads), or with `\r\n` (Windows). Cut on
         // the BEGIN header end so the body never leaks.
-        // Codex P1 retro 2026-05-24: matching on `\n` only let the
+        // Codex P1 retro: matching on `\n` only let the
         // escaped-newline case dump the full PEM into invariant evidence.
         const headerEnd = input.search(/-----(\r?\n|\\r?\\n|$)/);
         const firstLine = headerEnd > 0 ? input.slice(0, headerEnd + 5) : '-----BEGIN PRIVATE KEY-----';

package/dist/core/context/markdown-loader.js

@@ -6,11 +6,11 @@
  * context block. They are loaded once per session, deterministically, with
  * the following safety budget:
  *
- *   - max import depth: 3 (deeper chains are skipped, not fatal)
- *   - max total loaded bytes: 64 KB across PUGI.md + AGENTS.md + all imports
- *   - HTML comment stripping (`<!-- ... -->`) — comments often carry stale
- *     annotations that bias the model long after they go out of date
- *   - workspace containment — `@import ../../../etc/passwd` is rejected
+ *  - max import depth: 3 (deeper chains are skipped, not fatal)
+ *  - max total loaded bytes: 64 KB across PUGI.md + AGENTS.md + all imports
+ *  - HTML comment stripping (`<!-- ... -->`) — comments often carry stale
+ *    annotations that bias the model long after they go out of date
+ *  - workspace containment — `@import ../../../etc/passwd` is rejected
  *
  * Missing files are not errors. If `PUGI.md` is absent we simply skip it
  * and report nothing; the engine builds its context from instructions +
@@ -26,22 +26,40 @@ export const MAX_TOTAL_BYTES = 64 * 1024;
 /**
  * Source filenames we look for at the workspace root. Order matters:
  * PUGI.md is the canonical Pugi-native file; AGENTS.md is the
- * cross-CLI compatibility shim used by other agentic CLIs.
+ * cross-CLI compatibility shim used by other agentic CLIs; CLAUDE.md
+ * is the the upstream tool drop-in compat shim —
+ * operators migrating from CC routinely keep a workspace-root
+ * `CLAUDE.md` documenting project conventions, and we pick it up so
+ * Pugi sees the same ambient guidance without a manual rename.
+ *
+ * All three files are loaded when present (no "first one wins"
+ * dropdown). Each entry is HTML-stripped + @import-expanded + capped
+ * against the shared 64 KB budget. Pugi's precedence convention is
+ * "shown last = highest specificity"; PUGI.md / AGENTS.md / CLAUDE.md
+ * each have a stable position in this list so the context builder's
+ * render order is deterministic.
  */
-export const MARKDOWN_SOURCES = ['PUGI.md', 'AGENTS.md'];
+export const MARKDOWN_SOURCES = ['PUGI.md', 'AGENTS.md', 'CLAUDE.md'];
 /**
  * Load PUGI.md + AGENTS.md from `workspaceRoot`. Either or both may be
  * absent. Returns the combined load result with per-file detail plus a
  * flat list of warnings (best-effort: a missing file is a warning, not
  * an error).
  */
-export async function loadMarkdownContext(workspaceRoot) {
+export async function loadMarkdownContext(workspaceRoot, env = process.env) {
     const warnings = [];
     const loaded = [];
     let budgetRemaining = MAX_TOTAL_BYTES;
     const visited = new Set();
     const absRoot = resolve(workspaceRoot);
-    for (const source of MARKDOWN_SOURCES) {
+    // #20 : allow operators to opt OUT of CLAUDE.md
+    // ingest via `PUGI_CC_COMPAT_DISABLE=1`. PUGI.md / AGENTS.md remain
+    // loaded — they are Pugi-native surfaces, not shims.
+    const ccCompatDisabled = env.PUGI_CC_COMPAT_DISABLE === '1';
+    const activeSources = ccCompatDisabled
+        ? MARKDOWN_SOURCES.filter((s) => s !== 'CLAUDE.md')
+        : MARKDOWN_SOURCES;
+    for (const source of activeSources) {
         const candidate = resolve(absRoot, source);
         if (!existsSync(candidate)) {
             warnings.push({
@@ -200,7 +218,7 @@ function expandFile(input) {
         // readFileSync then follows the symlink and inlines arbitrary
         // contents into the static context. Realpath the target AND the
         // workspace root so the comparison runs against the physical paths.
-        // Mirrors the apps/pugi-cli/src/core/trust.ts pattern from PR #305.
+        // Mirrors the apps/pugi-cli/src/core/trust.ts pattern from PR.
         let realTarget;
         let realRoot;
         try {

package/dist/core/context/markdown-traverse.js

@@ -0,0 +1,255 @@
+/**
+ * Per-directory PUGI.md / AGENTS.md / CLAUDE.md / GEMINI.md traverse-up
+ * loader — β5a R4+P5.
+ *
+ * the upstream tool, peer CLI, and Gemini CLI all support a "walk up from
+ * cwd to the workspace root, pick up agent-context markdown at every
+ * level" pattern. Without this, a `pugi explain` invoked from
+ * `apps/admin-api/` cannot see project-local conventions encoded in
+ * `apps/admin-api/PUGI.md` (or the cross-CLI shim files) — the
+ * existing `loadMarkdownContext` only reads files at `workspaceRoot`.
+ *
+ * The β5a quality gate (≥80% win-rate vs the upstream tool per CEO)
+ * surfaces this gap repeatedly: monorepo-local conventions (NestJS
+ * controller style, Prisma migration name format, cabinet brand voice
+ * gates) live in per-app context files, and Pugi was blind to them
+ * pre-β5a.
+ *
+ * Contract:
+ *
+ *  - Walk from `cwd` upward until we reach `workspaceRoot` OR cross
+ *    the filesystem boundary. The workspace root file itself is
+ *    loaded by the legacy `loadMarkdownContext` so we do NOT include
+ *    it here (no double-load, no double-budget-charge).
+ *
+ *  - At each intermediate directory, look for the four canonical
+ *    filenames: `PUGI.md` (native), `AGENTS.md` (cross-CLI shim),
+ *    `CLAUDE.md` (the upstream tool compat), `GEMINI.md` (Gemini CLI compat).
+ *
+ *  - HTML comments stripped, identical to the legacy loader.
+ *
+ *  - `@import` expansion is intentionally NOT performed here — the
+ *    per-dir surface is "drop a small file with the local
+ *    conventions"; deep @import chains belong at workspace root.
+ *    Keeping this surface flat means the per-dir budget cannot be
+ *    blown out by a runaway @import in an unrelated subtree.
+ *
+ *  - Aggregate budget: `MAX_TRAVERSE_BYTES` across ALL files found
+ *    in the walk. When exhausted, remaining files are skipped with
+ *    a `budget_exhausted` warning. Default 32 KB — half the
+ *    workspace-root budget, because per-dir files are meant to be
+ *    terse delta conventions, not full project briefs.
+ *
+ *  - The walk is bounded: `MAX_TRAVERSE_DEPTH` levels above
+ *    workspaceRoot are NEVER traversed (defense against being
+ *    invoked from a malicious cwd outside the workspace; in
+ *    practice cwd is always inside workspaceRoot but the symlink
+ *    case demands belt + suspenders).
+ *
+ *  - Order returned: shallowest-first (workspace root would be
+ *    first if included, then each level closer to cwd). Closest-
+ *    to-cwd files are the most specific and the context builder
+ *    emits them LAST so the model treats them as the highest-
+ *    priority conventions.
+ *
+ * This module is pure: no logging, no network, no fs writes. Filesystem
+ * reads only.
+ */
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { stripHtmlComments } from './markdown-loader.js';
+/**
+ * Per-traverse total byte cap. Half the workspace-root budget — these
+ * files are meant to be terse "in this subdir, do X". 32 KB still fits
+ * ~8000 words of guidance.
+ */
+export const MAX_TRAVERSE_BYTES = 32 * 1024;
+/**
+ * Per-file byte cap. A single per-dir file should never dominate; the
+ * 8 KB cap keeps any one level honest. Files larger than this are
+ * loaded up to the cap and flagged truncated.
+ */
+export const MAX_TRAVERSE_PER_FILE_BYTES = 8 * 1024;
+/**
+ * Maximum number of parent directories above workspaceRoot we will
+ * traverse. Zero in normal operation — cwd is always inside the
+ * workspace; the cap exists so a misconfigured invocation never
+ * walks the whole filesystem looking for AGENTS.md.
+ */
+export const MAX_TRAVERSE_DEPTH = 0;
+/**
+ * Filenames we look for at every level of the walk. The order here
+ * also defines the per-directory load order: PUGI.md first (highest
+ * trust), then cross-CLI compat shims. When the same directory has
+ * multiple files (e.g. both PUGI.md AND CLAUDE.md), all are loaded
+ * — operators sometimes keep both during a tool migration.
+ */
+export const TRAVERSE_SOURCES = ['PUGI.md', 'AGENTS.md', 'CLAUDE.md', 'GEMINI.md'];
+/**
+ * Walk from `opts.cwd` upward toward `opts.workspaceRoot`, loading
+ * every PUGI.md / AGENTS.md / CLAUDE.md / GEMINI.md we encounter at
+ * intermediate levels. The workspace root itself is NOT loaded here
+ * — `loadMarkdownContext(workspaceRoot)` owns that file.
+ *
+ * Returned `loaded` is sorted shallowest-first (closest-to-root) so
+ * the caller can emit per-dir context in increasing specificity.
+ *
+ * Safety properties (proven by spec):
+ *
+ *  - Never reads outside the workspace tree (symlinks resolved via
+ *    realpathSync; off-tree symlinks rejected as
+ *    `import_escapes_workspace`).
+ *  - Never reads more than `MAX_TRAVERSE_BYTES` total or more than
+ *    `MAX_TRAVERSE_PER_FILE_BYTES` per file.
+ *  - Never walks above the workspace root.
+ *  - Never visits the workspace root itself (single source of truth
+ *    for workspace-level docs stays with `loadMarkdownContext`).
+ */
+export async function loadTraversedMarkdown(opts) {
+    const warnings = [];
+    const loaded = [];
+    let budgetRemaining = MAX_TRAVERSE_BYTES;
+    let absRoot;
+    let absCwd;
+    try {
+        absRoot = realpathSync(resolve(opts.workspaceRoot));
+        absCwd = realpathSync(resolve(opts.cwd));
+    }
+    catch (error) {
+        warnings.push({
+            kind: 'read_error',
+            message: `realpath failed for traverse anchor: ${error.message}`,
+        });
+        return { loaded, warnings, totalBytes: 0 };
+    }
+    // Containment guard: if cwd is not inside workspaceRoot, refuse
+    // to walk. Returning a clean empty result keeps the engine happy
+    // and surfaces nothing about the off-tree cwd to the model.
+    const relCwd = relative(absRoot, absCwd);
+    if (relCwd.startsWith('..') || isAbsolute(relCwd)) {
+        warnings.push({
+            kind: 'import_escapes_workspace',
+            message: `cwd is outside workspaceRoot; per-dir traverse skipped (cwd=${absCwd}, root=${absRoot})`,
+            path: absCwd,
+        });
+        return { loaded, warnings, totalBytes: 0 };
+    }
+    // Collect the walk: every directory from cwd UP TO (but not
+    // including) workspaceRoot.
+    const dirsToVisit = [];
+    let current = absCwd;
+    while (current !== absRoot) {
+        dirsToVisit.push(current);
+        const parent = dirname(current);
+        if (parent === current)
+            break; // hit filesystem root before workspaceRoot — defensive
+        current = parent;
+        if (dirsToVisit.length > 64)
+            break; // pathological depth, refuse
+    }
+    // Walk shallowest-first so we charge the budget in the order
+    // that matches what we return.
+    dirsToVisit.reverse();
+    for (const dir of dirsToVisit) {
+        if (budgetRemaining <= 0) {
+            warnings.push({
+                kind: 'budget_exhausted',
+                message: `per-dir traverse budget exhausted before reaching ${dir}`,
+                path: dir,
+            });
+            break;
+        }
+        for (const source of TRAVERSE_SOURCES) {
+            const candidate = resolve(dir, source);
+            if (!existsSync(candidate))
+                continue;
+            // Symlink guard: same realpath check as the workspace-root
+            // loader. A symlink inside the workspace that points outside
+            // the workspace must NOT be inlined.
+            let realCandidate;
+            try {
+                realCandidate = realpathSync(candidate);
+            }
+            catch (error) {
+                warnings.push({
+                    kind: 'read_error',
+                    message: `realpath failed for ${candidate}: ${error.message}`,
+                    path: candidate,
+                });
+                continue;
+            }
+            const realRel = relative(absRoot, realCandidate);
+            if (realRel.startsWith('..') || isAbsolute(realRel)) {
+                warnings.push({
+                    kind: 'import_escapes_workspace',
+                    message: `traverse file escapes workspace via symlink: ${candidate} -> ${realCandidate}`,
+                    path: candidate,
+                });
+                continue;
+            }
+            let raw;
+            let rawBytes;
+            try {
+                rawBytes = statSync(candidate).size;
+                raw = readFileSync(candidate, 'utf8');
+            }
+            catch (error) {
+                warnings.push({
+                    kind: 'read_error',
+                    message: `could not read ${candidate}: ${error.message}`,
+                    path: candidate,
+                });
+                continue;
+            }
+            const stripped = stripHtmlComments(raw);
+            // Per-file cap first, then global budget.
+            const perFileCap = Math.min(MAX_TRAVERSE_PER_FILE_BYTES, budgetRemaining);
+            let content = stripped;
+            let truncated = false;
+            let contentBytes = Buffer.byteLength(content, 'utf8');
+            if (contentBytes > perFileCap) {
+                // Codepoint-safe slice: convert byte cap to char cap by
+                // taking min(byte cap, char-length-up-to-cap). We accept
+                // mild over-trim for safety.
+                content = content.slice(0, perFileCap);
+                truncated = true;
+                contentBytes = Buffer.byteLength(content, 'utf8');
+            }
+            const distance = distanceSegments(absCwd, dir);
+            loaded.push({
+                source,
+                resolvedPath: candidate,
+                dir,
+                distanceFromCwd: distance,
+                rawBytes,
+                loadedBytes: contentBytes,
+                truncated,
+                content,
+            });
+            budgetRemaining -= contentBytes;
+            if (budgetRemaining <= 0)
+                break;
+        }
+    }
+    return {
+        loaded,
+        warnings,
+        totalBytes: MAX_TRAVERSE_BYTES - budgetRemaining,
+    };
+}
+/**
+ * How many path segments separate `from` and `to`. Both must be
+ * absolute. `to` is assumed to be an ancestor of (or equal to)
+ * `from`; if not, returns -1 so callers can ignore the file.
+ */
+function distanceSegments(from, to) {
+    if (from === to)
+        return 0;
+    const rel = relative(to, from);
+    if (rel.startsWith('..') || isAbsolute(rel))
+        return -1;
+    if (rel.length === 0)
+        return 0;
+    return rel.split(sep).length;
+}
+//# sourceMappingURL=markdown-traverse.js.map

package/dist/core/context/pugiignore.js

@@ -1,5 +1,5 @@
 /**
- * `.pugiignore` parser - α6.5 Phase 1 (three-tier context).
+ * `.pugiignore` parser - Phase 1 (three-tier context).
  *
  * The CLI walks the workspace to build a repo skeleton and to feed the
  * chokidar watcher. Both passes need a single source of truth for which
@@ -9,32 +9,32 @@
  *
  * Design choices:
  *
- *   1. We layer four sources, last-write-wins per the .gitignore spec:
- *      (a) Built-in DEFAULT_IGNORE_PATTERNS - secret / binary / build
- *          paths every workspace should drop.
- *      (b) `~/.pugi/global.pugiignore` - operator-global overrides.
- *      (c) Repo `.gitignore` (when present) - so we don't re-walk
- *          node_modules / dist / etc.
- *      (d) Repo `.pugiignore` - workspace-local extensions.
+ *  1. We layer four sources, last-write-wins per the .gitignore spec:
+ *     (a) Built-in DEFAULT_IGNORE_PATTERNS - secret / binary / build
+ *         paths every workspace should drop.
+ *     (b) `~/.pugi/global.pugiignore` - operator-global overrides.
+ *     (c) Repo `.gitignore` (when present) - so we don't re-walk
+ *         node_modules / dist / etc.
+ *     (d) Repo `.pugiignore` - workspace-local extensions.
  *
- *   2. The `ignore` npm package handles negation (`!path`) and nested
- *      directories correctly. Rolling a minimal glob matcher is doable
- *      but the test surface for gitignore semantics (esp. negation +
- *      ancestor matching) is wide enough that pulling the audited
- *      library is the safer call. It is already in the workspace via
- *      transitive deps; we add it as an explicit pugi-cli dep.
+ *  2. The `ignore` npm package handles negation (`!path`) and nested
+ *     directories correctly. Rolling a minimal glob matcher is doable
+ *     but the test surface for gitignore semantics (esp. negation +
+ *     ancestor matching) is wide enough that pulling the audited
+ *     library is the safer call. It is already in the workspace via
+ *     transitive deps; we add it as an explicit pugi-cli dep.
  *
- *   3. Privacy is defense-in-depth: even if the operator deletes the
- *      built-in defaults from their `.pugiignore`, we re-add the
- *      secret patterns at the END of the chain so a typo in user
- *      config cannot expose `.env` / `*.pem` / `*.key`. The user can
- *      explicitly negate (`!.env.example`) but cannot wipe the
- *      defense.
+ *  3. Privacy is defense-in-depth: even if the operator deletes the
+ *     built-in defaults from their `.pugiignore`, we re-add the
+ *     secret patterns at the END of the chain so a typo in user
+ *     config cannot expose `.env` / `*.pem` / `*.key`. The user can
+ *     explicitly negate (`!.env.example`) but cannot wipe the
+ *     defense.
  *
- *   4. Paths are normalised to forward slashes (the `ignore` package
- *      requires POSIX-style separators even on Windows) and stripped
- *      of any leading workspace root so `isIgnored` answers in
- *      repo-relative terms.
+ *  4. Paths are normalised to forward slashes (the `ignore` package
+ *     requires POSIX-style separators even on Windows) and stripped
+ *     of any leading workspace root so `isIgnored` answers in
+ *     repo-relative terms.
  *
  * The API surface is minimal: `loadPugiIgnore(cwd)` returns a
  * `PugiIgnore` matcher with `isIgnored(absPath): boolean`. The matcher
@@ -59,19 +59,19 @@ const ignoreFactory = ignoreModule.default
  * Built-in patterns shipped with every Pugi workspace. The list is a
  * conservative union of three categories:
  *
- *   - **Secrets** (defense in depth): `.env*`, `*.pem`, `*.key`,
- *     `secrets/**`, `.netrc`, `id_rsa*`, `*.secret`, `credentials*`.
- *     These are re-applied at the END of the chain so user config
- *     cannot accidentally expose them.
+ *  - **Secrets** (defense in depth): `.env*`, `*.pem`, `*.key`,
+ *    `secrets/**`, `.netrc`, `id_rsa*`, `*.secret`, `credentials*`.
+ *    These are re-applied at the END of the chain so user config
+ *    cannot accidentally expose them.
  *
- *   - **Build outputs / caches**: `node_modules/`, `dist/`, `build/`,
- *     `.next/`, `.nuxt/`, `.svelte-kit/`, `coverage/`, `.nx/`, `.cache/`,
- *     `.turbo/`, `.parcel-cache/`, `out/`, `.output/`, `*.tsbuildinfo`.
+ *  - **Build outputs / caches**: `node_modules/`, `dist/`, `build/`,
+ *    `.next/`, `.nuxt/`, `.svelte-kit/`, `coverage/`, `.nx/`, `.cache/`,
+ *    `.turbo/`, `.parcel-cache/`, `out/`, `.output/`, `*.tsbuildinfo`.
  *
- *   - **Large binaries / data**: lockfiles (`*.lock`, `*-lock.json`,
- *     `*-lock.yaml`), images (`*.png`, `*.jpg`, `*.jpeg`, `*.gif`,
- *     `*.ico`), PDFs, videos, archives (`*.zip`, `*.tar`, `*.gz`),
- *     DB dumps (`*.sql`, `*.dump`), logs.
+ *  - **Large binaries / data**: lockfiles (`*.lock`, `*-lock.json`,
+ *    `*-lock.yaml`), images (`*.png`, `*.jpg`, `*.jpeg`, `*.gif`,
+ *    `*.ico`), PDFs, videos, archives (`*.zip`, `*.tar`, `*.gz`),
+ *    DB dumps (`*.sql`, `*.dump`), logs.
  *
  * The split between baseline patterns (applied first) and secret
  * patterns (applied last) matters: a user `.pugiignore` can `!`-negate
@@ -173,7 +173,7 @@ export const SECRET_IGNORE_PATTERNS = Object.freeze([
     // used by Java + .NET tooling. Both can carry private keys when
     // bundled (PKCS#7 / PKCS#12) and the file extension alone does not
     // tell us whether the bundle includes a key. Treat as secrets by
-    // default. triple-review P1 (PR #380).
+    // default. triple-review P1 (PR).
     '*.cer',
     '*.der',
     '*.p12',
@@ -216,11 +216,11 @@ export function workspaceGitIgnorePath(cwd) {
  * is built in this exact order so later layers override earlier ones,
  * with the trailing secret block as the inviolable backstop:
  *
- *   1. BASELINE_IGNORE_PATTERNS  (built-in defaults)
- *   2. ~/.pugi/global.pugiignore (operator global, optional)
- *   3. <cwd>/.gitignore          (workspace, optional)
- *   4. <cwd>/.pugiignore         (workspace, optional)
- *   5. SECRET_IGNORE_PATTERNS    (defense-in-depth backstop)
+ *  1. BASELINE_IGNORE_PATTERNS (built-in defaults)
+ *  2. ~/.pugi/global.pugiignore (operator global, optional)
+ *  3. <cwd>/.gitignore         (workspace, optional)
+ *  4. <cwd>/.pugiignore        (workspace, optional)
+ *  5. SECRET_IGNORE_PATTERNS   (defense-in-depth backstop)
  *
  * Any FS error reading optional files is swallowed - workspace
  * context is best-effort and must never block the REPL bootstrap.