@@ -0,0 +1,19 @@
+name: CI
+on:
+  push:
+    branches: [main, 'codex/**']
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '26.7.0'
+          cache: npm
+      - run: npm ci --ignore-scripts
+      - run: npm run typecheck
+      - run: npm test
@@ -0,0 +1,4 @@
+node_modules/
+coverage/
+dist/
+.DS_Store
@@ -0,0 +1,52 @@
+# codeboost
+
+Review agent-made Git changes one plan item at a time. The approved plan lists each item's files and acceptance checks; the review engine shows which item produced each change and flags foreign or overlapping work.
+
+**Status:** the first library slice is implemented. There is no application, server, agent runner, database, or merge command yet. Follow the [build order](docs/designs/codeboost-plan-indexed-review.md#build-order-and-the-gono-go-check); the read-only screen and real-PR go/no-go experiment come before agent execution.
+
+## Development
+
+Requires Node 26.7 or later and Git.
+
+```sh
+npm ci --ignore-scripts
+npm run typecheck
+npm test
+```
+
+Tests create disposable local repositories. They do not invoke agents, access GitHub, or execute plan acceptance commands.
+
+## Library
+
+- `core/plan.ts`: schema validation; YAML/JSON import; projected file-state and dependency checks; literal command parsing; individual suggestion validation and application.
+- `git/history.ts`: reads an immutable base-to-head commit range and file blobs. Uses argv, disables external diff/textconv helpers, hooks, and replacement objects.
+- `core/linking.ts`: replays line changes using an explicit `Map<commitSha, planItemId>` supplied by the caller. Trailers never establish ownership. Foreign work is Unplanned; overlapping item edits are Ambiguous; undeclared edits stay on their owner's row as out of scope.
+- `core/approvals.ts`: approval snapshots, dependency staleness, assignments, and accept-as-is choices keyed by content and duplicate occurrence/count.
+
+Example from TypeScript (Node can load these source modules):
+
+```ts
+import { importPlan } from './core/plan.ts';
+import { readHistory } from './git/history.ts';
+import { linkHistory } from './core/linking.ts';
+
+const { plan, warnings } = importPlan(planText, 'yaml', {
+  baseFiles: pathsAtBaseCommit, // Include symlink and submodule entries, never their targets.
+  allowedCommands: [['npm', 'test']],
+  issue: 412,
+}, nextRevision);
+const history = readHistory(repoPath, baseCommit, headCommit);
+const segments = linkHistory(plan, history, trustedCommitLedger);
+```
+
+Inputs such as `planText` and the ledger must come from the caller. The future `runner/store` owns the database and ledger; this library does not infer them from commit messages. Before saving a suggested edit, the store must compare-and-swap the plan revision in one transaction. The pure `applySuggestion` function validates a copy but cannot lock storage.
+
+## Current limits and safety
+
+- History must be linear and descend from the requested base. Merge histories are rejected with a rebase instruction. Reads are bounded to 500 commits, 32 MiB per Git response, and a 2-second budget per line diff; oversized work fails explicitly.
+- Ownership uses line diffs, not semantic inference. Within one replacement block, new lines inherit all affected owners conservatively. Function context comes from Git hunk headers, not an AST.
+- The importer requires an accurate base-file list. It rejects path traversal, Git metadata paths, and traversal through a listed file/symlink/submodule. Runtime symlink and write-scope enforcement belong to the future container/runner; plan validation alone is not a sandbox.
+- Allowed commands restrict accidents, not hostile programs or changed scripts. Parsing returns argv and never executes it. An unlisted valid command is a warning and must not run until allowed.
+- No code here claims container isolation, vendor-only network access, credential protection, or safe dependency installation. Those controls must be implemented before running agents.
+
+See [implementation decisions and evidence](docs/implementation/build-step-1.md) and the [plan format](docs/plan-format.md).
@@ -0,0 +1,54 @@
+import type { Plan, PlanItem } from './plan.ts';
+import type { Segment } from './linking.ts';
+
+/** Stable representation ignores object-key order and normalizes CRLF, not whitespace. */
+function stable(value: unknown): string {
+  if (typeof value === 'string') return JSON.stringify(value.replace(/\r\n/g, '\n'));
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (value !== null && typeof value === 'object') return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, val]) => `${JSON.stringify(key)}:${stable(val)}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+const contentKey = (s: Segment) => stable({ path: s.path, oldPath: s.oldPath, kind: s.kind, operation: s.operation, content: s.content });
+export interface SegmentChoice { key: string; action: 'assign' | 'accept'; item: string | null }
+/** Position among identical segments and total copies prevent approval transfer. */
+export function choiceKeys(segments: readonly Segment[]): string[] {
+  const counts = new Map<string, number>(), seen = new Map<string, number>();
+  for (const segment of segments) { const key = contentKey(segment); counts.set(key, (counts.get(key) ?? 0) + 1); }
+  return segments.map(segment => {
+    const key = contentKey(segment), copy = (seen.get(key) ?? 0) + 1; seen.set(key, copy);
+    return stable([key, copy, counts.get(key)]);
+  });
+}
+export function applyChoices(plan: Plan, segments: readonly Segment[], choices: readonly SegmentChoice[]): Segment[] {
+  const keys = choiceKeys(segments);
+  const byKey = new Map(choices.map(choice => [choice.key, choice]));
+  return segments.map((segment, i) => {
+    const choice = byKey.get(keys[i]!);
+    if (!choice || !['Ambiguous', 'Unplanned'].includes(segment.row)) return { ...segment };
+    if (choice.action === 'accept') return { ...segment, row: 'Accepted' };
+    if (!plan.items.some(item => item.id === choice.item)) throw new Error('Assigned item does not exist.');
+    return { ...segment, row: choice.item! };
+  });
+}
+export interface Approval { item: string; fingerprint: string }
+function fingerprint(item: PlanItem, segments: readonly Segment[]): string {
+  return stable({ item, segments: segments.filter(s => s.row === item.id).map(s => ({
+    path: s.path, oldPath: s.oldPath, kind: s.kind, operation: s.operation,
+    content: s.content, context: s.context, owners: [...s.owners].sort(),
+  })) });
+}
+export function approveItem(plan: Plan, segments: readonly Segment[], itemId: string, confirmNoChange = false): Approval {
+  const item = plan.items.find(item => item.id === itemId);
+  if (!item) throw new Error('Unknown item.');
+  if (!segments.some(segment => segment.row === itemId) && !confirmNoChange) throw new Error('Confirm no change needed before approving.');
+  return { item: itemId, fingerprint: fingerprint(item, segments) };
+}
+export function approvalStates(plan: Plan, segments: readonly Segment[], approvals: readonly Approval[]): Record<string, 'unreviewed' | 'approved' | 'stale'> {
+  const result: Record<string, 'unreviewed' | 'approved' | 'stale'> = Object.create(null);
+  for (const item of plan.items) {
+    const approval = approvals.find(approval => approval.item === item.id);
+    result[item.id] = !approval ? 'unreviewed' : approval.fingerprint !== fingerprint(item, segments) ||
+      item.depends_on.some(dep => result[dep] === 'stale') ? 'stale' : 'approved';
+  }
+  return result;
+}
@@ -0,0 +1,150 @@
+import { diffArrays } from 'diff';
+import type { Plan } from './plan.ts';
+
+export interface FileVersion { oid: string; mode: string; text: string | null }
+export interface ContextRange { oldStart: number; oldCount: number; newStart: number; newCount: number; name: string }
+export interface FileDelta {
+  oldPath: string | null; newPath: string | null;
+  before: FileVersion | null; after: FileVersion | null;
+  contexts: ContextRange[];
+}
+export interface CommitDelta { sha: string; parent: string; files: FileDelta[] }
+export interface History { base: string; head: string; commits: CommitDelta[]; final: FileDelta[] }
+export interface Segment {
+  path: string; oldPath: string | null; kind: 'text' | 'file';
+  /** Null means a foreign commit. Caller-supplied ledger is the sole authority. */
+  owners: (string | null)[];
+  row: string; scope: 'in-scope' | 'out-of-scope' | 'unplanned' | 'ambiguous';
+  oldLine: number | null; newLine: number | null; operation: '+' | '-' | null;
+  content: string; context: string; hunk: number; sharesHunkWith: string[];
+}
+interface TrackedLine { text: string; owners: (string | null)[]; origins: string[]; movedOwners: (string | null)[] }
+interface TrackedFile { lines: TrackedLine[]; metadataOwners: (string | null)[] }
+const lines = (text: string | null | undefined): string[] => text?.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+const unique = <T>(values: T[]): T[] => [...new Set(values)];
+const origin = (path: string, i: number) => `${path}\0${i}`;
+function textFile(file: FileVersion | null): boolean {
+  return file !== null && file.text !== null && ['100644', '100755'].includes(file.mode);
+}
+function metadataChange(delta: FileDelta): boolean {
+  return delta.oldPath !== delta.newPath || delta.before?.mode !== delta.after?.mode ||
+    !textFile(delta.before) || !textFile(delta.after);
+}
+function classify(plan: Plan, owners: (string | null)[], paths: string[]): Pick<Segment, 'row' | 'scope'> {
+  if (!owners.length || owners.includes(null)) return { row: 'Unplanned', scope: 'unplanned' };
+  if (owners.length > 1) return { row: 'Ambiguous', scope: 'ambiguous' };
+  const item = plan.items.find(item => item.id === owners[0]);
+  if (!item) throw new Error(`Ledger references unknown plan item ${owners[0]}.`);
+  const declared = new Set(item.files.flatMap(file => [file.path, ...(file.renamed_from ? [file.renamed_from] : [])]));
+  return { row: item.id, scope: paths.every(path => declared.has(path)) ? 'in-scope' : 'out-of-scope' };
+}
+
+/** Replays a linear history. Commit messages and Plan-Item trailers are never trusted. */
+export function linkHistory(plan: Plan, history: History, ledger: ReadonlyMap<string, string>): Segment[] {
+  const files = new Map<string, TrackedFile>();
+  const removed = new Map<string, (string | null)[]>();
+  // Deletions retain metadata even after the file leaves the tree.
+  const metadata = new Map<string, (string | null)[]>();
+  let parent = history.base;
+  for (const commit of history.commits) {
+    if (commit.parent !== parent) throw new Error('Linking requires a contiguous linear history.');
+    parent = commit.sha;
+    const owner = ledger.get(commit.sha) ?? null;
+    if (owner !== null && !plan.items.some(item => item.id === owner)) throw new Error(`Unknown ledger item: ${owner}`);
+    for (const delta of commit.files) {
+      const oldPath = delta.oldPath;
+      const path = delta.newPath ?? oldPath!;
+      let previous = oldPath ? files.get(oldPath) : undefined;
+      if (!previous) previous = {
+        lines: lines(textFile(delta.before) ? delta.before!.text : '').map((text, i) => ({ text, owners: [], origins: [origin(oldPath!, i)], movedOwners: [] })),
+        metadataOwners: [],
+      };
+      const next: TrackedLine[] = [];
+      const changes = diffArrays(previous.lines.map(line => line.text), lines(textFile(delta.after) ? delta.after!.text : ''), { timeout: 2000 });
+      if (!changes) throw new Error('Line attribution exceeded the diff time budget.');
+      let cursor = 0;
+      for (let n = 0; n < changes.length; n++) {
+        const change = changes[n]!;
+        if (!change.added && !change.removed) { next.push(...previous.lines.slice(cursor, cursor + change.value.length)); cursor += change.value.length; continue; }
+        const deleted = change.removed ? previous.lines.slice(cursor, cursor + change.value.length) : [];
+        if (change.removed) cursor += change.value.length;
+        const owners = unique([...deleted.flatMap(line => line.owners), owner]);
+        const origins = unique(deleted.flatMap(line => line.origins));
+        for (const id of origins) removed.set(id, owners);
+        const added = change.added ? change : changes[n + 1]?.added ? changes[++n]! : undefined;
+        if (added) for (const text of added.value) next.push({ text, owners, origins, movedOwners: unique(deleted.flatMap(line => line.movedOwners)) });
+      }
+      if (oldPath && delta.newPath && oldPath !== delta.newPath) {
+        for (let i = 0; i < next.length; i++) {
+          const line = next[i]!;
+          next[i] = { ...line, movedOwners: unique([...line.movedOwners, owner]) };
+          for (const id of line.origins) if (!removed.has(id)) removed.set(id, unique([...line.owners, owner]));
+        }
+      }
+      const metadataOwners = metadataChange(delta) ? unique([...previous.metadataOwners, owner]) : previous.metadataOwners;
+      if (oldPath) { files.delete(oldPath); metadata.set(oldPath, metadataOwners); }
+      if (delta.newPath) { files.set(delta.newPath, { lines: next, metadataOwners }); metadata.set(delta.newPath, metadataOwners); }
+    }
+  }
+  if (parent !== history.head) throw new Error('History does not end at the requested head.');
+  const segments: Segment[] = [];
+  for (const delta of history.final) {
+    const path = delta.newPath ?? delta.oldPath!;
+    const tracked = delta.newPath ? files.get(delta.newPath) : undefined;
+    const oldLines = lines(textFile(delta.before) ? delta.before!.text : '');
+    const newLines = lines(textFile(delta.after) ? delta.after!.text : '');
+    let oldIndex = 0, newIndex = 0, hunk = 0;
+    const fileSegments: Segment[] = [];
+    const affectedPaths = unique([delta.oldPath, delta.newPath].filter((p): p is string => p !== null));
+    const push = (part: Omit<Segment, 'row' | 'scope' | 'sharesHunkWith'>) => fileSegments.push({
+      ...part, ...classify(plan, part.owners, affectedPaths), sharesHunkWith: [],
+    });
+    if (metadataChange(delta)) {
+      const owners = unique(affectedPaths.flatMap(path => metadata.get(path) ?? []));
+      push({ path, oldPath: delta.oldPath, kind: 'file', owners, oldLine: null, newLine: null,
+        operation: null, context: '', hunk: -1,
+        content: JSON.stringify({ oldPath: delta.oldPath, newPath: delta.newPath,
+          oldMode: delta.before?.mode ?? null, newMode: delta.after?.mode ?? null,
+          oldOid: delta.before?.oid ?? null, newOid: delta.after?.oid ?? null }),
+      });
+    }
+    const finalChanges = diffArrays(oldLines, newLines, { timeout: 2000 });
+    if (!finalChanges) throw new Error('Final diff exceeded the time budget.');
+    for (const change of finalChanges) {
+      if (!change.added && !change.removed) {
+        oldIndex += change.value.length; newIndex += change.value.length;
+        if (change.value.length > 6) hunk++;
+        continue;
+      }
+      for (const text of change.value) {
+        const trackedLine = tracked?.lines[newIndex];
+        const owners = change.added
+          ? trackedLine?.owners.length ? trackedLine.owners : trackedLine?.movedOwners ?? []
+          : removed.get(origin(delta.oldPath!, oldIndex)) ?? [];
+        const context = delta.contexts.find(range => change.added
+          ? newIndex + 1 >= range.newStart && newIndex + 1 < range.newStart + range.newCount
+          : oldIndex + 1 >= range.oldStart && oldIndex + 1 < range.oldStart + range.oldCount)?.name ?? '';
+        push({ path, oldPath: delta.oldPath, kind: 'text', owners, content: text, context, hunk,
+          oldLine: change.removed ? oldIndex + 1 : null, newLine: change.added ? newIndex + 1 : null,
+          operation: change.added ? '+' : '-',
+        });
+        if (change.added) newIndex++; else oldIndex++;
+      }
+    }
+    // Adjacent lines with identical ownership/context form one segment.
+    const grouped: Segment[] = [];
+    for (const part of fileSegments) {
+      const last = grouped.at(-1);
+      if (last && part.kind === 'text' && last.kind === 'text' && last.hunk === part.hunk &&
+          last.operation === part.operation && last.context === part.context &&
+          (part.operation === '+' ? last.newLine! + lines(last.content).length === part.newLine : last.oldLine! + lines(last.content).length === part.oldLine) &&
+          JSON.stringify(last.owners) === JSON.stringify(part.owners)) last.content += part.content;
+      else grouped.push({ ...part });
+    }
+    for (const part of grouped) part.sharesHunkWith = unique(grouped
+      .filter(other => other !== part && other.hunk === part.hunk && other.row !== part.row)
+      .flatMap(other => other.owners.filter((owner): owner is string => owner !== null)));
+    segments.push(...grouped);
+  }
+  return segments;
+}