bitacora-cli 1.0.0 → 1.1.1

package/README.md

@@ -14,25 +14,8 @@ Show help:
 bitacora --help
 ```
 
-Typical flow:
-
-```bash
-# init bitacora files structure and add SKILL
-bitacora init
-
-# ask your agent to complete bitacora
-# whith your project info. You can
-# complete bitacora by yourself if you wish.
-codex "$bitacora read and fill bitacora template with this project info"
-
-# plan some tasks
-codex (planner )"$bitacora plan the unit test for this repo and add separated tasks to bitacora"
-
-# use another agent
-codex "$bitacora implement the 003 track"
-```
-
 Use `--root <path>` on any command to target a different project directory.
+Command examples are available in `examples/cli-workflows.md`.
 
 ## What Each Bitacora File Stores
 
@@ -43,42 +26,58 @@ Use `--root <path>` on any command to target a different project directory.
 - `bitacora/ux-style-guide.md`: visual tokens and UX interaction rules.
 - `bitacora/tracks/tracks.md`: canonical track registry, current snapshot, and handoff summary.
 - `bitacora/tracks/TRACK-*/track.md`: per-track plan, tasks, decisions, and timestamped log.
+- `bitacora/history/TRACK-*.md`: archived full track detail after compaction (read on demand).
+- `bitacora/history/tracks-*.md`: archived snapshots of `tracks/tracks.md`.
 - `.agents/skills/bitacora/SKILL.md`: instructions agents follow to keep the memory system updated.
 
-## How Agents Read and Update Bitacora
+## Compaction Model (v1.1.0)
 
-Recommended memory read order for agents:
+Bitacora now supports compacting finished tracks to reduce active context size and token usage.
 
-1. `bitacora/index.md`
-2. `bitacora/product.md`
-3. `bitacora/tech-stack.md`
-4. `bitacora/workflow.md`
-5. `bitacora/ux-style-guide.md`
-6. `bitacora/tracks/tracks.md`
-7. Active files in `bitacora/tracks/TRACK-*/track.md`
+### How it works
 
-Typical agent write operations:
+1. Keep full details while implementing.
+2. When a track is fully done, compact it.
+3. Bitacora writes a short version in `tracks/TRACK-xxx/track.md`.
+4. Full detail is archived in `bitacora/history/TRACK-xxx.md`.
+5. `bitacora/tracks/tracks.md` is regenerated in compact form.
 
-- `bitacora new-track`: create a new work unit.
-- `bitacora log --track-id ... --message ...`: append progress updates.
-- direct updates to `bitacora/tracks/TRACK-*/track.md`: tasks, decisions, execution details.
-- direct updates to `bitacora/tracks/tracks.md`: canonical project status and next action.
-- `bitacora validate` and `bitacora rebuild-state`: ensure memory remains valid and deterministic.
+### Completion gates for `--complete`
 
-## Agent Skill Integration
+`bitacora compact --complete` only succeeds when:
 
-When you run `bitacora init`, Bitacora also creates an agent skill at:
+- `# Tasks` has no unchecked checklist item (`- [ ]`).
+- `# Log` contains at least one verification line with `TEST:`.
 
-```text
-.agents/skills/bitacora/SKILL.md
-```
+If gates fail, command exits with code `1` and no compaction is applied.
 
-This skill guides agents to keep memory updated during implementation:
+## New in v1.1.1: Skill-only update
 
-- Read project memory before coding.
-- Create and update tracks as work progresses.
-- Log decisions and progress.
-- Keep a consistent handoff summary in `bitacora/tracks/tracks.md`.
+Use `bitacora skill` to install/update only `.agents/skills/bitacora/SKILL.md` and `skills-lock.json` without recreating `bitacora/` context files.
+
+## Typical flow
+
+```bash
+# 1) bootstrap
+bitacora init
+
+# 2) update skill only (after CLI upgrades)
+bitacora skill
+
+# 3) create work
+bitacora new-track
+
+# 4) append progress
+bitacora log --track-id TRACK-001 --message "implemented parser"
+bitacora log --track-id TRACK-001 --message "TEST: npm test -- --run tests/core/parser.test.ts -> pass"
+
+# 5) compact when fully completed
+bitacora compact --track-id TRACK-001 --complete
+
+# 6) inspect archive only when needed
+bitacora history --track-id TRACK-001
+bitacora history --track-id TRACK-001 --show
+```
 
 ## Commands
 
@@ -89,6 +88,14 @@ Creates the `bitacora/` memory structure in the project root.
 - `--force`: recreates memory files if they already exist.
 - `--root <path>`: sets the project root (default: current directory).
 
+### `bitacora skill [--root <path>]`
+
+Installs or updates only the Bitacora local agent skill and its lock entry.
+
+- Updates `.agents/skills/bitacora/SKILL.md`.
+- Updates `skills-lock.json` entry for `bitacora` while preserving other skills.
+- Does not recreate or modify `bitacora/` project memory files.
+
 ### `bitacora new-track [trackId] [--status <status>] [--priority <priority>] [--root <path>]`
 
 Creates a new track file. If `trackId` is omitted, Bitacora picks the next sequential ID.
@@ -106,6 +113,56 @@ Appends a timestamped log entry to an existing track.
 - `--message <text>`: required log message.
 - `--root <path>`: sets the project root.
 
