Enforce canonical root checkout semantics

Co-authored-by: Andrew <andrewxhill@gmail.com>

Author: andrewxhill-ai

.agent-hooks/guard_mainline_git.py

@@ -98,6 +98,8 @@ def main():
         "make commits there, then use `mq submit --check-only --json` and either "
         "`mq submit --wait --timeout 15m --json` or `mq submit --json` followed by "
         "`mq wait --submission <id> --for landed --json --timeout 30m`.\n"
+        "Keep /Users/devrel/Projects/recallnet/mainline clean on branch main; "
+        "that root checkout is the canonical protected checkout humans inspect.\n"
         "If you are the controller agent, use `mq land --json --timeout 30m` or let "
         "one machine-global `mainlined --all --json` drainer own registered repos.\n"
         "Allowed on main: read-only inspection and worktree creation. "

.agents/skills/worktree/SKILL.md

@@ -11,6 +11,7 @@ that work back through `mq`.
 The goal is simple:
 
 - `main` stays clean
+- the repo root checkout stays boring and trustworthy
 - each task gets its own worktree
 - all commits happen in the feature worktree
 - landing happens through `mq`, not manual merge into `main`
@@ -50,7 +51,7 @@ positive to work around. Move to a feature worktree and continue there.
 
 ### 1. Start from a clean protected branch worktree
 
-Use the canonical repo worktree as the protected branch worktree.
+Use the repo root checkout as the canonical protected branch worktree.
 
 Example:
 
@@ -64,6 +65,7 @@ Expected:
 
 - worktree is clean
 - branch is `main`
+- this root checkout is the one humans inspect and wrappers build from
 
 ### 2. Create a dedicated feature worktree
 
@@ -203,6 +205,8 @@ Expected:
 - `status --json` can correlate a succeeded submission to `publish_request_id`,
   `publish_status`, and `outcome`
 - `unmerged` is empty once the branch is truly reachable from protected `main`
+- `mq repo show` and `mq doctor` do not warn that the repo root checkout is
+  dirty or non-canonical
 
 ## Review and fix loop
 

AGENTS.md

@@ -5,11 +5,12 @@ instructions.
 
 ## Protected Main Worktrees
 
-- Treat `/Users/devrel/Projects/_wt/recallnet/mainline/protected-main` as the
-  canonical protected `main` worktree for this repo.
-- Treat `/Users/devrel/Projects/recallnet/mainline` as protected too unless you
-  have explicitly confirmed it is a disposable feature checkout. Do not assume
-  the root checkout is safe for feature commits.
+- Treat `/Users/devrel/Projects/recallnet/mainline` as the canonical protected
+  `main` checkout for this repo.
+- Treat `/Users/devrel/Projects/_wt/recallnet/mainline/protected-main` as a
+  protected mirror, not as the human-facing source of truth.
+- The root checkout must stay clean and on branch `main`. Humans inspect it,
+  wrappers build from it, and docs refer to it.
 - Do not use native mutating `git` commands from that worktree while on branch
   `main`.
 - Blocked examples: `git commit`, `git merge`, `git rebase`, `git push`,
@@ -31,6 +32,8 @@ instructions.
 - Controllers and factory-style daemons should prefer:
   - `mq land --json --timeout 30m`
   - or one machine-global `mainlined --all --json`
+- If `mq repo show` or `mq doctor` warns that the root checkout is dirty or not
+  canonical, fix that before trusting local binaries or local docs.
 - Plain `mq submit` now opportunistically tries to drain after queueing. If the
   integration lock is already held, it exits cleanly and the active worker keeps
   draining.

CONTRIBUTING.md

@@ -10,6 +10,7 @@
 ## Repo Workflow
 
 - treat `main` as protected
+- keep the repo root checkout clean on `main`; that is the canonical protected checkout humans inspect and wrappers build from
 - do feature work in a dedicated topic worktree
 - initialize new clones with `mq repo init`, commit `mainline.toml`, and run `./scripts/install-hooks.sh`
 - most agents should finish from a topic worktree with `mq submit --check-only --json` and `mq submit --wait --timeout 15m --json`

PLAN.md

@@ -57,6 +57,7 @@ Deliverables:
 - detect repo root from current directory
 - inspect worktrees and refs using `go-git`-backed repository access
 - identify canonical protected branch worktree
