The repos-directory auto-scan is removed; dashboard "Add project" is the only onboarding path (fix #1600)

[suleimansh]

🤖 agent PR

Reshaped per the review discussion below: the repos-directory auto-scan turned out to be too aggressive once it ran the installer (which commits) in every repo under the directory — so instead of hardening it, this PR deletes it. The dashboard's "Add project" is the only onboarding path, and it already installs before registering, so every onboarded repo gets the framework's self-ignoring .the-framework/.gitignore before any agent can git add -A framework state onto a work branch (the #1600 bug).

Removed (feature #1123, row 4 of FEATURES-SPEC.md):

• registerReposDirectory and the boot-time scan in src/daemon.ts
• the repos-directory.ts module and its tests/SPECs
• the reposDirectory / reposDirectoryAutoGrant preferences (src/registry.ts) and their tests

Kept — the two independent fixes from #1600's instances 2 and 3:

1. Activation means the ignore file, not the directory. isActivated (src/project.ts) now reads the same marker install's own no-op check reads: .the-framework/.gitignore. A .the-framework/ directory something else created can no longer read as activated forever while the repo still lacks the ignore file.
2. The repo-root branches symlink is hidden from git at creation. reconcileBranchLinks (src/branch-links.ts) applies the same repo-level exclude pair as All framework data moves to the tf-data branch (fix #1582) #1595's tickets link (/branches + !/branches/, so a user's own branches directory keeps committing).

Tests: the repos-directory and preference tests are gone with the feature; the activation tests moved to the ignore-file marker (daemon tests fake activation by writing it); the root-symlink test asserts the exclude pair fires at creation and never for a user's own entry. Full suite green (1498 node + 772 dashboard).

SPEC updates (want a human read-through — walkthrough in the comments): FEATURES-SPEC.md, project.SPEC.md, daemon.SPEC.md, branch-links.SPEC.md, the two test SPECs, and the two deleted repos-directory SPECs.

[suleimansh]

🤖 agent comment

A plain-language walkthrough of the five SPEC changes in this PR, for the human read-through:

1. project.SPEC.md — what "activated" means changed

• Before: "A repo counts as activated when the framework's marker directory exists."
• Now: activated means the ignore file the install writes exists — the file that keeps the framework's transient state off the repo's branches.
• Why: this is the core of the bug. The old rule meant that if a .the-framework/ folder existed for any reason, the framework said "this repo is set up" and never installed the ignore file — so agents committed framework junk onto the repo's branches forever. The new rule ties "activated" to the one file that actually matters.

2. daemon.SPEC.md — one new bullet about auto-added repos

• Added: an auto-registered repo is installed before it is registered (the same install as the dashboard's "Add project"), and a repo that cannot be installed is skipped rather than registered half-set-up.
• Why: this is new behavior. Previously the daemon's auto-scan just added repos to the list without setting them up (the Auto-onboarded repos never get .the-framework/.gitignore, so agents sweep framework state onto work branches #1600 bug). The daemon now does something extra at boot, so its spec has to say so — including the failure rule.

3. branch-links.SPEC.md — one new bullet about the root shortcut

• Added: the root branches shortcut is hidden from git the moment it is made; a user's own branches folder is never hidden.
• Why: the shortcut is a symlink the framework creates. Before, git saw it as a new untracked file, so any sweeping git add -A would commit it. The second sentence matters too: hiding a user's real files from git status would be a nasty surprise, so we only ever hide our own link.

4. branch-links.test.SPEC.md — the coverage sentence grew

• Now also says the shortcut is "hidden from git at creation (while an occupied path stays visible)".
• Why: test SPECs list what the tests prove. New tests prove the hiding behavior (and that a user's own entry is left visible), so the sentence had to grow to match.

5. daemon.test.SPEC.md — same idea, for the daemon tests

• Now also says "(auto-added repos are installed first, and a failed install skips the repo)".
• Why: same as 4 — new tests exist for install-before-register and skip-on-failure, so the coverage description says so.

Short version: changes 1–3 describe the new behavior, changes 4–5 keep the test-coverage summaries honest. All five follow from one sentence: a repo must get its protective ignore file before any agent touches it, and the framework's own root symlinks must never ride a commit onto your branches.

[brillout]

A concern I have is that it would be too aggressive. If I add ~/code I'd be mad that TF installed itself to all repos without my permission. Or am I misunderstanding how it works?

[brillout]

How about we skip the whole "add all repos in directory" feature for now?

[brillout]

And focus on the core USPs instead

[suleimansh]

It is opt-in (reposDirectoryAutoGrant, off by default) — but with this PR the opt-in got heavy: it runs the installer in every repo under the directory, and the installer makes commits. So agreed, too aggressive.

+1 to dropping it. I'll reshape this PR: delete the auto-scan, keep the two independent fixes (activation = the ignore file, hide the root branches symlink from git). Dashboard "Add project" stays the only onboarding path.

[suleimansh]

🤖 agent comment

SPEC walkthrough for the reshaped PR (supersedes the walkthrough above, which described the now-deleted auto-scan changes). Per modified SPEC file: where it sits, the diff, and why.

---

1. FEATURES-SPEC.md — the feature list, one row per user-facing feature; the numbers are stable ids.

 | 3 | Activate a repo from the dashboard (commits dirty state, creates `.the-framework/`, teaches `.gitignore`, registers it) |
-| 4 | Auto-register every repo under a configured "repos directory" |
 | 5 | Onboarding checklist — each step derived from a real fact, not a click |

The feature is gone, so its row goes. Row 4 stays a gap rather than renumbering everything after it — the numbers are referenced elsewhere as ids (the file already has 124 sitting out of order for the same reason).

---

2. project.SPEC.md — intro: "Read-only project helpers: whether a repo has The Framework installed, what its detection signals are, …". Its TLDR's first bullet defines what "activated" means.

-- A repo counts as activated when the framework's marker directory exists; creating it is a separate concern.
+- A repo counts as activated when the ignore file the install writes exists — the file that keeps the framework's transient state off the repo's branches. That way a repo can never look activated while it still lacks the one protection activation is about; writing it is a separate concern.

This is kept fix 1 and the core of #1600: under the old rule, a .the-framework/ directory created for any reason made the repo read as "set up" forever, so the ignore file was never installed and agents committed framework state onto work branches. The new rule ties "activated" to the one file activation is actually about.

---

3. daemon.SPEC.md — intro: "The process behind the dashboard: it serves the UI, spawns agents, and runs the background services." The TLDR bullet about what happens at boot changes:

-- At boot it registers the home project (and, when opted in, every repo in the user's repos directory), marks agents a dead process left "running" as stopped, and starts the background services. It resumes nothing: Ctrl-C was deliberate.
+- At boot it registers the home project, marks agents a dead process left "running" as stopped, and starts the background services. It resumes nothing: Ctrl-C was deliberate. Every other project joins through the dashboard's "Add project" — the one onboarding path, so a repo is always installed before an agent can touch it.

The parenthetical described the deleted auto-scan. The added sentence states the invariant the deletion buys: with a single onboarding path that installs before registering, no repo can be registered without its ignore file.

---

4. daemon.test.SPEC.md — a one-sentence file listing what the daemon tests prove.

-… event-log tailing, home-project and repos-directory registration rules, and starts over the dashboard …
+… event-log tailing, home-project registration rules, and starts over the dashboard …

The repos-directory registration tests are deleted with the feature, so the coverage sentence stops claiming them.

---

5. branch-links.SPEC.md — intro: "Keeps every session checkout reachable by its branch name: new checkouts live in .the-framework/branches/ …, and a branches shortcut at the repo root points there." One TLDR bullet added:

 - A session on a branch whose name cannot be a folder name (old slashed names) simply gets no link.
+- The `branches` shortcut at the repo root is hidden from git the moment it is made — it is the framework's, and left visible it would ride any sweeping commit onto a work branch. A user's own `branches` folder is never hidden.

This is kept fix 2. The symlink is framework-created; before, git saw it as a new untracked file at the repo root, so any sweeping git add -A committed it. The second sentence is the guard rail: a user's own real branches directory is never hidden from their git status.

---

6. branch-links.test.SPEC.md — a one-sentence file listing what the branch-links tests prove.

-… the repo-root shortcut is created once without clobbering, and the daemon pass visits every project.
+… the repo-root shortcut is created once without clobbering and hidden from git at creation (while an occupied path stays visible), and the daemon pass visits every project.

New tests prove the hiding behavior and that a path occupied by the user's own entry is left visible, so the coverage sentence grows to match.

---

7. repos-directory.SPEC.md + repos-directory.test.SPEC.md — deleted whole, with the module and its tests. They described only the auto-scan's directory listing ("Finds the git repositories sitting directly inside the directory the user keeps their repos in, so the daemon can auto-register them when that opt-in is on"). Note the dashboard's "Add project → It's a folder of repos" is untouched: it uses its own listing in install.ts, not this module.

Short version: 1, 3, 4 and 7 remove the feature from the record; 2 and 5–6 describe the two kept fixes. All of it follows from one sentence: a repo must get its protective ignore file before any agent touches it, and the framework's own root symlink must never ride a commit onto your branches.

[suleimansh]

Done — auto-scan deleted (prefs + FEATURES row 4 with it), the two fixes kept: activation = the install-written ignore file, root branches symlink git-excluded at creation. "Add project" is the only onboarding path; its "folder of repos" mode is separate code and untouched. SPEC walkthrough in the comments.

Dogfooded live: a repo with a pre-existing bare .the-framework/ dir installs correctly, activation flips with the ignore file in both directions, and git add -A stages nothing. Suite green (1498 + 772).

@brillout ready for another look.

[brillout]

Good