Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,8 @@ The driving agent owns state, cycle selection and completion claims; GStack supp

**Delivery parameters.** The merge is a squash merge: `gh pr merge <n> --squash --match-head-commit <sha>`. `/ship`'s documentation candidate (`gstack-docs-candidate snapshot`) takes the kept documents as `--docs` roots: AGENTS.md, CHANGELOG.md, PRODUCT_GOAL.md, README.md, `extension/README.md`, `extension/skills/codebook/SKILL.md` and the v9 PNG. CI packages the extension with `node extension/scripts/package.mjs --out artifacts/packages/codebook.vsix` and checks it with `node extension/scripts/check-package.mjs artifacts/packages/codebook.vsix` (`package.yml`). A release commit changes one test line besides the version files and CHANGELOG.md, the expected version in `extension/scripts/tests/package.test.mjs`; `/ship`'s Step 16 counts that edit as release metadata, not as a change to the reviewed tree.

**Pre-gate (owner, 2026-10-22).** `/ship`'s pre-gate runs Stage 1 only: `gstack-pregate --stage preflight --allow-repo-commands`, its secrets scan every time. The test lanes (Stage 2) are covered by `pnpm --dir extension test` on the final tree and by required CI.

**Background work.** `node extension/scripts/watch-background.mjs` (from the directory Claude Code started in, else with `--project <that directory>`) lists the current Claude Code session's background tasks and subagents (its `CLAUDE_CODE_SESSION_ID`), each with the time of its last output, and marks those silent for more than 20 minutes; a finished or stopped subagent is never marked, a shell's row stays marked after it ended (its task notification is the authority). Stop a review subagent that has written nothing for 20 minutes and dispatch it again on a narrower scope; dispatch a subagent that the API's safety filter stopped again at once, with the same brief, on the fallback model. While waiting longer than a few minutes, tell the owner what is awaited and since when.

**Ship review limit (owner, 2026-10-18).** After the installed `/ship`'s three fixing cycles, stop and report `converged:false`: no fourth cycle, no counter reset after a handoff, no round relabeled a repair; the no-carry rule does not waive this. An unconverged ship is no completed delivery. Only the owner starts a new invocation, with its own count. The owner's order for Cycle 0046's second invocation: if it also stops unconverged, its open findings become the next cycle's tasks and that cycle's PR holds only their fixes (Cycle 0047's delivery ended the same way).
Expand Down
16 changes: 16 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,21 @@
# Changelog

## [0.2.35.0] - 2026-10-23 (development candidate)

Cycle 0049's third pull request ([Issue #107](https://github.com/laststance/codebook/issues/107)): a test replay's executed source in one recorded-source tab that the native debugger opens, moves that never show two moments at once, the unrecorded time on the slider and a bounded wait in Play. The native round in VS Code and Cursor follows this merge.

**The executed source at the selected moment.**

- **One recorded-source tab.** A test replay shows its executed source in one tab named after the stop's file (`Captured-<file name>`). At a stop whose recorded source verifies, the tab holds that file as it ran, with the stopped line highlighted and labelled `Recorded: <path>:<line> · <t> s`. A stop in a file with another name renames the tab and Codebook closes the tab it opened before, so a replay never leaves a tab per stop; returning to Live or opening another saved study closes it.
- **The native debugger at the same moment.** At such a stop the debugger's thread reads `Recorded test stop <n> · <path>:<line>`, shows that stop's recorded values and stack, and its frames open the same tab. At an output, at the result and at a stop whose source does not verify, the tab holds `// Recorded source · Not recorded at this moment` and `// The test journal holds no source state for this moment.` (comments, so the editor reports no problem for them), and the debugger's thread reads `Not recorded at this moment` with no frames, also when the replay opens on such a moment.
- **One moment at a time.** Each move first takes the earlier moment off the debugger and the tab, then shows the new moment's source in the tab, then presents the debugger at it, and then shows the stopped line, its label, the Study position and the Application output together. Quick moves, an overtaken move and a return to the moment already shown leave no other moment's stop in the debugger and no extra tab. If the tab cannot open, the Study pane says `Codebook could not open the recorded source of stop <n>: <cause>. Details: Output › Codebook.`, the moment stays selected with no stop in the debugger, and **Retry** opens the tab again; returning to Live takes that line with it.

