Skip to content

chore: remove unreferenced scratch and unify repo structure - #133

Open
siracusa5 wants to merge 3 commits into
mainfrom
c/repo-cleanup-organization-d8d81c
Open

chore: remove unreferenced scratch and unify repo structure#133
siracusa5 wants to merge 3 commits into
mainfrom
c/repo-cleanup-organization-d8d81c

Conversation

@siracusa5

@siracusa5 siracusa5 commented Aug 11, 2026

Copy link
Copy Markdown
Collaborator

Summary

Repo cleanup: delete artifacts nothing referenced, then collapse the places where two conventions had grown side by side. 83 files, +692 / −7,095. Tracked size 17MB → 13.8MB, 587 files → 549. No engine behavior changes.

Deleted — all unreferenced, all scanned for secrets/PII first since this repo is public and deletion doesn't undo exposure (nothing found but fictional acme.com demo strings):

Path What it was
docs/review-assets/ 2.9MB of screenshots from three past PR reviews — 17% of the repo
apps/console/project/ Claude Design handoff bundle, including a diverged fork of apps/control-surface/
apps/console/chats/, mockups/ Session scratch inside a shipped npm package
docs/archive/ Describes the product under its pre-rename name; points at a path deleted in #20
packages/core/bin/ A directory whose only file was a README reserving the directory
apps/okf-browser/ Superseded by the console and playground; referenced only by the docs listing it as existing

Two judgment calls that departed from a literal reading:

  • layers/context-cake/ was moved, not deleted. Equally unreferenced, but it's 204 lines of accurate architecture prose in valid OKF form. Now examples/self-layer/ with a manifest that resolves — referenced and demonstrable instead of orphaned.
  • apps/console/project/HANDOFF.md went too, despite being the one cited file there. Its entire body instructs coding agents to read chats/ and the .dc.html export, both now gone; keeping it would leave a live trap. The provenance fact it carried is one sentence in apps/console/README.md.