+### `bitacora compact [--track-id <trackId> | --all] [--complete] [--dry-run] [--root <path>]`
+
+Compacts tracks by summarizing content and archiving full detail.
+
+- `--track-id <trackId>`: compact a specific track.
+- `--all`: compact all eligible tracks.
+- `--complete`: mark target tracks as completed (requires completion gates).
+- `--dry-run`: report estimated byte/token savings without writing files.
+- `--root <path>`: sets the project root.
+- `--complete` gates:
+  - `# Tasks` must not contain unchecked items (`- [ ]`).
+  - `# Log` must include at least one `TEST:` line.
+- rewrite/archive model:
+  - full source track is archived under `bitacora/history/TRACK-###.md`.
+  - active `tracks/TRACK-###/track.md` is rewritten into compact summary form.
+  - `tracks/tracks.md` is regenerated and the previous snapshot is archived in `bitacora/history/tracks-*.md`.
+
+Examples:
+
+```bash
+# Compact one already-completed track
+bitacora compact --track-id TRACK-004
+
+# Complete + compact in one step
+bitacora compact --track-id TRACK-004 --complete
+
+# Preview savings for all tracks
+bitacora compact --all --dry-run
+
+# Compact all completed tracks
+bitacora compact --all
+```
+
+### `bitacora history --track-id <trackId> [--show] [--root <path>]`
+
+Reads archived track history.
+
+- `--track-id <trackId>`: required track identifier.
+- `--show`: print full archived content (default prints only metadata/path).
+- `--root <path>`: sets the project root.
+
+### `bitacora --help`
+
+`bitacora --help` includes full command details for:
+- `init`, `skill`, `new-track`, `validate`, `rebuild-state`, `log`
+- `compact` (flags, completion gates, output/archive model)
+- `history` (metadata mode vs `--show`)
+
+For a maintained example output, see `examples/help-output.txt`.
+
 ### `bitacora validate [--json] [--root <path>]`
 
 Validates the Bitacora file/folder structure and reports errors.

package/dist/src/cli.js

@@ -5,9 +5,12 @@ exports.createCliProgram = createCliProgram;
 exports.runCli = runCli;
 const commander_1 = require("commander");
 const init_1 = require("./commands/init");
+const compact_1 = require("./commands/compact");
+const history_1 = require("./commands/history");
 const log_1 = require("./commands/log");
 const new_track_1 = require("./commands/new-track");
 const rebuild_state_1 = require("./commands/rebuild-state");
+const skill_1 = require("./commands/skill");
 const validate_1 = require("./commands/validate");
 const COMMAND_HELP_OVERVIEW = `
 Command details:
@@ -17,6 +20,11 @@ Command details:
       --force        Recreate bitacora memory if it already exists.
       --root <path>  Project root path (default: current directory).
 
+  skill
+    Installs or updates only the bitacora agent skill and skills lock entry.
+    Options:
+      --root <path>  Project root path (default: current directory).
+
   new-track [trackId]
     Creates a new track file, automatically picking the next track id when omitted.
     Options:
@@ -41,6 +49,32 @@ Command details:
       --track-id <trackId>  Track identifier.
       --message <text>      Log entry message.
       --root <path>         Project root path (default: current directory).
+
+  compact
+    Compacts tracks by summarizing and archiving redundant details.
+    Options:
+      --track-id <trackId>  Compact a specific track.
+      --all                 Compact all eligible tracks.
+      --complete            Mark target tracks as completed (requires completion gates).
+      --dry-run             Show savings without modifying files.
+      --root <path>         Project root path (default: current directory).
+    Completion gates (--complete):
+      - # Tasks has no unchecked item (- [ ]).
+      - # Log includes at least one line containing TEST:.
+    Output model:
+      - Full source moves to bitacora/history/TRACK-###.md.
+      - Active track.md is rewritten into compact summary form.
+      - tracks/tracks.md is regenerated; previous snapshot is archived in history/.
+
+  history
+    Reads archived history for a compacted track.
+    Options:
+      --track-id <trackId>  Track identifier.
+      --show                Print full archived content.
+      --root <path>         Project root path (default: current directory).
+    Notes:
+      - Without --show, prints metadata/path only.
+      - Use --show only when compact summary is insufficient.
 `;
 function writeLine(writer, message) {
     writer(message.endsWith("\n") ? message : `${message}\n`);
@@ -73,6 +107,18 @@ function createCliProgram(runtime = {}, onCommandExitCode) {
         });
         onCommandExitCode?.(exitCode);
     });
+    program
+        .command("skill")
+        .description("Install or update only the bitacora agent skill.")
+        .option("--root <path>", "project root path")
+        .action((options) => {
+        const exitCode = (0, skill_1.runSkillCommand)({
+            rootDir: options.root ?? cwd()
+        }, {
+            onError: (message) => writeLine(stderr, message)
+        });
+        onCommandExitCode?.(exitCode);
+    });
     program
         .command("new-track [trackId]")
         .description("Create a new track with optional id, status, and priority.")
@@ -142,6 +188,48 @@ function createCliProgram(runtime = {}, onCommandExitCode) {
         });
         onCommandExitCode?.(exitCode);
     });