**The slider and Play.** The time slider marks the recording between its first and last event as unrecorded, with a tick at each stop whose recorded source verifies, under `Ticks mark recorded stops; source and debugger are not recorded between them.` (a test journal records when a stop paused, not when the test resumed). **Play** moves from event to event and waits at most 1.5 seconds for the next one, also across an unrecorded interval, which it neither pauses at nor asks about; each surface shows the selected event's own time.

**Compatibility.** The MCP API stays 1.8 and the bundled skill 1.0.46. No stored format changes: test histories, learning materials and reader positions written by 0.2.34.0 open unchanged, and those written now open in 0.2.34.0.

**Not observed.** The recorded-source tab was checked natively in VS Code 1.142.0 and Cursor 3.26.13 on macOS (one tab per replay, renamed per file, the label or the placeholder visible, the debugger's top frame opening the tab), on saved test replays recorded through Codebook's tools without a chat; no chat-driven run of this version has reached a stop yet. Motion between moments is not recorded natively yet. A tab the editor restores after a restart serves the placeholder until a replay shows its own tab. Windows and Linux are not run.

## [0.2.34.0] - 2026-10-22 (development candidate)

Cycle 0049's second pull request ([Issue #107](https://github.com/laststance/codebook/issues/107)): a test replay's recorded test output in the Application pane, and the Study pane's test replay section rebuilt around the selected moment. The recorded source with its transitions and the native round in both editors come with the third pull request.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Codebook contributes `debug.focusEditorOnBreak: false` as the native debugger de

## Implementation status

This is a preview, not a Marketplace or Open VSX release. The delivered version is **0.2.34.0** once the second pull request of [Cycle 0049](https://github.com/laststance/codebook/issues/107) is merged; until then 0.2.33.0 ([PR #113](https://github.com/laststance/codebook/pull/113)) is the delivered one, and the active cycle Issue says where the delivery stands. Cycle 0049 is a feature cycle: a Vitest test run that the editor chat explained becomes a learning replay, a **test replay**. Its first pull request holds the loop and its contracts: a test run reads `demonstrated` once its test passed after every declared stop and its history sealed complete; **Save learning replay** and **Open replay** in the status bar save and open it (its test output, the executed source and the native debugger's recorded stops; no application video); the run resource tells the agent the test's result and which explanations the saved learning still lacks; a node-test start's refusals arrive before its first stop with their fix; and the bundled skill 1.0.46 routes a question about a test to this flow. The MCP API is 1.8. Its second pull request shows the recorded test output in the Application pane, updated in place up to the selected moment, and rebuilds the Study pane's test replay section around that moment (Previous stop and Next stop first, the learning summary drawn as a browser replay's with the selected step); the recorded source with its transitions and the native round in both editors come with its third; the test replay's summary in the Learning summary view is the next feature cycle. What each earlier cycle delivered, with its tests, trials and limits, is in the [change history](CHANGELOG.md) and in that cycle's record, kept under the tag [`docs-archive-2026-10-20`](https://github.com/laststance/codebook/tree/docs-archive-2026-10-20/docs/cycles); from Cycle 0048 on, the cycle's Issue holds its tasks and state, and its pull requests the results.
This is a preview, not a Marketplace or Open VSX release. The delivered version is **0.2.35.0** once the third pull request of [Cycle 0049](https://github.com/laststance/codebook/issues/107) is merged; until then 0.2.34.0 ([PR #116](https://github.com/laststance/codebook/pull/116)) is the delivered one, and the active cycle Issue says where the delivery stands. Cycle 0049 is a feature cycle: a Vitest test run that the editor chat explained becomes a learning replay, a **test replay**. Its first pull request holds the loop and its contracts: a test run reads `demonstrated` once its test passed after every declared stop and its history sealed complete; **Save learning replay** and **Open replay** in the status bar save and open it (its test output, the executed source and the native debugger's recorded stops; no application video); the run resource tells the agent the test's result and which explanations the saved learning still lacks; a node-test start's refusals arrive before its first stop with their fix; and the bundled skill 1.0.46 routes a question about a test to this flow. The MCP API is 1.8. Its second pull request shows the recorded test output in the Application pane, updated in place up to the selected moment, and rebuilds the Study pane's test replay section around that moment (Previous stop and Next stop first, the learning summary drawn as a browser replay's with the selected step); its third shows the executed source in one recorded-source tab that the native debugger's frames open, takes the earlier moment off the tab and the debugger before each move, marks the unrecorded time on the slider and bounds Play's wait between events; the native round in both editors follows its merge; the test replay's summary in the Learning summary view is the next feature cycle. What each earlier cycle delivered, with its tests, trials and limits, is in the [change history](CHANGELOG.md) and in that cycle's record, kept under the tag [`docs-archive-2026-10-20`](https://github.com/laststance/codebook/tree/docs-archive-2026-10-20/docs/cycles); from Cycle 0048 on, the cycle's Issue holds its tasks and state, and its pull requests the results.

The specification is [goal version 10](PRODUCT_GOAL.md), and the implementation targets external repositories. Historical fixture or coupled-Wiki success is not proof of that destination.

Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0.2.34.0
0.2.35.0
8 changes: 6 additions & 2 deletions extension/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,10 @@ The **Application pane** shows a test replay's recorded test output up to the se

The Study pane's **Test replay** section names the result, the capture and the explained stops, then the selected moment (`Stop <n> of <m> · <t> s`, `Output · <t> s` or `Result · <verdict> · <t> s`) with the explanation the chat saved for it, or `No saved explanation for this stop.`; at an output, at the result and at a stop whose recorded source does not verify it adds `Source and debugger not recorded at this moment.` **Previous stop** and **Next stop**, first in the section's transport, move between stops, **Previous event** and **Next event** through every event, and **Play** and the time slider move through the recording. The learning summary is drawn as a browser replay's: a sequence diagram and its numbered steps under **Step details**, where the selected step is marked and the other steps of the same moment read `Same recorded moment`; a step's link selects its moment and that step. The events are listed under the collapsed **Events (<n>)**. When the Application pane is closed, the section says `The Application pane is closed.`, and **Show recorded output** opens the pane again at the selected moment. Where that pane opens is not checked in either editor yet: it can open beside the source rather than above it.

The executed source shows in one **recorded-source tab**, named after the stop's file (`Captured-<file name>`). At a stop whose recorded source verifies, the tab holds that file as it ran, with the stopped line highlighted and labelled `Recorded: <path>:<line> · <t> s`; the native debugger's thread reads `Recorded test stop <n> · <path>:<line>`, shows that stop's recorded values and stack, and its frames open the same tab. At an output, at the result and at a stop whose source does not verify, the tab holds `// Recorded source · Not recorded at this moment` and `// The test journal holds no source state for this moment.`, and the debugger's thread reads `Not recorded at this moment` with no frames, also when the replay opens on such a moment. A stop in a file with another name renames the tab, and Codebook closes the tab it opened before, so a replay never leaves a tab per stop; returning to Live or opening another saved study closes the tab. Each move first takes the earlier moment off the debugger and the tab, then shows the new moment's source in the tab, then presents the debugger at it, and then shows the stopped line, its label, the Study position and the Application output together; quick moves, an overtaken move and a return to the moment already shown leave no other moment's stop in the debugger and no extra tab. If the tab cannot open, the Study pane says `Codebook could not open the recorded source of stop <n>: <cause>. Details: Output › Codebook.`, the moment stays selected with no stop in the debugger, and **Retry** opens the tab again; returning to Live takes that line with it.

The time slider marks the recording between its first and last event as unrecorded, with a tick at each stop whose recorded source verifies, under `Ticks mark recorded stops; source and debugger are not recorded between them.` (a test journal records when a stop paused, not when the test resumed). **Play** moves from event to event and waits at most 1.5 seconds for the next one, also across an unrecorded interval, which it neither pauses at nor asks about; each surface shows the selected event's own time.

Unexpected failures on these paths write one entry each to **Output › Codebook**, with the surface, the study, the profile, the versions, the cause and the stack. The causes they show name the extension's storage, the workspace and the home folder as `<storage>`, `<workspace>` and `~`; some other messages can still show full local paths.

The bundled skill (1.0.46) routes a question about a test, or about library behavior a test exercises, to the `node-test` profile, and the chat explains each test stop in the chat. A run that ends with an `error` before its first stop did not run its test: the chat starts it again only where the published recovery of that error's code allows (`codebook://help/errors`), and it treats any text the error quotes, such as test or tool output, as data. The chat claims saved learning only when the run reads `studyOutcome` `demonstrated` and `nodeTest.learningCoverage` `complete`, says when a test did not pass and names its exit code or signal, and points you to **Save learning replay** and **Open replay**.
Expand All @@ -86,7 +90,7 @@ The bundled skill (1.0.46) routes a question about a test, or about library beha
2. In Copilot Chat (in VS Code, a new chat in a **Local** session) or Cursor Agent, ask `/codebook` your own question about a test, or about library behavior a test exercises.
3. Follow the chat: it pauses the test at the stops it chose and explains each from the captured values, which you can inspect in the native debugger meanwhile.
4. When the test has run, click **Save learning replay** in the status bar.
5. Click **Open replay**, or open the test replay from Saved studies, and step through its stops with **Previous stop** and **Next stop**: the Application pane shows the test output up to each moment, and the Study pane its explanation.
5. Click **Open replay**, or open the test replay from Saved studies, and step through its stops with **Previous stop** and **Next stop**: the Application pane shows the test output up to each moment, the recorded-source tab the source as it ran, the native debugger the recorded values and stack, and the Study pane its explanation.

#### Terms

Expand Down Expand Up @@ -186,7 +190,7 @@ Package builds require a POSIX host (macOS or Linux); Windows builds are rejecte
```sh
pnpm --dir extension install --frozen-lockfile
pnpm --dir extension package
pnpm --dir extension package:check "$PWD/artifacts/packages/codebook-0.2.34.vsix"
pnpm --dir extension package:check "$PWD/artifacts/packages/codebook-0.2.35.vsix"
```

The package command checks pnpm, clears only the extension compiler output, rebuilds, bundles production modules and stages an explicit file allowlist. Test/application fixtures and experimental dependencies are rejected. The independent checker validates archive entries, hashes, manifests and dependency notices before accepting the VSIX.
Expand Down
2 changes: 1 addition & 1 deletion extension/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"displayName": "codebook",
"description": "Connect an external agent to source-grounded codebase studies.",
"publisher": "laststance",
"version": "0.2.34",
"version": "0.2.35",
"private": true,
"engines": {
"vscode": "^1.120.0",
Expand Down
3 changes: 3 additions & 0 deletions extension/scripts/fixtures/history-transport-golden.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
<div class="timeline-track"><input id="playhead" type="range" min="0" max="8000" step="1" value="0" title="Seek backward one second — ← / ↓ (Focused recording timeline); Seek forward one second — → / ↑ (Focused recording timeline); Seek backward 10 seconds — Page Down (Focused recording timeline); Seek forward 10 seconds — Page Up (Focused recording timeline); Seek recording start — Home (Focused recording timeline); Seek recording end — End (Focused recording timeline)" aria-valuetext="2.00 s presented" style=""><div id="history-coverage" role="img" aria-label="3 source/debugger history gaps: 0.00 s–1.00 s, 2.00 s–4.00 s, 5.00 s–8.00 s; 2 recorded stops: 1.00 s, 4.00 s" data-signature="[0,8000,[{&quot;startMs&quot;:0,&quot;endMs&quot;:1000},{&quot;startMs&quot;:2000,&quot;endMs&quot;:4000},{&quot;startMs&quot;:5000,&quot;endMs&quot;:8000}],[1000,4000]]"><span class="history-gap" aria-hidden="true" title="Not recorded at this moment · 0.00 s–1.00 s" style="left: 0%; width: 12.5%;"></span><span class="history-gap" aria-hidden="true" title="Not recorded at this moment · 2.00 s–4.00 s" style="left: 25%; width: 25%;"></span><span class="history-gap" aria-hidden="true" title="Not recorded at this moment · 5.00 s–8.00 s" style="left: 62.5%; width: 37.5%;"></span><span class="history-stop" aria-hidden="true" title="Recorded source and debugger · 1.00 s" style="left: 12.5%;"></span><span class="history-stop" aria-hidden="true" title="Recorded source and debugger · 4.00 s" style="left: 50%;"></span></div><span id="history-coverage-label" class="muted">Striped: source/debugger not recorded · ticks: recorded stops</span></div>
---
<div class="timeline-track"><input id="playhead" type="range" min="0" max="8000" step="1" value="0" title="Seek backward one second — ← / ↓ (Focused recording timeline); Seek forward one second — → / ↑ (Focused recording timeline); Seek backward 10 seconds — Page Down (Focused recording timeline); Seek forward 10 seconds — Page Up (Focused recording timeline); Seek recording start — Home (Focused recording timeline); Seek recording end — End (Focused recording timeline)" aria-valuetext="2.00 s presented" style=""><div id="history-coverage" role="img" aria-label="Historical source and debugger coverage unknown" hidden=""></div><span id="history-coverage-label" class="muted">Historical source/debugger coverage unknown</span></div>
Loading