bitacora-cli 1.0.0 → 1.1.0

package/README.md

@@ -14,24 +14,6 @@ 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.
 
 ## What Each Bitacora File Stores
@@ -43,42 +25,51 @@ 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.
+
+## Typical flow
+
+```bash
+# 1) bootstrap
+bitacora init
+
+# 2) create work
+bitacora new-track
 
-This skill guides agents to keep memory updated during implementation:
+# 3) 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"
 
-- 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`.
+# 4) compact when fully completed
+bitacora compact --track-id TRACK-001 --complete
+
+# 5) inspect archive only when needed
+bitacora history --track-id TRACK-001
+bitacora history --track-id TRACK-001 --show
+```
 
 ## Commands
 
@@ -106,6 +97,40 @@ 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.
+
+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 validate [--json] [--root <path>]`
 
 Validates the Bitacora file/folder structure and reports errors.

package/dist/src/cli.js

@@ -5,6 +5,8 @@ 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");
@@ -41,6 +43,22 @@ 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).
+
+  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).
 `;
 function writeLine(writer, message) {
     writer(message.endsWith("\n") ? message : `${message}\n`);
@@ -142,6 +160,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;
 }

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

@@ -78,6 +78,7 @@ 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(memoryRoot, "history"), { recursive: true });
     node_fs_1.default.mkdirSync(node_path_1.default.join(options.rootDir, ".agents", "skills", "bitacora"), { 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");

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/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() {
@@ -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.0",
   "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",