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

package/dist/core/compact/token-counter.js

@@ -0,0 +1,108 @@
+/**
+ * Approximate token counter for the `/compact` auto-trigger gate.
+ *
+ * Pugi does not bundle tiktoken — adding a 3 MB native module for a
+ * single heuristic check after every turn is the wrong trade. We instead
+ * use the OpenAI rule-of-thumb that 1 token ≈ 4 characters of English
+ * (≈ ¾ of a word). For mixed-language conversations the approximation
+ * skews high by 10-20% which is the safe direction — the auto-compact
+ * threshold trips slightly EARLY, never LATE. A late trigger would
+ * exceed the model's actual context window and crash the next turn.
+ *
+ * Per-model context windows are exported from `MODEL_CONTEXT_WINDOW` so
+ * the caller can resolve the budget from the active model slug without
+ * round-tripping to the server. New models added in Anvil should grow
+ * this table in lockstep; the fall-back is the conservative 32k window.
+ *
+ * Override hook: when `PUGI_TOKEN_COUNTER_OVERRIDE` is set the function
+ * parses it as a JSON object `{"text": <n>}` (number of tokens to claim
+ * per char). Used only by the integration spec — never by production.
+ */
+/** Default chars-per-token ratio for the OpenAI rule-of-thumb. */
+const DEFAULT_CHARS_PER_TOKEN = 4;
+/**
+ * Conservative fallback window when the model slug is unknown. 32k is
+ * the smallest window any current Anvil-served model exposes; using it
+ * as a fall-back guarantees we never overestimate budget and skip a
+ * compaction that should have fired.
+ */
+const FALLBACK_WINDOW = 32_000;
+/**
+ * Known context windows for models Anvil exposes today. Keep in sync
+ * with `apps/admin-api/src/pugi/model-registry.ts` — when a new model
+ * lands there, add it here. The table is intentionally narrow: only
+ * models we have actually validated.
+ */
+export const MODEL_CONTEXT_WINDOW = Object.freeze({
+    'sonnet-4.6': 200_000,
+    'sonnet-4.5': 200_000,
+    'opus-4.7': 1_000_000,
+    'opus-4.6': 200_000,
+    'haiku-4.5': 200_000,
+    'deepseek-chat-v3.1': 128_000,
+    'gpt-5': 200_000,
+    'gemini-2.5-pro': 1_000_000,
+});
+/**
+ * Estimate the token count of a single string. Returns a positive
+ * integer for non-empty input and zero for empty input. The function is
+ * pure — same input always yields the same output.
+ *
+ * The approximation is `ceil(byteLength / chars-per-token)`. We use
+ * `Buffer.byteLength` so multi-byte UTF-8 sequences count proportionally
+ * to their on-the-wire size, not their char count — this matches the
+ * tokenizer's behaviour on CJK / cyrillic / emoji where one char often
+ * eats 3-4 tokens.
+ */
+export function estimateTokens(text) {
+    if (text.length === 0)
+        return 0;
+    const ratio = readCharsPerTokenOverride() ?? DEFAULT_CHARS_PER_TOKEN;
+    const bytes = Buffer.byteLength(text, 'utf8');
+    return Math.max(1, Math.ceil(bytes / ratio));
+}
+/**
+ * Resolve the context window in tokens for the given model slug. Falls
+ * back to the conservative 32k window when the slug is unknown.
+ */
+export function contextWindowForModel(model) {
+    if (!model)
+        return FALLBACK_WINDOW;
+    const known = MODEL_CONTEXT_WINDOW[model];
+    return known ?? FALLBACK_WINDOW;
+}
+/**
+ * Sum the token estimates of an arbitrary list of strings. Convenience
+ * for the auto-trigger which has to count across N transcript turns.
+ */
+export function estimateTokensInMany(parts) {
+    let total = 0;
+    for (const part of parts) {
+        total += estimateTokens(part);
+    }
+    return total;
+}
+/**
+ * Read the test override env. Returns the parsed chars-per-token ratio
+ * when set, or undefined when absent / malformed. Never throws.
+ */
+function readCharsPerTokenOverride() {
+    const raw = process.env['PUGI_TOKEN_COUNTER_OVERRIDE'];
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object'
+            && parsed !== null
+            && typeof parsed.charsPerToken === 'number') {
+            const ratio = parsed.charsPerToken;
+            if (Number.isFinite(ratio) && ratio > 0)
+                return ratio;
+        }
+    }
+    catch {
+        /* malformed env, fall through */
+    }
+    return undefined;
+}
+//# sourceMappingURL=token-counter.js.map

