Skip to content

Commit 550340a

Browse files
mchwangclaude
andauthored
Implement plan validation and ledger-backed review core (#4)
* Add Evidence Desk design system and design review specs - DESIGN.md: tokens, type, layout, components (provenance gutter, file-change cards, logo), motion, and a decisions log. - CLAUDE.md: point UI work at DESIGN.md. - Design doc: screen specifications from the design review (D12-D28) and mark D22 done. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Add plan schema, import format, and plan-author prompt - schema/plan.schema.json: plan format v1, strict-mode compatible, used by claude --json-schema and codex exec --output-schema and for imports. - schema/plan-edit.schema.json: typed plan-assistant suggestions. - schema/examples/: #412 r3 plan (YAML) and a suggestion reply. - docs/plan-format.md: plain-language guide, checks after import, versions. - prompts/plan-author.md: one prompt for both agents. - Design doc: rewrite "The plan format", add decision P1 and task T18, list the four new approved mockups. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Fix clone isolation and plan validation contracts * Address automated review of plan safety and design docs * Address second Copilot review: container lock-down, symlinks, cmd wording - Design doc: lock down agent containers (read-only root, tmpfs scratch, non-root, no capabilities, no host mounts, resource limits) with a start-up self-test; /work is the only lasting writable place. T1 verify steps extended. Fix the last "three checks" to four. - plan-format.md: reject symlink components and .git targets in path and renamed_from; after each run, reject undeclared symlinks, symlinks that leave the repo, and any .git change; run codeboost's git with hooks off. - Both schemas, the guide, and the prompt describe cmd as one program with literal arguments run without a shell. Example P2 command no longer contains a quoted pipe. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Implement plan validation and ledger-backed Git review core * Preserve BOM changes in Git review evidence * Prevent Git preferences from hiding review changes * Track file scope at the owning commit across renames * Isolate Git object reads from inherited environment * Reject borrowed Git object stores and verify rename evidence * Bound cumulative Git blob memory per review history * Reject symlinked Git object storage before history reads * Bound directory scanning and document Git selection policy * Bound aggregate Git diff bytes and retained file records * Align plan library and review identities with merged v1 contracts * Reject all Unicode control characters in v1 paths and commands * Update library examples and verify scored rename parsing * Bound history replay and fix rename lineage and link target checks * Retain metadata ownership when deleted paths are reused * Reject Git graft and shallow ancestry metadata --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 91fd2b4 commit 550340a

18 files changed

Lines changed: 3410 additions & 0 deletions

‎.github/workflows/ci.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: CI
2+
on:
3+
push:
4+
branches: [main, 'codex/**']
5+
pull_request:
6+
permissions:
7+
contents: read
8+
jobs:
9+
test:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: actions/setup-node@v4
14+
with:
15+
node-version: '26.7.0'
16+
cache: npm
17+
- run: npm ci --ignore-scripts
18+
- run: npm run typecheck
19+
- run: npm test

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
node_modules/
2+
coverage/
3+
dist/
4+
.DS_Store

‎README.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# codeboost
2+
3+
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.
4+
5+
**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.
6+
7+
## Development
8+
9+
Requires Node 26.7 or later and Git.
10+
11+
```sh
12+
npm ci --ignore-scripts
13+
npm run typecheck
14+
npm test
15+
```
16+
17+
Tests create disposable local repositories. They do not invoke agents, access GitHub, or execute plan acceptance commands.
18+
19+
## Library
20+
21+
- `core/plan.ts`: schema validation; YAML/JSON import; projected file-state and dependency checks; literal command parsing; individual suggestion validation and application.
22+
- `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.
23+
- `core/linking.ts`: replays line changes using an explicit `Map<commitSha, planItemId | null>` 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.
24+
- `core/approvals.ts`: approval snapshots, dependency staleness, assignments, and accept-as-is choices keyed by content and duplicate occurrence/count.
25+
26+
Example from TypeScript (Node can load these source modules):
27+
28+
```ts
29+
import { importPlan } from './core/plan.ts';
30+
import { readHistory } from './git/history.ts';
31+
import { linkHistory } from './core/linking.ts';
32+
33+
const { plan, warnings } = importPlan(planText, 'yaml', {
34+
identity: storedPlanIdentity, // Stable repositoryId, taskId, and planId from storage.
35+
baseEntries: entriesAtBaseCommit, // Typed file/gitlink entries; symlinks include target text.
36+
pathKey: checkoutPathKey, // Actual checkout case/Unicode identity; fail if unknown.
37+
allowedCommands: [['npm', 'test']],
38+
issue: 412,
39+
}, nextRevision);
40+
const history = readHistory(repoPath, baseCommit, headCommit);
41+
const segments = linkHistory(plan, history, trustedCommitLedger, checkoutPathKey);
42+
```
43+
44+
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 load its captured identity/revision binding by opaque suggestion ID, reject canceled or consumed IDs, and compare-and-swap the plan revision plus consume/invalidate old suggestions in one transaction. The pure `applySuggestion` function requires that trusted binding and validates a copy, but cannot lock storage or prevent replay by itself. Applying one card stales its siblings; refresh and review regenerated cards before the next Apply. Approvals and choices likewise require the stored plan identity.
45+
46+
## Current limits and safety
47+
48+
- History must be linear and descend from the requested base. Merge histories are rejected with a rebase instruction; repositories using grafts, shallow ancestry, object alternates, or symlinked object storage are rejected (storage inspection is limited to 100,000 entries). Reads are bounded to 500 commits, 32 MiB per Git response, 64 MiB of unique blob bytes across the history (callers may lower `maxBlobBytes`), 8 MiB of cumulative diff output, 20,000 cumulative file records (including the final diff), and a shared 30-second monotonic deadline for a read. Git children receive only the remaining time and are killed on timeout. Filesystem inspections check the deadline between operations; a blocked filesystem syscall still requires an external worker supervisor. Oversized work fails explicitly.
49+
- Linking separately bounds cumulative split lines and candidate segments to 100,000 each, reference/work operations to 1,000,000, and text/origin strings to 32 Mi UTF-16 code units. It checks before expanding lines/origin sets; grouping no longer repeatedly splits accumulated content. Callers may lower these budgets. Linking has a 30-second overall deadline and each line diff uses at most 2 seconds or the remaining total, whichever is smaller.
50+
- The caller selects and trusts the repository and its Git administrative directory. Normal Git discovery, linked-worktree gitfiles, and symlinked gitdirs are supported; object-storage links and alternates inside that selected gitdir are rejected. This adapter is not a filesystem-containment boundary for untrusted repository roots.
51+
- Git administrative metadata and object storage must remain unchanged during a read; these library checks do not isolate a concurrently hostile filesystem.
52+
- 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.
53+
- The importer requires accurate typed base entries, stable plan identity, a selected issue, and a trusted checkout path-identity function. 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.
54+
- 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.
55+
- No code here claims container isolation, vendor-only network access, credential protection, or safe dependency installation. Those controls must be implemented before running agents.
56+
57+
See [implementation decisions and evidence](docs/implementation/build-step-1.md) and the [plan format](docs/plan-format.md).

‎core/approvals.ts‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
import { identityKey, type PlanIdentity } from './identity.ts';
2+
import type { Plan, PlanItem } from './plan.ts';
3+
import type { Segment } from './linking.ts';
4+
5+
/** Stable representation ignores object-key order and normalizes CRLF, not whitespace. */
6+
function stable(value: unknown): string {
7+
if (typeof value === 'string') return JSON.stringify(value.replace(/\r\n/g, '\n'));
8+
if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
9+
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(',')}}`;
10+
return JSON.stringify(value);
11+
}
12+
const contentKey = (s: Segment) => stable({ path: s.path, oldPath: s.oldPath, kind: s.kind, operation: s.operation, content: s.content });
13+
export interface SegmentChoice { key: string; action: 'assign' | 'accept'; item: string | null }
14+
/** Position among identical segments and total copies prevent approval transfer. */
15+
export function choiceKeys(segments: readonly Segment[], identity: PlanIdentity): string[] {
16+
const identityValue = identityKey(identity);
17+
const counts = new Map<string, number>(), seen = new Map<string, number>();
18+
for (const segment of segments) { const key = contentKey(segment); counts.set(key, (counts.get(key) ?? 0) + 1); }
19+
return segments.map(segment => {
20+
const key = contentKey(segment), copy = (seen.get(key) ?? 0) + 1; seen.set(key, copy);
21+
return stable([identityValue, key, copy, counts.get(key)]);
22+
});
23+
}
24+
export function applyChoices(plan: Plan, segments: readonly Segment[], choices: readonly SegmentChoice[], identity: PlanIdentity): Segment[] {
25+
const keys = choiceKeys(segments, identity);
26+
const byKey = new Map(choices.map(choice => [choice.key, choice]));
27+
return segments.map((segment, i) => {
28+
const choice = byKey.get(keys[i]!);
29+
if (!choice || !['Ambiguous', 'Unplanned'].includes(segment.row)) return { ...segment };
30+
if (choice.action === 'accept') return { ...segment, row: 'Accepted' };
31+
if (!plan.items.some(item => item.id === choice.item)) throw new Error('Assigned item does not exist.');
32+
return { ...segment, row: choice.item! };
33+
});
34+
}
35+
export interface Approval { item: string; fingerprint: string }
36+
function fingerprint(item: PlanItem, segments: readonly Segment[], identity: PlanIdentity): string {
37+
return stable({ identity: identityKey(identity), item, segments: segments.filter(s => s.row === item.id).map(s => ({
38+
path: s.path, oldPath: s.oldPath, kind: s.kind, operation: s.operation,
39+
content: s.content, context: s.context, owners: [...s.owners].sort(),
40+
})) });
41+
}
42+
export function approveItem(plan: Plan, segments: readonly Segment[], itemId: string, identity: PlanIdentity, confirmNoChange = false): Approval {
43+
const item = plan.items.find(item => item.id === itemId);
44+
if (!item) throw new Error('Unknown item.');
45+
if (!segments.some(segment => segment.row === itemId) && !confirmNoChange) throw new Error('Confirm no change needed before approving.');
46+
return { item: itemId, fingerprint: fingerprint(item, segments, identity) };
47+
}
48+
export function approvalStates(plan: Plan, segments: readonly Segment[], approvals: readonly Approval[], identity: PlanIdentity): Record<string, 'unreviewed' | 'approved' | 'stale'> {
49+
const result: Record<string, 'unreviewed' | 'approved' | 'stale'> = Object.create(null);
50+
for (const item of plan.items) {
51+
const approval = approvals.find(approval => approval.item === item.id);
52+
result[item.id] = !approval ? 'unreviewed' : approval.fingerprint !== fingerprint(item, segments, identity) ||
53+
item.depends_on.some(dep => result[dep] === 'stale') ? 'stale' : 'approved';
54+
}
55+
return result;
56+
}

‎core/identity.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
/** Stable IDs from trusted application storage, never model output or UI selection. */
2+
export interface PlanIdentity { repositoryId: string; taskId: string; planId: string }
3+
export function identityKey(identity: PlanIdentity): string {
4+
const values = [identity?.repositoryId, identity?.taskId, identity?.planId];
5+
if (!values.every(v => typeof v === 'string' && v.length > 0)) throw new Error('Stable repository/task/plan identity is required.');
6+
return JSON.stringify(values);
7+
}

0 commit comments

Comments
 (0)