+- for ordinary repos, treat the repo root checkout as the canonical protected `main`
 - detect and model bare repo storage path separately from worktree path
 - config file support
 - `mainline repo init`

README.md

@@ -53,6 +53,7 @@ There is one rule that matters:
 
 Once that line is real, the rest follows:
 
+- the repo root checkout stays as the canonical protected `main`
 - feature work happens in topic worktrees
 - submissions are recorded durably
 - integration is serialized
@@ -208,6 +209,10 @@ That init commit matters. It turns the repo’s queue policy into versioned,
 reviewable state instead of one more local convention that agents have to infer.
 `mq repo init` also registers the repo for `mainlined --all`, so one machine
 daemon can drain many repos without one idle process per repo.
+For normal repos, the root checkout should be the canonical protected `main`.
+Keep it clean and boring. Humans inspect that path, and the machine wrapper
+builds `mq` and `mainlined` from it. If it is dirty, the wrapper should refuse
+to build rather than silently drift.
 
 ## The Core Commands
 

SPEC.md

@@ -297,6 +297,7 @@ MVP checks:
 
 - worktree clean
 - protected branch worktree clean
+- for ordinary repos, the repository root checkout should be the canonical protected `main` checkout that humans inspect and local wrappers build from
 - branch not already integrated
 - branch HEAD still matches submitted SHA unless `--allow-newer-head` is set;
   when that flag is set, newer queued branch heads are allowed only if the new

docs/FLOWS.md

@@ -49,6 +49,10 @@ mq doctor --repo /path/to/main
 mq status --repo /path/to/main
 ```
 
+For ordinary repos, `/path/to/main` should be the repo root checkout that
+humans inspect and local wrappers build from. Keep that checkout clean and on
+the protected branch. Topic worktrees are where feature edits belong.
+
 Submit from any linked worktree in the same repo:
 
 ```bash

docs/install.md

@@ -65,6 +65,12 @@ git commit -m "Initialize mainline repo policy"
 
 `mq repo init` automatically registers the repo for the machine-global daemon
 registry used by `mainlined --all`.
+For ordinary repos, treat that root checkout as the canonical protected `main`.
+Keep it clean and on `main`, because humans inspect it and the machine wrappers
+build from it.
+The machine-level `mq` and `mainlined` wrappers refuse to build from a dirty
+root checkout so local binaries cannot silently drift away from the code humans
+are reading.
 
 State compatibility:
 

internal/app/registry.go

@@ -1,6 +1,7 @@
 package app
 
 import (
+	"bytes"
 	"encoding/json"
 	"errors"
 	"os"
@@ -61,7 +62,13 @@ func loadRegisteredReposFromPath(path string) ([]registeredRepo, error) {
 
 	var registry registryFile
 	if err := json.Unmarshal(data, &registry); err != nil {
-		return nil, err
+		sanitized, sanitizeErr := firstJSONObject(data)
+		if sanitizeErr != nil {
+			return nil, err
+		}
+		if unmarshalErr := json.Unmarshal(sanitized, &registry); unmarshalErr != nil {
+			return nil, err
+		}
 	}
 	sort.Slice(registry.Repositories, func(i, j int) bool {
 		return registry.Repositories[i].RepositoryRoot < registry.Repositories[j].RepositoryRoot
@@ -131,3 +138,43 @@ func canonicalRegistryPath(path string) string {
 	}
 	return filepath.Clean(path)
 }
+
+func firstJSONObject(data []byte) ([]byte, error) {
+	trimmed := bytes.TrimSpace(data)
+	if len(trimmed) == 0 || trimmed[0] != '{' {
+		return nil, errors.New("registry does not start with json object")
+	}
+
+	depth := 0
+	inString := false
+	escaped := false
+	for i, b := range trimmed {
+		if inString {
+			if escaped {
+				escaped = false
+				continue
+			}
+			if b == '\\' {
+				escaped = true
+				continue
+			}
+			if b == '"' {
+				inString = false
+			}
+			continue
+		}
+
+		switch b {
+		case '"':
+			inString = true
+		case '{':
+			depth++
+		case '}':
+			depth--
+			if depth == 0 {
+				return trimmed[:i+1], nil
+			}
+		}
+	}
+	return nil, errors.New("registry json object did not terminate cleanly")
+}