package/dist/core/consensus/anvil-fanout.js

@@ -1,21 +1,21 @@
 /**
- * Anvil fan-out — `pugi review --consensus` (α6.7).
+ * Anvil fan-out — `pugi review --consensus` .
  *
  * Posts the captured diff to Anvil's consensus endpoint and consumes the
  * SSE stream that interleaves per-reviewer events (`type:"verdict"`) and
  * the final consensus event (`type:"consensus"`).
  *
- * Endpoint contract (admin-api side, ships as α6.7.1 follow-up):
+ * Endpoint contract (admin-api side, ships as follow-up):
  *
- *   POST {apiUrl}/api/pugi/review-consensus
- *   Authorization: Bearer {apiKey}
- *   Content-Type: application/json
- *   Body: { diff, context: { branch, commit, title } }
- *   Response: text/event-stream
- *     data: { reviewer: "codex"|"claude"|"deepseek", type:"started" }
- *     data: { reviewer, type:"verdict", severity:"P0|P1|P2|P3|CLEAN",
- *             rawContent:"<reviewer text>", latencyMs, error? }
- *     data: { type:"consensus", rubric_verdict, reasoning }
+ *  POST {apiUrl}/api/pugi/review-consensus
+ *  Authorization: Bearer {apiKey}
+ *  Content-Type: application/json
+ *  Body: { diff, context: { branch, commit, title } }
+ *  Response: text/event-stream
+ *    data: { reviewer: "codex"|"claude"|"deepseek", type:"started" }
+ *    data: { reviewer, type:"verdict", severity:"P0|P1|P2|P3|CLEAN",
+ *            rawContent:"<reviewer text>", latencyMs, error? }
+ *    data: { type:"consensus", rubric_verdict, reasoning }
  *
  * The CLI side does NOT trust the server's `rubric_verdict` — we recompute
  * it locally from the per-reviewer verdicts so a malformed / forged server
@@ -24,15 +24,15 @@
  *
  * Graceful degradation:
  *
- *   - 404 from runtime  → "endpoint_missing" (admin-api endpoint pending,
- *                         α6.7 ships CLI-only). Caller falls back to the
- *                         legacy `pugi review --triple --remote` flow OR
- *                         prints a "backend not deployed" notice depending
- *                         on the operator's invocation.
- *   - 401/403 / 429     → matching status with an actionable message.
- *   - 5xx / timeout     → "failed" with the truncated body.
+ *  - 404 from runtime → "endpoint_missing" (admin-api endpoint pending,
+ *                         ships CLI-only). Caller falls back to the
+ *                        legacy `pugi review --triple --remote` flow OR
+ *                        prints a "backend not deployed" notice depending
+ *                        on the operator's invocation.
+ *  - 401/403 / 429    → matching status with an actionable message.
+ *  - 5xx / timeout    → "failed" with the truncated body.
  *
- * Local-first contract (ADR-0037): this module never touches the disk,
+ * Local-first contract : this module never touches the disk,
  * never logs the diff payload, and never retries on transient errors.
  */
 /**
@@ -75,7 +75,7 @@ export async function dispatchConsensus(config, request, sink) {
             return {
                 status: 'endpoint_missing',
                 code,
-                message: 'POST /api/pugi/review-consensus not deployed on this runtime (α6.7.1 follow-up).',
+                message: 'POST /api/pugi/review-consensus not deployed on this runtime .',
             };
         }
         if (code === 401 || code === 403) {
@@ -143,11 +143,11 @@ export async function dispatchConsensus(config, request, sink) {
  * Async-iterable SSE parser. Spec'd against the
  * [HTML SSE spec](https://html.spec.whatwg.org/multipage/server-sent-events.html):
  *
- *   - Events are delimited by a blank line.
- *   - Each line is `field:value` (whitespace after `:` stripped).
- *   - Multiple `data:` lines in one event concatenate with `\n`.
- *   - We only care about `data:` payloads carrying JSON; everything
- *     else (event:, id:, retry:) is ignored.
+ *  - Events are delimited by a blank line.
+ *  - Each line is `field:value` (whitespace after `:` stripped).
+ *  - Multiple `data:` lines in one event concatenate with `\n`.
+ *  - We only care about `data:` payloads carrying JSON; everything
+ *    else (event:, id:, retry:) is ignored.
  *
  * The parser tolerates JSON-parse failures by dropping the malformed
  * event and continuing; a single bad event must not block the consensus

package/dist/core/consensus/diff-capture.js

@@ -1,15 +1,19 @@
 /**
- * Diff capture — `pugi review --consensus` (α6.7).
+ * Diff capture — `pugi review --consensus` .
  *
  * Captures the diff that the consensus fan-out will send to Anvil. Four
  * supported source kinds (in order of precedence):
  *
- *   1. `--pr <number>`    — uses `gh pr diff <num>` (gh CLI required).
- *   2. `--commit <sha>`   — diff of that commit vs its first parent.
- *   3. `--branch <name>`  — diff of HEAD vs `origin/<name>` merge-base.
- *   4. (default)          — diff of HEAD vs `origin/main` merge-base
- *                           covering BOTH committed-since-base AND
- *                           uncommitted (staged + working tree) edits.
+ *  1. `--pr <number>`   — uses `gh pr diff <num>` (gh CLI required).
+ *  2. `--commit <sha>`  — diff of that commit vs its first parent.
+ *                          When `--base <ref>` is ALSO provided, the
+ *                          diff is the range `<base>..<commit>` instead
+ *                          (mirrors `git diff base..commit` — covers the
+ *                          full PR-style payload, not just the tip).
+ *  3. `--branch <name>` — diff of HEAD vs `origin/<name>` merge-base.
+ *  4. (default)         — diff of HEAD vs `origin/main` merge-base
+ *                          covering BOTH committed-since-base AND
+ *                          uncommitted (staged + working tree) edits.
  *
  * The shape mirrors the existing `performRemoteTripleReview` flow:
  * uncommitted edits are deliberately included by computing the diff
@@ -95,6 +99,16 @@ export function captureDiff(spec) {
         return captureFromPr(cwd, spec.pr);
     }
     if (typeof spec.commit === 'string' && spec.commit.length > 0) {
+        // When `--base` is supplied alongside `--commit`, callers want the
+        // full PR-style range diff (`base..commit`), not just the tip
+        // commit's parent diff. This matches the convention used by
+        // `git diff <base>..<commit>` everywhere else in the toolchain and
+        // is the verified-correct mode for reviewing a PR head ref. Without
+        // this branch, `--base` was silently ignored when `--commit` was
+        // present — see feedback_pugi_review_use_range_diff_not_worktree.
+        if (typeof spec.baseRef === 'string' && spec.baseRef.length > 0) {
+            return captureFromRange(cwd, spec.baseRef, spec.commit);
+        }
         return captureFromCommit(cwd, spec.commit);
     }
     if (typeof spec.branch === 'string' && spec.branch.length > 0) {
@@ -114,7 +128,18 @@ function captureFromPr(cwd, pr) {
     // Fetch the PR head into a private ref so we have local objects to
     // diff against. `pull/<num>/head` is GitHub's special refspec exposed
     // to anyone with read access on the repo.
-    safeExec(cwd, 'git', ['fetch', 'origin', `pull/${pr}/head:${tempRef}`]);
+    //
+    // The leading `+` (force-update) is REQUIRED: if a prior invocation
+    // died before reaching the `finally` cleanup (SIGKILL, host crash,
+    // operator Ctrl-C inside a `try` block in a wrapping caller, hung
+    // gh CLI), the tempRef survives on disk. Without `+`, the next
+    // `fetch <pr>/head:<tempRef>` aborts with
+    //  `! [rejected] pull/N/head -> refs/pugi/consensus-pr-N (non-fast-forward)`
+    // and the entire consensus run fails for an operator who did nothing
+    // wrong. `+` semantics: replace the ref unconditionally — exactly
+    // the recovery behavior we want for a sandboxed `refs/pugi/...` slot
+    // that no human ever reads.
+    safeExec(cwd, 'git', ['fetch', 'origin', `+pull/${pr}/head:${tempRef}`]);
     try {
         // Resolve the base ref to diff against. Prefer the PR's declared
         // base; fall back to `origin/main`. We compute the merge-base so a
@@ -149,8 +174,10 @@ function captureFromPr(cwd, pr) {
             safeExec(cwd, 'git', ['update-ref', '-d', tempRef]);
         }
         catch {
-            // Swallow: a leftover ref under refs/pugi/ is harmless. The next
-            // run will overwrite it via `fetch ... :ref` anyway.
+            // Swallow: a leftover ref under refs/pugi/ is harmless. The
+            // next run force-overwrites it via `fetch +pull/<n>/head:<ref>`
+            // (note the leading `+` in the refspec above), so a stale tempRef
+            // never blocks a future invocation even if cleanup never runs.
         }
     }
 }
@@ -192,6 +219,88 @@ function captureFromCommit(cwd, commit) {
         },
     };
 }
+/**
+ * Range capture for `--commit <X> --base <Y>` — diff equivalent to
+ * `git diff <base>..<commit>`. Used when the operator names BOTH endpoints
+ * (typical PR review against a remote head SHA).
+ *
+ * Critical: this MUST be a pure read-only range diff against named refs.
+ * The previous behavior fell through to `captureFromCommit` which only
+ * showed the tip commit (`commit~1..commit`) — fine for single-commit
+ * review, wrong for multi-commit PRs. Worse, a stale fallback path was
+ * sending the working tree diff (`git diff` with no args), which caused
+ * every review on to surface identical noise from uncommitted
+ * `.gitignore` edits instead of the actual PR contents.
+ *
+ * Working tree integrity: only `git diff <ref>..<ref>` and metadata
+ * `log` / `rev-parse` / `name-rev` are used — none of these touch the
+ * index, working tree, or HEAD.
+ */
+function captureFromRange(cwd, baseRef, commit) {
+    // Resolve both endpoints up front so an unknown ref errors with a
+    // clear message before the diff invocation. `rev-parse` is read-only.
+    const fullCommit = safeExec(cwd, 'git', ['rev-parse', commit]).trim();
+    if (!fullCommit)
+        throw new Error(`Unknown commit ref: ${commit}`);
+    // Task #63 — refresh the base ref via `git fetch` BEFORE
+    // resolving. Previously a stale local `main` (last fetched days ago)
+    // would silently produce a diff containing every commit that landed
+    // upstream after the fetch, swamping the model's review с unrelated
+    // changes. The fetch is opportunistic: failures (offline, auth) are
+    // swallowed so the existing rev-parse path stays the safety net и
+    // returns the clear "Unknown base ref" error if the stale local copy
+    // is also missing.
+    //
+    // We fetch ONLY the base ref (not all refs) so the overhead is
+    // bounded — typical PR-style review payload, base = main, one ref.
+    // `--no-tags --quiet` keeps the network footprint minimal.
+    const remoteCandidate = baseRef.includes('/') ? baseRef : `origin/${baseRef}`;
+    if (remoteCandidate.startsWith('origin/')) {
+        const bareRef = remoteCandidate.slice('origin/'.length);
+        safeExecOptional(cwd, 'git', [
+            'fetch',
+            '--no-tags',
+            '--quiet',
+            'origin',
+            bareRef,
+        ]);
+    }
+    // Resolve the base: accept already-qualified refs (`origin/main`,
+    // `refs/heads/foo`) and bare branch names. If the bare name isn't
+    // locally resolvable, retry against `origin/<name>` — the common
+    // CI shape where local main is absent but the remote tracking ref is.
+    let resolvedBase = safeExecOptional(cwd, 'git', ['rev-parse', baseRef]).trim();
+    let effectiveBase = baseRef;
+    if (!resolvedBase && !baseRef.includes('/')) {
+        const remoteBase = `origin/${baseRef}`;
+        resolvedBase = safeExecOptional(cwd, 'git', ['rev-parse', remoteBase]).trim();
+        if (resolvedBase)
+            effectiveBase = remoteBase;
+    }
+    if (!resolvedBase)
+        throw new Error(`Unknown base ref: ${baseRef}`);
+    const diff = safeExec(cwd, 'git', [
+        'diff',
+        `${resolvedBase}..${fullCommit}`,
+        '--',
+        '.',
+        ...PROTECTED_PATHSPEC_EXCLUDES,
+    ]);
+    const cappedDiff = capDiff(diff);
+    const subject = safeExec(cwd, 'git', ['log', '-1', '--pretty=%s', fullCommit]).trim();
+    const branch = safeExec(cwd, 'git', ['name-rev', '--name-only', fullCommit]).trim() || 'detached';
+    const stats = computeStats(cappedDiff);
+    return {
+        diff: cappedDiff,
+        context: {
+            branch,
+            commit: shortSha(fullCommit),
+            title: subject || `commit ${shortSha(fullCommit)}`,
+            ref: `range:${effectiveBase}..${shortSha(fullCommit)}`,
+            stats,
+        },
+    };
+}
 function captureFromBranch(cwd, branch, baseRef) {
     const remoteRef = branch.includes('/') ? branch : `origin/${branch}`;
     const mergeBase = safeExec(cwd, 'git', ['merge-base', baseRef, remoteRef]).trim();
@@ -227,8 +336,8 @@ function captureFromBase(cwd, baseRef) {
     const mergeBase = safeExecOptional(cwd, 'git', ['merge-base', baseRef, 'HEAD']).trim();
     if (mergeBase) {
         // Two parts (non-overlapping):
-        //   1. Committed since base:  `<base>..HEAD`
-        //   2. Uncommitted (staged + working tree as a single union): `git diff HEAD`
+        //  1. Committed since base: `<base>..HEAD`
+        //  2. Uncommitted (staged + working tree as a single union): `git diff HEAD`
         // `git diff HEAD` already reports BOTH staged AND working-tree
         // changes relative to HEAD, so we MUST NOT add a separate
         // `--cached` invocation: doing so emits the same staged hunks

package/dist/core/consensus/rubric.js

@@ -1,5 +1,5 @@
 /**
- * Consensus rubric — `pugi review --consensus` (α6.7).
+ * Consensus rubric — `pugi review --consensus` .
  *
  * Three independent reviewers (Codex / Claude / DeepSeek) produce findings
  * tagged `[P0]` / `[P1]` / `[P2]` / `[P3]`. The rubric translates the per-
@@ -7,16 +7,16 @@
  *
  * Rubric (verbatim from /triple-review skill + admin-api OES MCP triple_review):
  *
- *   any reviewer reports [P0]              -> BLOCK
- *   two or more reviewers report [P1]      -> BLOCK   (consensus)
- *   exactly one reviewer reports [P1]      -> WARN    (asymmetric)
- *   no reviewer reports [P0] or [P1]       -> PASS    (P2/P3 only)
- *   every reviewer errored                 -> BLOCK   (no signal)
+ *  any reviewer reports [P0]             -> BLOCK
+ *  two or more reviewers report [P1]     -> BLOCK  (consensus)
+ *  exactly one reviewer reports [P1]     -> WARN   (asymmetric)
+ *  no reviewer reports [P0] or [P1]      -> PASS   (P2/P3 only)
+ *  every reviewer errored                -> BLOCK  (no signal)
  *
  * The rubric never reads model text beyond the severity markers; the
  * reviewer-side narrative is shown to the operator unchanged. Keeping the
  * verdict deterministic + LLM-free is the entire point of the gate (CEO
- * directive 2026-05-19): a model that disagrees with the rubric can be
+ * directive): a model that disagrees with the rubric can be
  * audited, a model that produces the verdict cannot.
  */
 /**
@@ -35,13 +35,13 @@ const SEVERITY_TOKEN = /\[\s*[Pp]([0-3])\s*\]/g;
  * Heuristics (intentionally permissive — different models format very
  * differently and a strict parser would drop signal):
  *
- *   1. Split the text on `[Px]` tokens, preserving the marker.
- *   2. Each marker starts a new finding. The summary is the rest of the
- *      same line (and the next line if the first is `:` or empty after
- *      stripping whitespace).
- *   3. Empty / whitespace-only summaries are dropped — a bare `[P1]`
- *      with no context cannot be acted on, and treating it as a finding
- *      would falsely trigger consensus.
+ *  1. Split the text on `[Px]` tokens, preserving the marker.
+ *  2. Each marker starts a new finding. The summary is the rest of the
+ *     same line (and the next line if the first is `:` or empty after
+ *     stripping whitespace).
+ *  3. Empty / whitespace-only summaries are dropped — a bare `[P1]`
+ *     with no context cannot be acted on, and treating it as a finding
+ *     would falsely trigger consensus.
  */
 export function parseFindings(raw) {
     if (typeof raw !== 'string' || raw.length === 0)
@@ -88,8 +88,8 @@ function extractSummary(slice) {
 /**
  * Compute the highest BLOCKING severity from a finding list. Returns
  * `null` when the reviewer is clean for gating purposes, i.e. either:
- *   - no findings at all, OR
- *   - only P2 / P3 findings (informational, non-blocking by rubric).
+ *  - no findings at all, OR
+ *  - only P2 / P3 findings (informational, non-blocking by rubric).
  *
  * `null` is the right contract for downstream tooling that gates on
  * "did this reviewer flag anything that should block ship?" - the
@@ -143,7 +143,7 @@ export function aggregate(verdicts) {
     const erroredReviewers = verdicts.filter((v) => v.errored).length;
     // Zero reviewers = zero signal. Falling through to the no-P0/no-P1
     // branch would emit a false PASS — exactly the regression flagged by
-    // Codex during PR #370 review. Treat empty input as BLOCK so the gate
+    // Codex during PR review. Treat empty input as BLOCK so the gate
     // fails closed when the backend returns no events at all (5xx that
     // somehow drained the SSE, server-side bug, dispatcher misconfig).
     if (totalReviewers === 0) {
@@ -214,11 +214,11 @@ export function aggregate(verdicts) {
 }
 /**
  * Map a rubric verdict to the conventional exit code Pugi CLI uses for
- * gates (spec α6.7):
+ * gates (spec ):
  *
- *   PASS  -> 0
- *   WARN  -> 1
- *   BLOCK -> 2
+ *  PASS -> 0
+ *  WARN -> 1
+ *  BLOCK -> 2
  *
  * The non-zero codes are distinct so a shell script can branch on the
  * exact outcome without re-parsing stdout.

package/dist/core/context/builder.js

@@ -5,11 +5,11 @@
  * Per `docs/research/pugi-cli-corpus/patterns/context-compaction.md` §6,
  * static and dynamic context live in different sections:
  *
- *   STATIC                        DYNAMIC
- *   - system instructions         - transcript turns (recent)
- *   - tool schemas (sorted)       - session memory ref
- *   - safety rules                - open task graph snapshot
- *   - PUGI.md + AGENTS.md
+ *  STATIC                       DYNAMIC
+ *  - system instructions        - transcript turns (recent)
+ *  - tool schemas (sorted)      - session memory ref
+ *  - safety rules               - open task graph snapshot
+ *  - PUGI.md + AGENTS.md
  *
  * Static blocks hash deterministically; identical session starts emit
  * identical static prefixes, hitting the model provider's prompt cache.
@@ -50,7 +50,7 @@ export async function buildContext(input) {
         bytes: Buffer.byteLength(instructionsContent, 'utf8'),
     });
     // 3. Safety rules — optional, hashed into the instructions block via
-    //    concatenation when present so consumers can read both as one.
+    //   concatenation when present so consumers can read both as one.
     if (input.safetyRules) {
         const safety = normalizeNewlines(input.safetyRules);
         blocks.push({

package/dist/core/context/compaction-events.js

@@ -3,11 +3,11 @@
  * session's events.jsonl using the shared AuditEvent discriminated union
  * in `@pugi/sdk/audit-trace.ts`.
  *
- * Until PR #307 these events were written with the ad-hoc shape
+ * Until PR these events were written with the ad-hoc shape
  * `{ id, ts, sessionId, ... }` and the comment in this header claimed
  * "we keep `session.ts` untouched and write our events through a
  * dedicated helper that bypasses the AuditEvent schema". The downside,
- * caught by Claude review on PR #307, is that every consumer that
+ * caught by Claude review on PR, is that every consumer that
  * calls `auditEventSchema.parse(line)` (cabinet UI, replay tooling,
  * `core/index-store.ts`) would throw on every compaction event, and
  * `safeParse` consumers would silently drop them.
@@ -19,12 +19,12 @@
  *
  * Events emitted:
  *
- *   compaction.started            { sessionId, tier, trigger }
- *   compaction.completed          { sessionId, tier, bytesReclaimed,
- *                                   newContextSize, artifactsCreated }
- *   compaction.skipped            { sessionId, tier, reason }
- *   compaction.invariant_violated { sessionId, invariant, evidence,
- *                                   artifactRef? }
+ *  compaction.started           { sessionId, tier, trigger }
+ *  compaction.completed         { sessionId, tier, bytesReclaimed,
+ *                                  newContextSize, artifactsCreated }
+ *  compaction.skipped           { sessionId, tier, reason }
+ *  compaction.invariant_violated { sessionId, invariant, evidence,
+ *                                  artifactRef? }
  *
  * All four are appended in mode 0o600 and respect the
  * `session.enabled` flag (no-op when `.pugi/` is absent).

package/dist/core/context/compaction.js

@@ -2,42 +2,42 @@
  * Six-tier context compaction engine for the Pugi CLI agent loop.
  *
  * Spec: `docs/research/pugi-cli-corpus/patterns/context-compaction.md`,
- * sprint slot: ADR-0056 §α5.5.
+ * sprint slot:  §.
  *
  * Tiers and triggers (selectTier rules):
  *
- *   pressure      | tier
- *   --------------+----------------------------------------------------
- *   <  0.5        | microcompact (only if redundant tool outputs)
- *   0.5  .. 0.7   | cached_microcompact
- *   0.7  .. 0.85  | reactive_summary
- *   0.85 .. 0.95  | full_compaction
- *   >  0.95       | reset (with checkpoint)
+ *  pressure     | tier
+ *  --------------+----------------------------------------------------
+ *  < 0.5       | microcompact (only if redundant tool outputs)
+ *  0.5 .. 0.7  | cached_microcompact
+ *  0.7 .. 0.85 | reactive_summary
+ *  0.85 .. 0.95 | full_compaction
+ *  > 0.95      | reset (with checkpoint)
  *
  * Tier behaviours (per pattern card §3):
  *
- *   1. microcompact         — sync; strip redundant token deltas,
- *                             collapse repeated status lines, dedupe
- *                             identical tool argument echoes; keep
- *                             tool RESULTS verbatim; target 10-20%
- *   2. cached_microcompact  — sync; replace inline tool output with
- *                             { artifactRef, size } when an artifact
- *                             with matching sha256 already exists;
- *                             target 30-50% on repetitive sessions
- *   3. reactive_summary     — async-shaped; summarize the last N=10
- *                             turns into a structured turn-summary
- *                             artifact; replace those turns with a
- *                             single turn_summary event
- *   4. session_memory       — async-shaped; distill long-running build
- *                             state into .pugi/session.db (or jsonl
- *                             fallback if SQLite not yet present)
- *   5. full_compaction      — sync, slow; rebuild from event log +
- *                             artifacts + session_memory + PUGI.md;
- *                             keep open decisions, FSM state, active
- *                             tool calls, last 3 turns verbatim
- *   6. reset                — manual or >0.95; save full state to
- *                             .pugi/checkpoints/<name>/ and start
- *                             fresh with only PUGI.md + session_memory
+ *  1. microcompact        — sync; strip redundant token deltas,
+ *                            collapse repeated status lines, dedupe
+ *                            identical tool argument echoes; keep
+ *                            tool RESULTS verbatim; target 10-20%
+ *  2. cached_microcompact — sync; replace inline tool output with
+ *                            { artifactRef, size } when an artifact
+ *                            with matching sha256 already exists;
+ *                            target 30-50% on repetitive sessions
+ *  3. reactive_summary    — async-shaped; summarize the last N=10
+ *                            turns into a structured turn-summary
+ *                            artifact; replace those turns with a
+ *                            single turn_summary event
+ *  4. session_memory      — async-shaped; distill long-running build
+ *                            state into .pugi/session.db (or jsonl
+ *                            fallback if SQLite not yet present)
+ *  5. full_compaction     — sync, slow; rebuild from event log +
+ *                            artifacts + session_memory + PUGI.md;
+ *                            keep open decisions, FSM state, active
+ *                            tool calls, last 3 turns verbatim
+ *  6. reset               — manual or >0.95; save full state to
+ *                            .pugi/checkpoints/<name>/ and start
+ *                            fresh with only PUGI.md + session_memory
  *
  * The compaction NEVER touches static blocks. Invariants enforce that
  * (static-hash-unchanged) plus secrets-never-summarize and
@@ -316,7 +316,7 @@ function tierSessionMemory(input) {
     const summaryText = JSON.stringify(memory, null, 2);
     const artifactsCreated = [];
     if (input.workspaceRoot) {
-        // SQLite migration arrives in α6.4 (per spec). Until then we append
+        // SQLite migration arrives in (per spec). Until then we append
         // a JSONL line to .pugi/session-memory.jsonl, which the next session
         // bootstraps into context.
         const path = resolve(input.workspaceRoot, '.pugi', 'session-memory.jsonl');

package/dist/core/context/index.js

@@ -1,16 +1,16 @@
 /**
- * Three-tier context model - α6.5 Phase 1 barrel.
+ * Three-tier context model - Phase 1 barrel.
  *
  * Bundles the four primitives so the REPL bootstrap can import from a
  * single path:
  *
- *   import {
- *     loadPugiIgnore,
- *     buildRepoSkeleton,
- *     renderSkeleton,
- *     WorkingSet,
- *     PugiWatcher,
- *   } from '../context/index.js';
+ *  import {
+ *    loadPugiIgnore,
+ *    buildRepoSkeleton,
+ *    renderSkeleton,
+ *    WorkingSet,
+ *    PugiWatcher,
+ *  } from '../context/index.js';
  *
  * No new logic lives here - just re-exports.
  */
@@ -18,4 +18,11 @@ export { BASELINE_IGNORE_PATTERNS, SECRET_IGNORE_PATTERNS, globalPugiIgnorePath,
 export { COLLAPSE_DIR_ENTRIES, MAX_README_LINES, MAX_SKELETON_BYTES, MAX_TREE_DEPTH, MAX_WALK_NODES, TOP_LANGUAGES, buildRepoSkeleton, detectPackageManager, languageForExtension, readGitBranch, readPackageJson, readReadme, renderSkeleton, topLanguages, } from './repo-skeleton.js';
 export { DEFAULT_WORKING_SET_CAPACITY, WorkingSet, } from './working-set.js';
 export { MAX_WATCHED_PATHS, PugiWatcher, THROTTLE_WINDOW_MS, } from './watcher.js';
+/**
+ * β5a R4+P5 — per-directory PUGI.md / AGENTS.md / CLAUDE.md / GEMINI.md
+ * traverse-up. Loads agent-context markdown at every directory between
+ * `cwd` and `workspaceRoot` (workspace root file is owned by
+ * `loadMarkdownContext` in `markdown-loader.ts` — no double-load).
+ */
+export { MAX_TRAVERSE_BYTES, MAX_TRAVERSE_PER_FILE_BYTES, MAX_TRAVERSE_DEPTH, TRAVERSE_SOURCES, loadTraversedMarkdown, } from './markdown-traverse.js';
 //# sourceMappingURL=index.js.map