Triage .scratch, docs/specs, docs/tickets before deleting them

[qcentic-adm]

Part of #6

Question

What, if anything, in .scratch/, docs/specs/ and docs/tickets/ is still load-bearing — and what gets promoted before they are deleted?

Deletion is decided; this ticket is the triage that makes it safe.

.scratch/ holds four spec folders and 39 ticket files for work that has already shipped: web-panel-extraction (12 issues), harness-installer (7), remote-core-write-path (7), detached-core (11). docs/specs/ and docs/tickets/ are the same kind of record from the same era.

Triage against a single test: does this document a decision or constraint that is still true, and is that fact recorded nowhere else — not in code, not in a test, not in an ADR, not in a comment? These specs were unusually detailed, so some of them are the only written record of why things are the way they are.

Deliver:

• The list of facts worth keeping, each with where it should land — an ADR, a docs page from the docs tree, or a code comment next to the thing it explains.
• The confirmation that everything else is genuinely redundant.
• The removal list, including the ## Historical working notes section of docs/agents/issue-tracker.md, which points readers at .scratch/ and must not outlive it.
• A check for any other in-repo reference to these paths — images-edge.yml currently has .scratch/** in its paths-ignore, and there will be others.

Bias toward deleting. Git history is the archive, and a promoted fact that turns out to be wrong is worse than one that has to be re-derived.

[qcentic-dev]

Triage complete — 5 facts to promote, 63 files to delete

Read all 63 files against the test: does this document a decision or constraint that is still true, and is that fact recorded nowhere else — not in code, not in a test, not in an ADR, not in a comment?

Almost nothing survives it. The twelve ADRs, CONTEXT.md, docs/domain-model.md, docs/ci-cd.md, INSTALL.md and — most of all — the code's own comments have already absorbed this material, often in better words than the specs used. Five facts fail the test. Everything else is redundant.

Exact inventory: .scratch/ is 38 files — 3 spec.md (harness-installer, remote-core-write-path, web-panel-extraction; detached-core has issues only) and 35 issue files. Plus docs/specs/ (12) and docs/tickets/ (12 + README.md). The ticket's "39 ticket files" is 35.

---

1. Facts worth keeping

K1 — The Panel owns no source-control surface → new ADR 0013

docs/specs/11-remove-worktree-and-git.md is the only written record that git left the Panel on purpose, and the only place the door is held shut.

The removal itself is well recorded — dropLegacyWorktreeSchema() in packages/shared/src/schema-bootstrap.ts:517, packages/panel/src/db/__tests__/drop-legacy-worktree-schema.test.ts. What is recorded nowhere is the forward constraint. docs/domain-model.md's non-goals list ("Not an IDE", "Not a prompt manager", "Not a memory system"…) has no git entry, and neither does its "What is no longer in the domain" list. Nothing in the repo stops the next contributor adding a branch chip.

Promote, from the spec's overview and ## Follow-ups / out of scope:

• Source-control decisions — which branch, which worktree, when to diff, when to push — belong to the tool the operator uses on the machine hosting the Harness, not to a remote control.
• The Harness may run git inside a session; that is the Harness's concern. This removes Panel visibility into git state, it does not constrain the Harness.
• If a "session is on branch X" pill is ever wanted, it re-enters as a session-metadata string reported by the Harness over core-link, never as a Panel-owned git probe.
• No per-task branch field. Branch routing, if ever needed, belongs in the Harness's session-spawn contract, not on the Panel's Task row.

Also add a Not a source-control UI row to docs/domain-model.md's non-goals, and worktree / git-diff / branch to its "no longer in the domain" list — that is where a reviewer looks.

K2 — One fixed look, copied from Actana Studio → new ADR 0014

docs/specs/12-adopt-studio-look.md has no ADR and is the sole record of the theming decision.

packages/panel/src/styles.css opens with "JetBrains Mono is the Panel's single face — the Studio look uses it for UI and terminal alike." That gestures at the decision without recording either the source of the tokens or that the look is fixed. grep -i 'actana studio' over all code and docs returns nothing outside the specs being deleted.

Promote:

• One canonical look. The only operator axis is dark / light, system-following. No accent picker, no tint slider, no background image, no interface or terminal font override, no interface zoom stepper.
• The tokens are copied from Actana Studio, not invented. Deviating from Studio's values reintroduces the "why do these look different?" problem the cutover exists to solve — so a new colour is a sync question, not a taste question.
• Explicitly not planned: per-project or per-Core theme override, and white-label brand hooks (Studio's NEXT_PUBLIC_BRAND_* surface is deliberately not ported).

Anchor a short comment at the @theme token block in packages/panel/src/styles.css pointing at the ADR — that is the file someone edits when they want to add a colour.

K3 — No code signing, and why that is safe → docs/ci-cd.md, plus a citation fix in install.sh

The strongest case in the set. grep -ri 'quarantine|xattr|gatekeeper' across every .ts, .mjs and .sh in the repo returns zero hits.

Today the fact lives in exactly two half-places:

• install.sh:295 — "the project publishes no signatures (spec: "No code signing")". That comment cites a file this ticket deletes.
• docs/harness-macos-prerelease-checklist.md:47 asserts the outcome ("No Gatekeeper dialog … that is a release blocker") without saying why no dialog is expected.

And ADR 0010 explicitly defers the question: "Signing questions may still apply to the Harness binary and must be re-raised in Harness distribution planning." They were raised and answered — in .scratch/harness-installer/spec.md and issue 04-macos-launchagent-ci.md.

Promote into docs/ci-cd.md § The release artifacts (which already covers the checksums but not this):

• Integrity is published checksums, verified by both install.sh and actana update — not signatures. No Apple notarization, no Windows Authenticode.
• This is safe because the curl | bash path never sets the com.apple.quarantine attribute, so Gatekeeper never intervenes. Revisit only if a browser-download distribution is ever added.
• Corollary that already cost one review cycle: do not add xattr -dr com.apple.quarantine to actana setup. A first cut did, defending against a tarball arriving by browser or AirDrop; it was rejected as scope creep against this decision.

Then repoint install.sh:295 at docs/ci-cd.md instead of "spec".

K4 — actana.ai is authoritative; actano.ai is a typo → one-line fix to ADR 0007

docs/adr/0007-scope-narrowing-and-rebrand.md:24 says the update-manager stub points at control.actano.ai. docs/specs/09-rebrand-and-auto-update.md:377 is the only place that resolves it: "Prior confusion between actano.ai and actana.ai … is resolved: actana.ai is authoritative."

Delete spec 09 and a live ADR keeps a misspelled domain with nothing to correct it. The sentence is doubly stale — electron/update-manager.ts went with Electron (ADR 0010) — so correct the spelling or strike the clause. Cheap either way; do it in the deletion PR.

K5 — The Terms of Service body still needs a legal review → a tracker issue, not a doc

packages/panel/src/components/views/TermsSettingsPage.tsx is still in the tree, still carrying a Terms body written for the upstream product with the product name string-replaced. Spec 09's Open Questions: "the language may need legal review under the new brand … do not ship publicly without a review pass."

Given the OSS launch is the current effort, this is live and flagged nowhere else. But it is an action item, not an architectural fact — so it belongs in GitHub, not an ADR. File it as its own issue before deleting spec 09.

---

2. Three near-misses I recommend dropping

Flagging these because they read as promotable and are not:

• Panel → Harness file transfer (spec 03). The decision is already in docs/domain-model.md:29-31 — "File transfer to a Harness will be a separate first-class feature designed later." The only unrecorded part is a checklist of dimensions the future spec must cover (transport, size caps, destination semantics). That is a to-be-designed list, not a decision; whoever writes that spec will re-derive it in ten minutes.
• Decommission the academy/pets-ws relay (spec 02). Another repo, an ops action, and the fork's pet subsystem is long gone. Not this repo's record to hold.
• Stale <!-- mc:recall:start --> markers in operators' CLAUDE.md (spec 04). Pre-launch, no users, and the spec itself concludes the marker text is harmless prose without the injector.

---

3. Confirmation that everything else is redundant

Grouped by what already holds it:

The twelve ADRs absorb the four .scratch/ efforts almost completely. detached-core → ADRs 0001–0005. harness-installer → 0003. remote-core-write-path → 0004. web-panel-extraction → 0010, 0011, 0012 (its own header says so: "decisions recorded in ADR 0010, 0011, 0012"). Specs 01–10 → ADRs 0006, 0007, 0008, 0009. Every "Considered Options / rejected" block I checked in the specs has a matching, usually fuller, block in its ADR.

CONTEXT.md and docs/domain-model.md hold the vocabulary and the scope boundaries: the full actana verb set, the linger step, the auto-start unit and its per-platform reach, the MC_* → AC_* rename, the removed-feature vocabulary list, and the scope-boundaries cheat sheet.

The code comments are the real reason so little survives. Repeatedly, the scratch note's rationale is already in the file it describes, in better shape:

Scratch note	Already at
"Idempotency is about the pairing, not the bytes"; material reissued only when --public-host changes because the old cert's SAN would not verify	packages/harness/src/actana-setup.ts:151-152
ProcessType=Interactive so a Core is not throttled as housekeeping	packages/harness/src/actana-launchd.ts:124-125
Reissue semantics	packages/harness/src/harness-cert-material.ts:59 (cites ADR 0003)
machinectl shell not docker exec (only the former makes a logind session); it always exits 0, so every script carries its own exit-status sentinel or "every assertion made through it is vacuous"; apt-get purge sudo makes "no sudo used" structural	scripts/lib/systemd-container.mjs:1-19,42-50 — verbatim, and better
The whole issue-02 / issue-06 acceptance list	the header comment of scripts/e2e-actana-setup-linux.mjs
Nine removal-spec rationales	packages/shared/src/schema-bootstrap.ts:460-531, one self-contained comment per drop

Tests hold the rest. drop-legacy-worktree-schema.test.ts and its siblings, install-sh.test.mjs, e2e-actana-setup-{linux,macos}.mjs, smoke-panel-image.mjs.

Already-shipped docs hold the operator-facing half: INSTALL.md (one-liner, checksum verification, linger, every verb, troubleshooting), docs/ci-cd.md (release artifacts, tags, native-runner rationale, smoke-as-acceptance), docs/harness-macos-prerelease-checklist.md and docs/harness-linux-rehearsal.md (exactly the "CI cannot reboot a runner" seam the installer spec's testing section called for), deploy/dev/README.md (Core-in-a-box).

And a large slice is not merely redundant but void — it describes code that no longer exists. All 12 docs/tickets/ files are Electron-era implementation breakdowns (electron/main.ts, electron/preload.ts, src/server/, electron-builder, notarization, AC-09-01 — Stub electron/update-manager.ts). remote-core-write-path/spec.md is a root-cause analysis of an Electron-ABI better-sqlite3 binding bug that cannot recur — ADR 0010 removed the Electron ABI. The three .scratch/ spec.md files each open with a Status line (ready-for-agent, needs-triage) for work that shipped months ago.

---

4. Removal list

63 files.

• .scratch/ — all 38 files, whole directory:
  • detached-core/issues/01–11 (11)
  • harness-installer/spec.md + issues/01–07 (8)
  • remote-core-write-path/spec.md + issues/01–07 (8)
  • web-panel-extraction/spec.md + issues/01–10 (11)
• docs/specs/ — all 12 (01-remove-whisper.md … 12-adopt-studio-look.md)
• docs/tickets/ — all 13 (12 + README.md)
• docs/agents/issue-tracker.md — the ## Historical working notes section, lines 37–42 (heading + the three-line body + separator). It exists to point readers at .scratch/; it must not outlive it.

⚠️ Sequencing. ## Historical working notes is not in main at 087b550 — it only exists in the in-flight rewrite of issue-tracker.md (the GitHub-tracker version, presumably #15's work). Same for docs/README.md and .github/workflows/images-edge.yml, both still untracked. The deletion PR has to land after those, or three of the edits below have nothing to edit.

---

5. Every in-repo reference to these paths

Swept the whole tree. Ten sites, seven of them outside the doomed directories. images-edge.yml was one of eleven.

Workflows / build config

1. .github/workflows/images-edge.yml:22 — ".scratch/**" in paths-ignore. Drop the line. Note "**.md" and "docs/**" are already in the same list, so docs/specs and docs/tickets need no change there — .scratch/** is the only dead entry.
2. .dockerignore:25 — .scratch. Drop the line (harmless once the directory is gone, but dead).

Code — the one that actually matters

3. packages/shared/src/schema-bootstrap.ts — nine comments citing a docs/specs/ path, at lines 460, 466, 474, 483, 492, 501, 510, 518, 527. Each comment is otherwise self-contained and worth keeping; only the citation dies. Repoint:

   Line	Subject	New citation
   460	pet	ADR 0007
   466	voice / Whisper	ADR 0007
   474	convenience surfaces	ADR 0007
   483	recall / memory / code graph	ADR 0007
   492	bundled skills	already cites ADR 0006 — just drop the path
   501	IDE-adjacent	ADR 0007
   510	sandbox	already cites ADR 0009 — just drop the path
   518	worktree / git	new ADR 0013 (K1)
   527	studio look	new ADR 0014 (K2)

   Worth noting how this falls out: the two comments left with nothing to point at are exactly the two specs with no ADR. K1 and K2 are not tidying — they are what keeps these two comments meaningful.

4. install.sh:295 — the project publishes no signatures (spec: "No code signing"). Repoint at docs/ci-cd.md per K3.

Docs

5. docs/README.md:88-89 — the specs/ and tickets/ bullets under ## Historical record. Remove both. The section still has upstream/, refactor-plan.md and session-orchestrator-brief.md, so keep the heading.
6. docs/agents/issue-tracker.md:39 — inside the ## Historical working notes section already on the removal list.
7. docs/adr/0007-…:19 — "See docs/specs/." Strike the sentence's trailing pointer; the ADR stands without it. (Same PR, fix actano.ai at line 24 per K4.)
8. docs/adr/0009-…:17 — "Removal spec 10 (docs/specs/10-remove-sandbox.md) lands as a single PR…". Rewrite without the path.
9. docs/refactor-plan.md:4 — the staleness banner cites docs/specs/10-remove-sandbox.md. Reduce to "ADR 0009". (Separately: that whole file describes src/server/, electron/, mc-agent/ — a tree layout that no longer exists. Whether it survives at all is a bigger question than Triage .scratch, docs/specs, docs/tickets before deleting them #17; flagging, not scoping.)
10. docs/upstream/ — four files link ../specs: DIVERGENCE.md:5, PROVENANCE.md:4, PROVENANCE.md:79, BACKLOG.md:4. Convert each to an ADR reference. Also PROVENANCE.md:24 describes a working tree with "5 in-flight issue-note/ADR files under .scratch/" — a snapshot of a moment in 2026-07, not a link; leave it or strike the clause.

Self-references inside the doomed set (die with their files, listed for completeness): docs/specs/01:417, 07:68, 09:182, 09:371, 12:444; docs/tickets/04:416, 07:62, 10:347, 11:336.

---

6. Suggested landing order

1. File the Terms legal-review issue (K5) — the only item whose home is outside the repo.
2. Land ADR 0013 (K1) + the domain-model.md non-goal rows, and ADR 0014 (K2) + the styles.css comment.
3. Land the docs/ci-cd.md signing paragraph (K3) and repoint install.sh:295.
4. Delete the 63 files and the ## Historical working notes section; in the same PR fix all ten references, including the nine schema-bootstrap.ts citations and the actano.ai typo (K4).

Steps 2–3 must precede step 4, so no citation is ever dangling at a commit boundary.

Nothing deleted yet — that is the implementation ticket.