@pugi/cli 0.1.0-beta.1 → 0.1.0-beta.100

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

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 {