+    program
+        .command("compact")
+        .description("Compact tracks and archive redundant details.")
+        .option("--track-id <trackId>", "track identifier")
+        .option("--all", "compact all eligible tracks")
+        .option("--complete", "mark track(s) as completed before compaction")
+        .option("--dry-run", "report savings without writing files")
+        .option("--root <path>", "project root path")
+        .action((options) => {
+        const compactOptions = {
+            rootDir: options.root ?? cwd(),
+            all: Boolean(options.all),
+            complete: Boolean(options.complete),
+            dryRun: Boolean(options.dryRun)
+        };
+        if (options.trackId !== undefined) {
+            compactOptions.trackId = options.trackId;
+        }
+        const exitCode = (0, compact_1.runCompactCommand)(compactOptions, {
+            now,
+            onOutput: (message) => writeLine(stdout, message),
+            onError: (message) => writeLine(stderr, message)
+        });
+        onCommandExitCode?.(exitCode);
+    });
+    program
+        .command("history")
+        .description("Read archived history for a compacted track.")
+        .requiredOption("--track-id <trackId>", "track identifier")
+        .option("--show", "print full archived content")
+        .option("--root <path>", "project root path")
+        .action((options) => {
+        const exitCode = (0, history_1.runHistoryCommand)({
+            rootDir: options.root ?? cwd(),
+            trackId: options.trackId,
+            show: Boolean(options.show)
+        }, {
+            onOutput: (message) => writeLine(stdout, message),
+            onError: (message) => writeLine(stderr, message)
+        });
+        onCommandExitCode?.(exitCode);
+    });
     program.addHelpText("after", COMMAND_HELP_OVERVIEW);
     return program;
 }
