docs: design review, decision log, and file-based task system - #506
Merged
nichochar merged 1 commit intoJul 29, 2026
Merged
Conversation
Copy link
Copy Markdown
Contributor
Sorry, something went wrong.
Groundwork for restarting the project. Three additions, no code changes: - REVIEW.md: formal review of the prototype. Security findings verified against a running instance, the design forks worth reconsidering (execution model, .src.md grammar, session state ownership), and a code-quality pass. - DECISIONS.md: why the system is the way it is. Records the reasoning behind the choices that aren't obvious from the code, and flags which ones are under review. - tasks/: one markdown file per task, status in frontmatter, no tooling. Seeded with the ten tasks the review turned up.
nichochar
force-pushed
the
docs/project-memory
branch
from
b0af817 to
ea93a9b
Compare
July 29, 2026 15:24
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Groundwork for restarting the project. No code changes — three new documents plus a task directory.
What's here
REVIEW.md — a formal review of the prototype. Three parts: security, design forks worth reconsidering, and a code-quality pass.
DECISIONS.md — why the system is the way it is. Ten entries covering the choices that aren't recoverable from reading the code, each with what it buys and what it costs. Statuses (active / under review) flag which ones are still open.
tasks/ — one markdown file per task, status in frontmatter moving TODO → IN_PROGRESS → DONE, no tooling. Seeded with the ten tasks the review turned up, ordered roughly by priority.
Headline finding
The "it runs locally" assumption is being treated as a security boundary, and it isn't one. Verified against a running instance:
The last one is what makes it remote code execution rather than disclosure: a page can list sessions over HTTP, then push cell:update + cell:exec. Reproductions are in REVIEW.md §1.
Two more found by reading and deliberately not exercised, because both are destructive: path traversal into fs.rm(recursive: true) via DELETE /api/srcbooks/:id, and shell injection through a cell filename that arrives from an imported .src.md.
Tasks 0001 and 0002 cover the fixes; PRs stacked on this branch.
Baseline health
Better than two years of dormancy would suggest — installs, builds, and passes its 11 tests cleanly on Node 24 with no changes. The architecture is coherent and the format instinct is right. What it needs is a security pass, a safety net, and one explicit decision about what kind of notebook it wants to be (task 0006).
🤖 Generated with Claude Code