Structure

  • packages/core/package.json — packages/ promised packages; packages/core had no manifest. Now private, with an exports map, and explicitly not a workspace: declaring workspaces would force a root npm install and end the plain-Node guarantee that defines the engine. Imports stay path-based. Verified against electron-builder.yml, which ships src/ and fixtures/ but not this file.
  • packages/core/src/bin-shim.mjs — the nine root CLI wrappers were nine byte-identical copies of one 9-line block. Three lines each now. The process.argv[1] rewrite that makes usage strings name the real module is preserved, documented, and verified.
  • scripts/*.test.mjs → scripts/tests/, matching packages/core/tests/.
  • supabase/README.md names apps/desktop/ as owner. The directory stays at the root because the Supabase CLI resolves supabase/ from the invocation directory.

One finding deliberately dropped: moving generated signals.json / team-activity.json out of apps/control-surface/. The dashboard is served by python3 -m http.server --directory apps/control-surface, so the data must sit inside that directory to be fetchable. The two gitignore entries pointing into apps/ are the correct cost.

Docs

Six AGENTS.md files are now symlinks to CLAUDE.md. apps/site's pair were byte-identical; the root and console pairs had already drifted, so content unique to AGENTS.md merged into CLAUDE.md first — the no-root-install rule, CI / required as the sole gate, the app-v* tag namespace, the PORT-configurable playground test.

CLAUDE.md's Gotchas had grown longer than its Architecture section and read as an incident log. Every rule stayed, as an imperative with a link; the reasoning moved to five notes under docs/architecture/notes/. The abort-signal gap in github.mjs/mcp.mjs is now stated as a known gap rather than buried mid-paragraph.

Tests

npm test was a 32-command && chain on one line: no subsets, no partial runs, every failure after the first hidden. scripts/test.mjs groups the same 32 suites and adds --only / --bail / --list, reporting every failure with its rerun command. Suites stay sequential on purpose — several bind 127.0.0.1 or shell out to git.

npm run test:unit          # pure units
npm run test:integration   # sources, sync, servers
npm run test:slow          # indexing behaviour over time
npm test                   # everything, which is what CI runs

CONTRIBUTING.md also gains a note that an unset LANG makes BSD grep classify service.mjs and main.mjs as binary and return no matches rather than an error — a silent trap for contributors who navigate by search.

Affected area

  • Core engine / MCP / write path
  • Console
  • Site
  • Playground or local demo surfaces
  • Docs / specs / contributor workflow
  • Packs

Core/console/playground are checked for file layout and docs only — no runtime code changed except the CLI wrapper bodies.

Validation

  • npm test — 32/32 suites, 132.3s
  • npm --prefix apps/console run typecheck
  • npm --prefix apps/console test — 428 tests
  • npm --prefix apps/console run build
  • npm --prefix apps/site run build

Also: desktop npm test (104 tests) and npm run test:isolation, both pass. Every relative link in every edited doc resolves.

Desktop npm run smoke produces no output in a headless sandbox — Electron can't reach a window server. Confirmed identical on unmodified HEAD via a pristine worktree, so it's environmental, not a regression; CI runs it on a macOS runner.

Compatibility

  • Root commands still work, or the PR explains the migration path.
  • No root npm dependencies were added.
  • Generated files are ignored or intentionally committed.

All nine root commands verified working after the shim rewrite.

Sign-off

  • Every commit is signed off (git commit -s) per the DCO.

🤖 Generated with Claude Code

siracusa5 and others added 3 commits August 11, 2026 16:47
@siracusa5 @claude
chore: remove unreferenced scratch and unify repo structure
d5c6280 
The repo had accumulated a layer of one-time artifacts that nothing
referenced and no build read: 2.9MB of PR-review screenshots under
docs/review-assets/, a Claude Design handoff bundle under
apps/console/project/ (including a diverged fork of apps/control-surface/),
session scratch in apps/console/chats/ and mockups/, an archive doc still
describing the product under its pre-rename name and pointing at a path
deleted in #20, and packages/core/bin/ — a directory whose only content was
a README reserving the directory. apps/okf-browser/ went too: superseded by
the console and the playground, and referenced only by the three docs that
listed it as existing.

layers/context-cake/ was equally unreferenced but is real architecture
prose in valid OKF form, so it moved to examples/self-layer/ with a
manifest that resolves rather than being dropped.

Structure, where two conventions had grown side by side:

- packages/ promised packages but packages/core had no package.json. It has
  one now — private, with an exports map, and explicitly NOT a workspace,
  because declaring workspaces would force a root npm install and end the
  plain-Node guarantee that defines the engine. Imports stay path-based.
- The nine root CLI wrappers were nine byte-identical copies of the same
  9-line block. They now call runCoreCli() in packages/core/src/bin-shim.mjs
  and are three lines each; the process.argv[1] rewrite that makes usage
  strings name the real module is preserved and documented.
- scripts/ colocated its tests while packages/core/ kept them in tests/.
  Now both use tests/.
- supabase/ read like a first-class backend tier; a README names
  apps/desktop/ as its owner. It stays at the root because the Supabase CLI
  resolves supabase/ from the invocation directory.

Docs: six AGENTS.md files are now symlinks to their CLAUDE.md. apps/site's
pair were already byte-identical; the root and console pairs had drifted,
so the content unique to AGENTS.md (no-root-install, CI / required as the
sole gate, the app-v* tag namespace, the PORT-configurable playground test)
merged into CLAUDE.md first. CLAUDE.md's Gotchas had grown longer than its
Architecture section and read as an incident log; every rule stayed, as an
imperative with a link, and the reasoning moved to five notes under
docs/architecture/notes/. The abort-signal gap in github.mjs/mcp.mjs is now
stated as a known gap instead of buried mid-paragraph.

Tests: npm test was a 32-command && chain on one line — no subsets, no
partial runs, and every failure after the first was hidden. scripts/test.mjs
groups the same 32 suites (unit/integration/eval/release/slow), supports
--only and --bail, and reports every failure with the rerun command. Suites
stay sequential on purpose: several bind 127.0.0.1 or shell out to git.

CONTRIBUTING gains a note that an unset LANG makes BSD grep treat
service.mjs and main.mjs as binary and return no matches rather than an
error — a silent trap for contributors who navigate by search.

Verified: npm test 32/32; console typecheck + 428 tests + build; site build;
desktop 104 tests + engine isolation. Desktop npm run smoke needs a window
server and produces no output in a headless sandbox — confirmed identical on
unmodified HEAD, so it is environmental, not a regression.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: John Siracusa <siracusa5@users.noreply.github.com>
@siracusa5 @claude
fix: make --only fail loudly, and correct docs the cleanup left stale
fb50047 
Adversarial review of the cleanup itself. Three real defects, all
self-inflicted by the previous commit:

scripts/test.mjs treated `only` as a truthiness check downstream, so an
empty value skipped the filter instead of erroring. Both `--only` at the end
of argv (value undefined) and `--only=` (value "") therefore ran the entire
32-suite gate — the opposite of what was asked for, and slow enough that you
only notice two minutes in. Found by probing the argument surface rather
than by any test: the happy path `--only search` worked fine throughout.
Both spellings now exit 2 with a usable message.

CLAUDE.md still told readers the test suite was "the chain ... in
package.json", which the same commit had replaced with a runner. Now points
at scripts/test.mjs and lists the group commands.

docs/architecture/README.md referenced `docs/team-knowledge-system-handoff.md`.
That reference was already dangling before this branch — the file was
committed as docs/handoff.md and renamed to docs/archive/handoff.md, never
that name — but deleting docs/archive/ removed its nearest surviving
relative, so it now says plainly where the content went. Also adds a pointer
from the superseded design spec to the new notes/ directory, which nothing
linked to.

Checked and found clean, recorded so the next reader doesn't redo it:
- All nine root shims resolve their targets; usage strings still name the
  core module, not the wrapper.
- The desktop CLI resolves packages/core/src directly and never touches the
  root shims, so the shim rewrite is invisible to the packaged app.
- A concern about the AGENTS.md symlinks was disproved empirically rather
  than assumed: GitHub's contents API with application/vnd.github.raw
  resolves symlinks and returns all 22,668 bytes of CLAUDE.md, so a
  github/github-rest layer reading this repo ingests real content, not a
  10-byte target path. The git tree API does list them (mode 120000, type
  blob), which is what made this worth checking.
- 85 repo-relative markdown links resolve. The 112 apparent failures under
  apps/site/src/content are /-rooted Astro site routes, not filesystem
  paths.

npm test 32/32 after the fix. demo:verify passes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: John Siracusa <siracusa5@users.noreply.github.com>
@siracusa5 @claude
Merge main into the cleanup branch
1c6911f 
main moved ahead by four PRs while this branch was open. Three of them
interacted with it directly:

#131 added packages/core/tests/sidecar-state.test.mjs to the test chain. The
only conflict was package.json's "test" script — this branch replaced the
chain with scripts/test.mjs, so a mechanical "keep ours" would have silently
dropped that suite from the gate. It is registered now, and the runner grew
assertEverySuiteRegistered(): on a full run it walks packages/core/tests and
scripts/tests and refuses to start if a test file exists that no suite names.
The old chain had the same failure mode and no way to notice it.

#132 removed two stray NUL bytes from service.mjs and main.mjs — the actual
cause of the grep blindness this branch had documented in CONTRIBUTING as a
locale problem. That diagnosis was wrong: a NUL byte makes grep treat a file
as binary regardless of LANG, and both files now grep cleanly with LANG
unset. The section is corrected to name the real cause, and scripts/test.mjs
gained assertNoNulBytes() so a reintroduced NUL fails the gate instead of
quietly hiding a file from every search. #132 fixed the instances; nothing
stopped the next one.

#130/#129 touched console and desktop only and merged clean.

Also aligns packages/core/package.json's node floor with the root's new >=22.

Verified after the merge: npm test 33/33; console typecheck + 453 tests;
desktop 106 tests.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: John Siracusa <siracusa5@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@siracusa5