@@ -157,6 +245,9 @@ async function runCli(argv, runtime = {}) {
     }
     catch (error) {
         if (error instanceof commander_1.CommanderError) {
+            if (error.code === "commander.helpDisplayed") {
+                return 0;
+            }
             return commandExitCode !== 0 ? commandExitCode : 1;
         }
         throw error;

package/dist/src/commands/compact.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCompactCommand = runCompactCommand;
+const compaction_1 = require("../core/compaction");
+const validator_1 = require("../core/validator");
+function formatSavings(label, before, after, tokensBefore, tokensAfter) {
+    const bytesSaved = before - after;
+    const tokensSaved = tokensBefore - tokensAfter;
+    return `${label}: bytes ${before} -> ${after} (${bytesSaved >= 0 ? "-" : "+"}${Math.abs(bytesSaved)}), tokens ${tokensBefore} -> ${tokensAfter} (${tokensSaved >= 0 ? "-" : "+"}${Math.abs(tokensSaved)})`;
+}
+function runCompactCommand(options, dependencies = {}) {
+    const now = dependencies.now ?? (() => new Date().toISOString());
+    const onOutput = dependencies.onOutput ?? (() => { });
+    const onError = dependencies.onError ?? (() => { });
+    if (options.all && options.trackId) {
+        onError("Use either --all or --track-id, not both");
+        return 1;
+    }
+    if (!options.all && !options.trackId) {
+        onError("Missing target. Provide --track-id <TRACK-###> or --all");
+        return 1;
+    }
+    const initialValidation = (0, validator_1.validateMemory)(options.rootDir);
+    if (!initialValidation.ok) {
+        onError(`Memory structure is invalid: ${initialValidation.errors.join("; ")}`);
+        return 1;
+    }
+    const targets = options.trackId
+        ? [options.trackId]
+        : initialValidation.tracks.map((track) => track.frontmatter.track_id).sort((left, right) => left.localeCompare(right));
+    const timestamp = now();
+    let compactedCount = 0;
+    for (const trackId of targets) {
+        try {
+            const result = (0, compaction_1.compactTrack)({
+                rootDir: options.rootDir,
+                trackId,
+                complete: options.complete,
+                dryRun: options.dryRun,
+                now: timestamp
+            });
+            if (!result.compacted) {
+                onOutput(`${trackId}: skipped (${result.skippedReason ?? "not eligible"})`);
+                continue;
+            }
+            compactedCount += 1;
+            onOutput(formatSavings(trackId, result.bytesBefore, result.bytesAfter, result.estimatedTokensBefore, result.estimatedTokensAfter));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            onError(message);
+            if (options.trackId) {
+                return 1;
+            }
+        }
+    }
+    if (compactedCount === 0) {
+        onOutput("No tracks compacted");
+        return options.trackId ? 1 : 0;
+    }
+    const finalValidation = (0, validator_1.validateMemory)(options.rootDir);
+    if (!finalValidation.ok) {
+        onError(`Memory structure is invalid: ${finalValidation.errors.join("; ")}`);
+        return 1;
+    }
+    const registrySavings = (0, compaction_1.compactTracksRegistry)({
+        rootDir: options.rootDir,
+        now: timestamp,
+        tracks: finalValidation.tracks,
+        dryRun: options.dryRun
+    });
+    onOutput(formatSavings("tracks.md", registrySavings.bytesBefore, registrySavings.bytesAfter, registrySavings.estimatedTokensBefore, registrySavings.estimatedTokensAfter));
+    onOutput(`Compacted tracks: ${compactedCount}`);
+    return 0;
+}

package/dist/src/commands/history.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHistoryCommand = runHistoryCommand;
+const compaction_1 = require("../core/compaction");
+function runHistoryCommand(options, dependencies = {}) {
+    const onOutput = dependencies.onOutput ?? (() => { });
+    const onError = dependencies.onError ?? (() => { });
+    try {
+        const result = (0, compaction_1.readTrackHistory)(options.rootDir, options.trackId, options.show);
+        if (!result.exists) {
+            onError(`History not found for ${options.trackId}: ${result.historyPath}`);
+            return 1;
+        }
+        if (!options.show) {
+            onOutput(`Track: ${result.trackId}`);
+            onOutput(`History path: ${result.historyPath}`);
+            onOutput("Use --show to print history contents");
+            return 0;
+        }
+        onOutput(result.content ?? "");
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        onError(message);
+        return 1;
+    }
+}

package/dist/src/commands/init.js

@@ -6,63 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runInitCommand = runInitCommand;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-const node_crypto_1 = require("node:crypto");
 const templates_1 = require("../core/templates");
-function computeHash(content) {
-    return (0, node_crypto_1.createHash)("sha256").update(content).digest("hex");
-}
-function readSkillsLockFile(filePath) {
-    if (!node_fs_1.default.existsSync(filePath)) {
-        return {
-            version: 1,
-            skills: {}
-        };
-    }
-    try {
-        const parsed = JSON.parse(node_fs_1.default.readFileSync(filePath, "utf8"));
-        if (typeof parsed !== "object" || parsed === null) {
-            return { version: 1, skills: {} };
-        }
-        const versionRaw = parsed.version;
-        const skillsRaw = parsed.skills;
-        const normalized = {};
-        if (typeof skillsRaw === "object" && skillsRaw !== null) {
-            for (const [name, value] of Object.entries(skillsRaw)) {
-                if (typeof value !== "object" || value === null) {
-                    continue;
-                }
-                const source = value.source;
-                const sourceType = value.sourceType;
-                const computedHash = value.computedHash;
-                if (typeof source === "string" &&
-                    typeof sourceType === "string" &&
-                    typeof computedHash === "string") {
-                    normalized[name] = { source, sourceType, computedHash };
-                }
-            }
-        }
-        return {
-            version: typeof versionRaw === "number" ? versionRaw : 1,
-            skills: normalized
-        };
-    }
-    catch {
-        return {
-            version: 1,
-            skills: {}
-        };
-    }
-}
-function writeSkillsLockFile(rootDir, skillContent) {
-    const lockPath = node_path_1.default.join(rootDir, "skills-lock.json");
-    const lock = readSkillsLockFile(lockPath);
-    lock.skills.bitacora = {
-        source: ".agents/skills/bitacora/SKILL.md",
-        sourceType: "local",
-        computedHash: computeHash(skillContent)
-    };
-    node_fs_1.default.writeFileSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
-}
+const skill_installer_1 = require("../core/skill-installer");
 function runInitCommand(options, dependencies = {}) {
     const now = dependencies.now ?? (() => new Date().toISOString());
     const onError = dependencies.onError ?? (() => { });
@@ -78,15 +23,13 @@ function runInitCommand(options, dependencies = {}) {
     const createdOnDate = createdAt.slice(0, 10);
     const trackId = "TRACK-001";
     node_fs_1.default.mkdirSync(node_path_1.default.join(memoryRoot, "tracks", trackId), { recursive: true });
-    node_fs_1.default.mkdirSync(node_path_1.default.join(options.rootDir, ".agents", "skills", "bitacora"), { recursive: true });
+    node_fs_1.default.mkdirSync(node_path_1.default.join(memoryRoot, "history"), { recursive: true });
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "product.md"), (0, templates_1.createProductTemplate)(), "utf8");
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "tech-stack.md"), (0, templates_1.createTechStackTemplate)(), "utf8");
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "workflow.md"), (0, templates_1.createWorkflowTemplate)(), "utf8");
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "ux-style-guide.md"), (0, templates_1.createUxStyleGuideTemplate)(), "utf8");
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "index.md"), (0, templates_1.createIndexTemplate)(), "utf8");
-    const skillContent = (0, templates_1.createAgentSkillTemplate)();
-    node_fs_1.default.writeFileSync(node_path_1.default.join(options.rootDir, ".agents", "skills", "bitacora", "SKILL.md"), skillContent, "utf8");
-    writeSkillsLockFile(options.rootDir, skillContent);
+    (0, skill_installer_1.installBitacoraSkill)(options.rootDir);
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "tracks", "tracks.md"), (0, templates_1.createTracksRegistryTemplate)(createdOnDate), "utf8");
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "tracks", "tracks-template.md"), (0, templates_1.createTracksTemplate)(), "utf8");
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "tracks", trackId, "track.md"), (0, templates_1.createTrackTemplate)(trackId, "active", "medium", createdAt), "utf8");

package/dist/src/commands/skill.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSkillCommand = runSkillCommand;
+const skill_installer_1 = require("../core/skill-installer");
+function runSkillCommand(options, dependencies = {}) {
+    const onError = dependencies.onError ?? (() => { });
+    try {
+        (0, skill_installer_1.installBitacoraSkill)(options.rootDir);
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        onError(message);
+        return 1;
+    }
+}

package/dist/src/core/compaction.js

@@ -0,0 +1,249 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateTokenCount = estimateTokenCount;
+exports.compactTrack = compactTrack;
+exports.buildCompactedTracksRegistry = buildCompactedTracksRegistry;
+exports.compactTracksRegistry = compactTracksRegistry;
+exports.readTrackHistory = readTrackHistory;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const parser_1 = require("./parser");
+const MAX_DECISIONS_IN_COMPACT_TRACK = 3;
+const PENDING_TASK_REGEX = /^-\s*\[\s\]/m;
+const TEST_LOG_REGEX = /^-\s+[^|]+\s+\|\s+TEST:\s+.+$/m;
+function uniqueOrdered(lines) {
+    const seen = new Set();
+    const result = [];
+    for (const line of lines) {
+        if (seen.has(line)) {
+            continue;
+        }
+        seen.add(line);
+        result.push(line);
+    }
+    return result;
+}
+function extractLines(section) {
+    return section
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+function summarizeOverview(overview) {
+    const lines = extractLines(overview);
+    if (lines.length === 0) {
+        return "- Summary unavailable.";
+    }
+    return lines.slice(0, 2).map((line) => `- ${line.replace(/^-\s*/, "")}`).join("\n");
+}
+function summarizeTasks(tasks) {
+    const lines = extractLines(tasks);
+    const checkboxes = lines.filter((line) => /^-\s*\[[ xX]\]/.test(line));
+    const done = checkboxes.filter((line) => /^-\s*\[[xX]\]/.test(line)).length;
+    if (checkboxes.length === 0) {
+        return "- No checklist tasks found.";
+    }
+    return `- Checklist completed: ${done}/${checkboxes.length}`;
+}
+function summarizeDecisions(decisions) {
+    const normalizedLines = extractLines(decisions)
+        .map((line) => line.replace(/^-\s*/, ""));
+    const uniqueLines = uniqueOrdered(normalizedLines);
+    const tail = uniqueLines.slice(-MAX_DECISIONS_IN_COMPACT_TRACK);
+    if (tail.length === 0) {
+        return "- No decisions captured.";
+    }
+    return tail.map((line) => `- ${line}`).join("\n");
+}
+function assertCanMarkAsCompleted(trackPath, tasks, log) {
+    if (PENDING_TASK_REGEX.test(tasks)) {
+        throw new Error(`Cannot mark track as completed: pending tasks found (${trackPath})`);
+    }
+    if (!TEST_LOG_REGEX.test(log)) {
+        throw new Error(`Cannot mark track as completed: missing TEST: evidence in log (${trackPath})`);
+    }
+}
+function renderFrontmatter(fields) {
+    const lines = Object.entries(fields).map(([key, value]) => `${key}: ${value}`);
+    return `---\n${lines.join("\n")}\n---`;
+}
+function ensureHistoryRoot(rootDir) {
+    const historyRoot = node_path_1.default.join(rootDir, "bitacora", "history");
+    node_fs_1.default.mkdirSync(historyRoot, { recursive: true });
+    return historyRoot;
+}
+function buildCompactedTrackMarkdown(input) {
+    const frontmatter = renderFrontmatter({
+        track_id: input.trackId,
+        status: input.status,
+        priority: input.priority,
+        created_at: input.createdAt,
+        updated_at: input.updatedAt,
+        completion: String(input.completion),
+        compacted_at: input.compactedAt,
+        history_path: input.historyPath
+    });
+    return `${frontmatter}
+
+# Overview
+${summarizeOverview(input.overview)}
+- Full history: ${input.historyPath}
+
+# Tasks
+${summarizeTasks(input.tasks)}
+
+# Decisions
+${summarizeDecisions(input.decisions)}
+
+# Log
+- ${input.compactedAt} | compacted track and archived full history
+`;
+}
+function estimateTokenCount(text) {
+    return Math.ceil(text.length / 4);
+}
+function compactTrack(request) {
+    const trackPath = node_path_1.default.join(request.rootDir, "bitacora", "tracks", request.trackId, "track.md");
+    if (!node_fs_1.default.existsSync(trackPath)) {
+        throw new Error(`Track not found: ${request.trackId}`);
+    }
+    const source = node_fs_1.default.readFileSync(trackPath, "utf8").replace(/\r\n/g, "\n");
+    const parsed = (0, parser_1.parseTrackMarkdown)(source);
+    if (request.complete) {
+        assertCanMarkAsCompleted(trackPath, parsed.sections.tasks, parsed.sections.log);
+    }
+    else if (parsed.frontmatter.status !== "completed") {
+        return {
+            trackId: request.trackId,
+            compacted: false,
+            skippedReason: "Track is not completed",
+            bytesBefore: source.length,
+            bytesAfter: source.length,
+            estimatedTokensBefore: estimateTokenCount(source),
+            estimatedTokensAfter: estimateTokenCount(source)
+        };
+    }
+    const compactedAt = request.now;
+    const updatedAt = request.now;
+    const completion = 100;
+    const status = "completed";
+    const historyRoot = ensureHistoryRoot(request.rootDir);
+    const historyFileName = `${request.trackId}.md`;
+    const historyAbsolutePath = node_path_1.default.join(historyRoot, historyFileName);
+    const historyRelativePath = node_path_1.default.join("bitacora", "history", historyFileName).replace(/\\/g, "/");
+    const compactedMarkdown = buildCompactedTrackMarkdown({
+        trackId: parsed.frontmatter.track_id,
+        status,
+        priority: parsed.frontmatter.priority,
+        createdAt: parsed.frontmatter.created_at,
+        updatedAt,
+        completion,
+        compactedAt,
+        historyPath: historyRelativePath,
+        overview: parsed.sections.overview,
+        tasks: parsed.sections.tasks,
+        decisions: parsed.sections.decisions
+    });
+    if (!request.dryRun) {
+        node_fs_1.default.writeFileSync(historyAbsolutePath, source, "utf8");
+        node_fs_1.default.writeFileSync(trackPath, compactedMarkdown, "utf8");
+    }
+    return {
+        trackId: request.trackId,
+        compacted: true,
+        bytesBefore: source.length,
+        bytesAfter: compactedMarkdown.length,
+        estimatedTokensBefore: estimateTokenCount(source),
+        estimatedTokensAfter: estimateTokenCount(compactedMarkdown)
+    };
+}
+function extractTrackRows(tracks) {
+    const sorted = [...tracks].sort((left, right) => left.frontmatter.track_id.localeCompare(right.frontmatter.track_id));
+    return sorted
+        .map((track) => {
+        const status = track.frontmatter.status;
+        const completion = track.frontmatter.completion ?? (status === "completed" ? 100 : 0);
+        const notes = track.frontmatter.compacted_at ? "compacted" : "active detail";
+        return `| ${track.frontmatter.track_id} | ${status} | ${completion}% | ${track.frontmatter.updated_at} | ${notes} |`;
+    })
+        .join("\n");
+}
+function buildCompactedTracksRegistry(now, tracks) {
+    const active = tracks.filter((track) => track.frontmatter.status === "active").length;
+    const blocked = tracks.filter((track) => track.frontmatter.status === "blocked").length;
+    const completed = tracks.filter((track) => track.frontmatter.status === "completed").length;
+    const archived = tracks.filter((track) => track.frontmatter.status === "archived").length;
+    const rows = extractTrackRows(tracks);
+    return `# Tracks
+
+> Canonical project status and handoff registry.
+>
+> Last updated: ${now.slice(0, 10)}
+>
+> Rule: update this file after meaningful implementation changes.
+
+## Snapshot
+
+- Active: ${active}
+- Blocked: ${blocked}
+- Completed: ${completed}
+- Archived: ${archived}
+
+## Track Registry
+
+| ID | Status | Completion | Last Update | Notes |
+| --- | --- | --- | --- | --- |
+${rows.length > 0 ? rows : "| - | - | - | - | - |"}
+
+## Session Handoff (Required)
+
+- Track(s) touched
+- Tests run (exact command + result)
+- Current TDD phase
+- Blockers/assumptions
+- Next recommended action
+`;
+}
+function compactTracksRegistry(options) {
+    const tracksRegistryPath = node_path_1.default.join(options.rootDir, "bitacora", "tracks", "tracks.md");
+    const before = node_fs_1.default.existsSync(tracksRegistryPath) ? node_fs_1.default.readFileSync(tracksRegistryPath, "utf8") : "";
+    const next = buildCompactedTracksRegistry(options.now, options.tracks);
+    if (!options.dryRun) {
+        const historyRoot = ensureHistoryRoot(options.rootDir);
+        const backupFileName = `tracks-${options.now.replace(/[:.]/g, "-")}.md`;
+        node_fs_1.default.writeFileSync(node_path_1.default.join(historyRoot, backupFileName), before, "utf8");
+        node_fs_1.default.writeFileSync(tracksRegistryPath, next, "utf8");
+    }
+    return {
+        bytesBefore: before.length,
+        bytesAfter: next.length,
+        estimatedTokensBefore: estimateTokenCount(before),
+        estimatedTokensAfter: estimateTokenCount(next)
+    };
+}
+function readTrackHistory(rootDir, trackId, includeContent) {
+    const trackPath = node_path_1.default.join(rootDir, "bitacora", "tracks", trackId, "track.md");
+    if (!node_fs_1.default.existsSync(trackPath)) {
+        throw new Error(`Track not found: ${trackId}`);
+    }
+    const parsed = (0, parser_1.parseTrackMarkdown)(node_fs_1.default.readFileSync(trackPath, "utf8"));
+    const historyPath = parsed.frontmatter.history_path ?? node_path_1.default.join("bitacora", "history", `${trackId}.md`).replace(/\\/g, "/");
+    const absoluteHistoryPath = node_path_1.default.join(rootDir, historyPath);
+    const exists = node_fs_1.default.existsSync(absoluteHistoryPath);
+    if (!includeContent) {
+        return {
+            trackId,
+            historyPath,
+            exists
+        };
+    }
+    return {
+        trackId,
+        historyPath,
+        exists,
+        ...(exists ? { content: node_fs_1.default.readFileSync(absoluteHistoryPath, "utf8") } : {})
+    };
+}

package/dist/src/core/parser.js

@@ -78,6 +78,9 @@ function parseTrackMarkdown(markdown) {
     const trackId = getRequiredField("track_id");
     const createdAt = getRequiredField("created_at");
     const updatedAt = getRequiredField("updated_at");
+    const completionRaw = frontmatter.completion;
+    const compactedAtRaw = frontmatter.compacted_at;
+    const historyPathRaw = frontmatter.history_path;
     if (!types_1.TRACK_STATUSES.includes(status)) {
         throw new Error("Invalid status");
     }
@@ -91,13 +94,24 @@ function parseTrackMarkdown(markdown) {
             throw new Error(`Missing section: ${heading}`);
         }
     }
+    let completion;
+    if (completionRaw !== undefined) {
+        const parsedCompletion = Number.parseInt(completionRaw, 10);
+        if (!Number.isInteger(parsedCompletion)) {
+            throw new Error("Invalid completion");
+        }
+        completion = parsedCompletion;
+    }
     return {
         frontmatter: {
             track_id: trackId,
             status: status,
             priority: priority,
             created_at: createdAt,
-            updated_at: updatedAt
+            updated_at: updatedAt,
+            ...(completion !== undefined ? { completion } : {}),
+            ...(compactedAtRaw !== undefined ? { compacted_at: compactedAtRaw } : {}),
+            ...(historyPathRaw !== undefined ? { history_path: historyPathRaw } : {})
         },
         sections: {
             overview: sections.overview ?? "",

package/dist/src/core/skill-installer.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installBitacoraSkill = installBitacoraSkill;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const templates_1 = require("./templates");
+function computeHash(content) {
+    return (0, node_crypto_1.createHash)("sha256").update(content).digest("hex");
+}
+function readSkillsLockFile(filePath) {
+    if (!node_fs_1.default.existsSync(filePath)) {
+        return {
+            version: 1,
+            skills: {}
+        };
+    }
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(filePath, "utf8"));
+        if (typeof parsed !== "object" || parsed === null) {
+            return { version: 1, skills: {} };
+        }
+        const versionRaw = parsed.version;
+        const skillsRaw = parsed.skills;
+        const normalized = {};
+        if (typeof skillsRaw === "object" && skillsRaw !== null) {
+            for (const [name, value] of Object.entries(skillsRaw)) {
+                if (typeof value !== "object" || value === null) {
+                    continue;
+                }
+                const source = value.source;
+                const sourceType = value.sourceType;
+                const computedHash = value.computedHash;
+                if (typeof source === "string" &&
+                    typeof sourceType === "string" &&
+                    typeof computedHash === "string") {
+                    normalized[name] = { source, sourceType, computedHash };
+                }
+            }
+        }
+        return {
+            version: typeof versionRaw === "number" ? versionRaw : 1,
+            skills: normalized
+        };
+    }
+    catch {
+        return {
+            version: 1,
+            skills: {}
+        };
+    }
+}
+function writeSkillsLockFile(rootDir, skillContent) {
+    const lockPath = node_path_1.default.join(rootDir, "skills-lock.json");
+    const lock = readSkillsLockFile(lockPath);
+    lock.skills.bitacora = {
+        source: ".agents/skills/bitacora/SKILL.md",
+        sourceType: "local",
+        computedHash: computeHash(skillContent)
+    };
+    node_fs_1.default.writeFileSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+}
+function installBitacoraSkill(rootDir) {
+    const skillDir = node_path_1.default.join(rootDir, ".agents", "skills", "bitacora");
+    node_fs_1.default.mkdirSync(skillDir, { recursive: true });
+    const skillContent = (0, templates_1.createAgentSkillTemplate)();
+    node_fs_1.default.writeFileSync(node_path_1.default.join(skillDir, "SKILL.md"), skillContent, "utf8");
+    writeSkillsLockFile(rootDir, skillContent);
+}

package/dist/src/core/templates.js

@@ -22,6 +22,7 @@ Quick map of where to find each kind of project memory.
 4. \`ux-style-guide.md\` (visual style tokens and UX constraints)
 5. \`tracks/tracks.md\` (canonical project status and next actions)
 6. \`tracks/TRACK-*/track.md\` (details for active or relevant tracks)
+7. \`history/\` (archived detail, read only when needed)
 
 ## File Index
 
@@ -37,11 +38,16 @@ Quick map of where to find each kind of project memory.
 - \`tracks/TRACK-001/track.md\`: first active track created by \`bitacora init\`.
 - \`tracks/TRACK-*/track.md\`: per-track execution details (overview, tasks, decisions, log).
 
+### \`history/\`
+- \`history/TRACK-*.md\`: archived full detail after compaction.
+- \`history/tracks-*.md\`: archived snapshots of \`tracks/tracks.md\`.
+
 Mandatory behavior:
 
 - Always read this index at session start.
 - Always update memory before session end.
 - Always keep \`tracks/tracks.md\` aligned with track-level changes.
+- Read \`history/\` only when active context is insufficient.
 `;
 }
 function createProductTemplate() {
@@ -163,7 +169,7 @@ function createAgentSkillTemplate() {
     return `---
 name: bitacora
 description: Keep deterministic project memory in bitacora/ and update it continuously during implementation sessions.
-version: 1.0.0
+version: 1.1.1
 type: local
 source: .agents/skills/bitacora/SKILL.md
 ---
@@ -179,11 +185,13 @@ Canonical skill file path: \`.agents/skills/bitacora/SKILL.md\`.
 - Always read \`bitacora/product.md\`, \`bitacora/tech-stack.md\`, \`bitacora/workflow.md\`, and \`bitacora/ux-style-guide.md\` before making code changes.
 - Always read \`bitacora/tracks/tracks.md\` and the active \`bitacora/tracks/TRACK-*/track.md\` files before implementation.
 - Always write memory updates before ending the session.
+- Do not read \`bitacora/history/\` unless needed to recover full detail.
 
 ## What To Update During Work
 - Update \`bitacora/tracks/TRACK-*/track.md\` while work progresses (tasks, decisions, logs).
 - Update \`bitacora/tracks/tracks.md\` after meaningful changes, including current status and next action.
 - Update root docs when product/tech/workflow/ux assumptions change.
+- Before closing a fully completed track, append a \`TEST:\` verification log and run \`bitacora compact --track-id <id> --complete\`.
 
 ## File Map (Where To Look)
 - \`bitacora/product.md\`: scope, goals, constraints, non-goals.
@@ -193,6 +201,7 @@ Canonical skill file path: \`.agents/skills/bitacora/SKILL.md\`.
 - \`bitacora/tracks/tracks.md\`: canonical status registry and handoff summary.
 - \`bitacora/tracks/tracks-template.md\`: template for new tracks.
 - \`bitacora/tracks/TRACK-*/track.md\`: per-track execution details.
+- \`bitacora/history/\`: archived detail to inspect only when needed.
 
 ## Manual Bootstrap (No CLI Required)
 If the CLI is unavailable, create this exact structure manually:
@@ -204,6 +213,7 @@ bitacora/
   tech-stack.md
   workflow.md
   ux-style-guide.md
+  history/
   tracks/
     tracks.md
     tracks-template.md
@@ -226,6 +236,7 @@ Required track sections in \`track.md\`:
 ## End Of Session Checklist
 - Confirm \`bitacora/tracks/tracks.md\` is updated.
 - Confirm active \`TRACK-*/track.md\` files include latest decisions and logs.
+- Confirm compacted tracks have history in \`bitacora/history/\`.
 `;
 }
 function createTracksRegistryTemplate(date) {

package/dist/src/core/validator.js

@@ -112,6 +112,27 @@ function validateUpdatedAtAgainstLogEntries(tracks, errors) {
         }
     }
 }
+function validateCompactionMetadata(rootDir, tracks, errors) {
+    for (const track of tracks) {
+        const { completion, status, history_path: historyPath } = track.frontmatter;
+        if (completion !== undefined && (completion < 0 || completion > 100)) {
+            errors.push(`Invalid completion value for ${track.frontmatter.track_id}: ${completion}`);
+        }
+        if (status === "completed" && completion !== undefined && completion !== 100) {
+            errors.push(`Completed track must have completion 100: ${track.frontmatter.track_id}`);
+        }
+        if (track.frontmatter.compacted_at !== undefined) {
+            if (!historyPath) {
+                errors.push(`Compacted track missing history_path: ${track.frontmatter.track_id}`);
+                continue;
+            }
+            const historyAbsolutePath = node_path_1.default.join(rootDir, historyPath);
+            if (!node_fs_1.default.existsSync(historyAbsolutePath)) {
+                errors.push(`Compacted track history file not found for ${track.frontmatter.track_id}`);
+            }
+        }
+    }
+}
 function validateMemory(rootDir) {
     const errors = [];
     const trackDirectories = getTrackDirectories(rootDir);
@@ -119,6 +140,7 @@ function validateMemory(rootDir) {
     const tracks = loadTracks(rootDir, errors);
     validateDuplicateTrackIds(tracks, errors);
     validateUpdatedAtAgainstLogEntries(tracks, errors);
+    validateCompactionMetadata(rootDir, tracks, errors);
     errors.sort((left, right) => left.localeCompare(right));
     return {
         ok: errors.length === 0,

package/dist/src/index.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateMemory = exports.buildStateFromTracks = exports.buildIndexFromTracks = exports.parseTrackMarkdown = exports.boot = void 0;
+exports.validateMemory = exports.buildStateFromTracks = exports.buildIndexFromTracks = exports.parseTrackMarkdown = exports.readTrackHistory = exports.compactTracksRegistry = exports.compactTrack = exports.boot = void 0;
 var boot_1 = require("./core/boot");
 Object.defineProperty(exports, "boot", { enumerable: true, get: function () { return boot_1.boot; } });
+var compaction_1 = require("./core/compaction");
+Object.defineProperty(exports, "compactTrack", { enumerable: true, get: function () { return compaction_1.compactTrack; } });
+Object.defineProperty(exports, "compactTracksRegistry", { enumerable: true, get: function () { return compaction_1.compactTracksRegistry; } });
+Object.defineProperty(exports, "readTrackHistory", { enumerable: true, get: function () { return compaction_1.readTrackHistory; } });
 var parser_1 = require("./core/parser");
 Object.defineProperty(exports, "parseTrackMarkdown", { enumerable: true, get: function () { return parser_1.parseTrackMarkdown; } });
 var state_builder_1 = require("./core/state-builder");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bitacora-cli",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Deterministic agent-oriented project memory system. Provides structured Markdown-based long-term memory, strict validation, state reconstruction, and an enforcement CLI with agent skill integration to guide and limit agent behavior.",
   "repository": {
     "type": "git",