From 8cac271b9a7ca79042152cccc3aa0a3a92b69788 Mon Sep 17 00:00:00 2001
From: Aly Raffauf <aly@aly.codes>
Date: Sun, 9 Aug 2026 19:17:06 -0400
Subject: [PATCH] chore: remove redundant comments

---
 internal/deployment/sort.go                |  2 --
 internal/filesystem/parents.go             |  3 ---
 internal/filesystem/replace.go             |  4 ----
 internal/hooks/discover.go                 |  9 ---------
 internal/hooks/execute.go                  | 16 ----------------
 internal/hooks/execute_test.go             |  7 -------
 internal/hooks/order.go                    |  7 -------
 internal/reconcile/state_snapshot.go       |  9 ---------
 internal/reconcile/target_snapshot_test.go |  3 ---
 internal/repository/collisions.go          | 14 --------------
 internal/repository/compiler.go            | 18 ------------------
 internal/repository/compiler_test.go       | 12 ------------
 internal/repository/controls.go            |  9 ---------
 internal/repository/overlay.go             |  3 ---
 internal/repository/overlay_test.go        |  5 -----
 internal/repository/scan.go                |  9 ---------
 internal/repository/scan_test.go           |  2 --
 internal/routes/activate.go                | 12 ------------
 internal/selection/groups.go               | 13 -------------
 internal/selection/repository_test.go      |  4 ----
 internal/state/files_decode.go             |  1 -
 internal/state/files_read.go               |  7 -------
 internal/subprocess/run.go                 |  3 ---
 internal/subprocess/run_test.go            |  2 --
 24 files changed, 174 deletions(-)

diff --git a/internal/deployment/sort.go b/internal/deployment/sort.go
index 4c62d6d..a06a6bb 100644
--- a/internal/deployment/sort.go
+++ b/internal/deployment/sort.go
@@ -77,8 +77,6 @@ func SortGroups(groups []string) []string {
 	return compactStrings(sorted)
 }
 
-// indexLess adapts a bytewise element comparator into the index-based callback
-// shape that sort.SliceStable expects, for any slice element type.
 func indexLess[T any](items []T, less func(a, b T) bool) func(int, int) bool {
 	return func(i, j int) bool {
 		return less(items[i], items[j])
diff --git a/internal/filesystem/parents.go b/internal/filesystem/parents.go
index faf9963..587cb78 100644
--- a/internal/filesystem/parents.go
+++ b/internal/filesystem/parents.go
@@ -14,9 +14,6 @@ func targetPath(destination Destination) string {
 	return filepath.Join(destination.Root, filepath.FromSlash(destination.Relative))
 }
 
-// walkParentsValid checks every existing component from root through the
-// parent of relative; each must be a real directory. Missing components are
-// tolerated because a replacement may create them.
 func walkParentsValid(root, relative string) error {
 	segments, err := pathsafe.Segments(relative)
 	if err != nil {
diff --git a/internal/filesystem/replace.go b/internal/filesystem/replace.go
index 3ef50d4..c34a339 100644
--- a/internal/filesystem/replace.go
+++ b/internal/filesystem/replace.go
@@ -43,8 +43,6 @@ type ReplaceError struct {
 func (e *ReplaceError) Error() string { return e.Cause.Error() }
 func (e *ReplaceError) Unwrap() error { return e.Cause }
 
-// temporaryFile pairs the write path with the sync/close lifecycle of one
-// open replacement entry.
 type temporaryFile struct {
 	temp   TempFile
 	handle SyncHandle
@@ -67,8 +65,6 @@ func (file *temporaryFile) prepare(ctx context.Context, spec ReplacementSpec) er
 	return validateReplacement(file.temp.Name(), TokenOfContent(spec.Content), spec.Mode)
 }
 
-// validateReplacement re-checks the on-disk temporary entry: it must be a
-// regular file carrying exactly the intended bytes and mode.
 func validateReplacement(name string, token ContentToken, mode fs.FileMode) error {
 	facts, err := CaptureTarget(name)
 	if err != nil {
diff --git a/internal/hooks/discover.go b/internal/hooks/discover.go
index 364c9f0..088001d 100644
--- a/internal/hooks/discover.go
+++ b/internal/hooks/discover.go
@@ -1,9 +1,3 @@
-// This file validates one scope's _hooks tree into immutable hook
-// descriptors (PLAN.md Section 10.2). Discovery is read-only: it uses
-// os.Lstat and os.ReadDir only, never executes a hook, imports a process
-// helper, or inspects the target tree. A hooks root or phase path that is
-// not a real directory, and any direct child that is not an executable
-// regular file, is a validation error rather than a silent skip.
 package hooks
 
 import (
@@ -43,7 +37,6 @@ func Discover(root string, scope deployment.Scope) ([]deployment.Hook, error) {
 	return discovered, nil
 }
 
-// discoverPhase validates one before/after directory beneath the hooks root.
 func discoverPhase(hooksRoot string, scope deployment.Scope, phase deployment.HookPhase) ([]deployment.Hook, error) {
 	phasePath := filepath.Join(hooksRoot, string(phase))
 	info, err := os.Lstat(phasePath)
@@ -71,8 +64,6 @@ func discoverPhase(hooksRoot string, scope deployment.Scope, phase deployment.Ho
 	return discovered, nil
 }
 
-// discoverEntry validates one direct child and builds its descriptor. A
-// directory, symlink, special entry, or non-executable file is rejected.
 func discoverEntry(scope deployment.Scope, phasePath string, entry os.DirEntry) (deployment.Hook, error) {
 	phase := deployment.HookPhase(filepath.Base(phasePath))
 	full := filepath.Join(phasePath, entry.Name())
diff --git a/internal/hooks/execute.go b/internal/hooks/execute.go
index f475285..50149d2 100644
--- a/internal/hooks/execute.go
+++ b/internal/hooks/execute.go
@@ -1,11 +1,3 @@
-// This file executes ordered hook descriptors with the PLAN.md Section 10.4
-// runtime: repository-root working directory, inherited streams, a CATTERY_*
-// environment appended after the inherited one, and process-group
-// cancellation through internal/subprocess. The caller supplies one phase's
-// sequence built with the Section 12.2 comparators; before hooks stop at the
-// first failure, after hooks attempt every hook and aggregate failures.
-// Dry-run and no-hooks execute nothing. No secret-specific environment or
-// captured-stream policy enters hooks.
 package hooks
 
 import (
@@ -60,8 +52,6 @@ func Execute(ctx context.Context, input ExecuteInput, ordered []deployment.Hook)
 	return errors.Join(failures...)
 }
 
-// runHook executes one hook, wrapping launch and cancellation errors and
-// translating a nonzero exit into a hook failure error.
 func runHook(ctx context.Context, input ExecuteInput, hook deployment.Hook) error {
 	environment := append(os.Environ(), hookEnvironment(input, hook)...)
 	result, err := subprocess.Run(ctx, subprocess.Request{
@@ -81,9 +71,6 @@ func runHook(ctx context.Context, input ExecuteInput, hook deployment.Hook) erro
 	return nil
 }
 
-// hookEnvironment builds the Section 10.4 CATTERY_* variables for one hook.
-// os/exec keeps the later duplicate of a variable, so appending after the
-// inherited environment guarantees the canonical values win.
 func hookEnvironment(input ExecuteInput, hook deployment.Hook) []string {
 	return []string{
 		"CATTERY_REPO=" + input.RepositoryRoot,
@@ -95,7 +82,6 @@ func hookEnvironment(input ExecuteInput, hook deployment.Hook) []string {
 	}
 }
 
-// inheritReader defaults a nil stdin to the caller process stream.
 func inheritReader(reader io.Reader) io.Reader {
 	if reader == nil {
 		return os.Stdin
@@ -103,7 +89,6 @@ func inheritReader(reader io.Reader) io.Reader {
 	return reader
 }
 
-// inheritStdout defaults a nil stdout to the caller process stream.
 func inheritStdout(writer io.Writer) io.Writer {
 	if writer == nil {
 		return os.Stdout
@@ -111,7 +96,6 @@ func inheritStdout(writer io.Writer) io.Writer {
 	return writer
 }
 
-// inheritStderr defaults a nil stderr to the caller process stream.
 func inheritStderr(writer io.Writer) io.Writer {
 	if writer == nil {
 		return os.Stderr
diff --git a/internal/hooks/execute_test.go b/internal/hooks/execute_test.go
index ab59fd5..0dfc359 100644
--- a/internal/hooks/execute_test.go
+++ b/internal/hooks/execute_test.go
@@ -167,7 +167,6 @@ func testExecuteMissingExecutable(t *testing.T) {
 	}
 }
 
-// hookSpec bundles one test hook script's identity and body.
 type hookSpec struct {
 	name  string
 	group string
@@ -175,7 +174,6 @@ type hookSpec struct {
 	body  string
 }
 
-// writeTestHook writes an executable script for spec beneath dir.
 func writeTestHook(t *testing.T, dir string, spec hookSpec) deployment.Hook {
 	t.Helper()
 	path := filepath.Join(dir, spec.name)
@@ -188,13 +186,11 @@ func writeTestHook(t *testing.T, dir string, spec hookSpec) deployment.Hook {
 	}
 }
 
-// recordingHook writes a hook that appends its name to order.txt.
 func recordingHook(t *testing.T, dir string, spec hookSpec) deployment.Hook {
 	spec.body = fmt.Sprintf("echo %s >> order.txt", spec.name)
 	return writeTestHook(t, dir, spec)
 }
 
-// sequenceHooks writes the scrambled hooks and sorts them by phase.
 func sequenceHooks(t *testing.T, dir string, phase deployment.HookPhase) []deployment.Hook {
 	specs := []hookSpec{
 		{name: "zsh-b.sh", group: "zsh"},
@@ -217,7 +213,6 @@ func sequenceHooks(t *testing.T, dir string, phase deployment.HookPhase) []deplo
 	return ordered
 }
 
-// executeInput builds a base input bound to root as both repository and HOME.
 func executeInput(root string, phase deployment.HookPhase, result string) ExecuteInput {
 	return ExecuteInput{
 		RepositoryRoot: root,
@@ -228,13 +223,11 @@ func executeInput(root string, phase deployment.HookPhase, result string) Execut
 	}
 }
 
-// fileExists reports whether path is present.
 func fileExists(path string) bool {
 	_, err := os.Stat(path)
 	return err == nil
 }
 
-// assertExecutionOrder fails unless dir/order.txt lists want in order.
 func assertExecutionOrder(t *testing.T, dir string, want []string) {
 	t.Helper()
 	data, err := os.ReadFile(filepath.Join(dir, "order.txt"))
diff --git a/internal/hooks/order.go b/internal/hooks/order.go
index 8c80d56..2aa3f9c 100644
--- a/internal/hooks/order.go
+++ b/internal/hooks/order.go
@@ -1,10 +1,3 @@
-// This file orders validated hook descriptors into the two execution
-// sequences the apply orchestrator uses (PLAN.md Section 12.2): before hooks
-// run repository scope first, then groups lexically; after hooks run groups
-// lexically first, then repository scope last. Within one phase, names sort
-// bytewise. Each sort moves only its own phase, leaving the other phase's
-// hooks in stable order, so the two sequences are independent and compose
-// into the Section 10.3 order without a rescan.
 package hooks
 
 import (
diff --git a/internal/reconcile/state_snapshot.go b/internal/reconcile/state_snapshot.go
index 105edee..25712d1 100644
--- a/internal/reconcile/state_snapshot.go
+++ b/internal/reconcile/state_snapshot.go
@@ -56,8 +56,6 @@ func NewStateSnapshot(rows StateRows) (StateSnapshot, error) {
 	}, nil
 }
 
-// rejectDualActive rejects a path that is active in both the file and alias
-// tables of one repository pair, per PLAN.md Section 8.4.
 func rejectDualActive(files []state.FileBaseline, aliases []state.AliasBaseline) error {
 	active := make(map[string]bool, len(files))
 	for _, row := range files {
@@ -73,8 +71,6 @@ func rejectDualActive(files []state.FileBaseline, aliases []state.AliasBaseline)
 	return nil
 }
 
-// convertFileRow projects one file baseline into its immutable evaluation
-// record, cloning the retirement timestamp and validating every field.
 func convertFileRow(row state.FileBaseline) (FileState, error) {
 	if err := validateFileRow(row); err != nil {
 		return FileState{}, err
@@ -93,7 +89,6 @@ func convertFileRow(row state.FileBaseline) (FileState, error) {
 	}, nil
 }
 
-// validateFileRow rejects a row that could not have been stored faithfully.
 func validateFileRow(row state.FileBaseline) error {
 	if err := validateFilePaths(row); err != nil {
 		return err
@@ -113,7 +108,6 @@ func validateFileRow(row state.FileBaseline) error {
 	return nil
 }
 
-// validateFilePaths rejects malformed path and enum fields of a file row.
 func validateFilePaths(row state.FileBaseline) error {
 	if !state.IsSlashRelative(row.TargetPath) {
 		return fmt.Errorf("reconcile: file row target %q is not a slash-relative path", row.TargetPath)
@@ -135,8 +129,6 @@ func validateFilePaths(row state.FileBaseline) error {
 	return nil
 }
 
-// convertAliasRow projects one alias baseline into its immutable evaluation
-// record, cloning the retirement timestamp and validating every field.
 func convertAliasRow(row state.AliasBaseline) (AliasState, error) {
 	if err := validateAliasRow(row); err != nil {
 		return AliasState{}, err
@@ -151,7 +143,6 @@ func convertAliasRow(row state.AliasBaseline) (AliasState, error) {
 	}, nil
 }
 
-// validateAliasRow rejects a row that could not have been stored faithfully.
 func validateAliasRow(row state.AliasBaseline) error {
 	if !state.IsSlashRelative(row.AliasPath) {
 		return fmt.Errorf("reconcile: alias row path %q is not a slash-relative path", row.AliasPath)
diff --git a/internal/reconcile/target_snapshot_test.go b/internal/reconcile/target_snapshot_test.go
index 42b1ed3..ad7827f 100644
--- a/internal/reconcile/target_snapshot_test.go
+++ b/internal/reconcile/target_snapshot_test.go
@@ -32,7 +32,6 @@ func TestTargetSnapshot(t *testing.T) {
 	}
 }
 
-// captureAt captures one destination and fails the test on any error.
 func captureAt(t *testing.T, root, relative string) TargetSnapshot {
 	t.Helper()
 	snapshot, err := CaptureTarget(Destination{Root: root, Relative: relative})
@@ -42,7 +41,6 @@ func captureAt(t *testing.T, root, relative string) TargetSnapshot {
 	return snapshot
 }
 
-// mustTargetFile writes a regular file and fails the test on any error.
 func mustTargetFile(t *testing.T, path string, content []byte) {
 	t.Helper()
 	if err := os.WriteFile(path, content, 0o644); err != nil {
@@ -50,7 +48,6 @@ func mustTargetFile(t *testing.T, path string, content []byte) {
 	}
 }
 
-// mustTargetMkdir creates a directory and fails the test on any error.
 func mustTargetMkdir(t *testing.T, path string) {
 	t.Helper()
 	if err := os.Mkdir(path, 0o700); err != nil {
diff --git a/internal/repository/collisions.go b/internal/repository/collisions.go
index 7b10e86..d6ba278 100644
--- a/internal/repository/collisions.go
+++ b/internal/repository/collisions.go
@@ -1,9 +1,3 @@
-// This file implements the pure global collision engine for one compiled
-// platform plan (PLAN.md Section 6.3): file/file, file/alias, and alias/alias
-// equality and parent/child overlaps under bytewise and portable case/NFC
-// equivalence, across scopes, and against protected trees beneath HOME. The
-// engine inspects only its arguments; target identity and temporal races are
-// runtime preflight concerns.
 package repository
 
 import (
@@ -40,7 +34,6 @@ func CheckCollisions(files []deployment.ManagedFile, aliases []deployment.Alias,
 	return protectedTreeCollisions(files, aliases, scope)
 }
 
-// fileCollisions rejects equivalent or ancestor-related file target pairs.
 func fileCollisions(files []deployment.ManagedFile) error {
 	targets := fileTargets(files)
 	for first := 0; first < len(files); first++ {
@@ -70,7 +63,6 @@ func conflictIndex(destinations []string, first int) (int, error) {
 	return -1, nil
 }
 
-// fileTargets projects the file targets into one slice.
 func fileTargets(files []deployment.ManagedFile) []string {
 	targets := make([]string, len(files))
 	for index := range files {
@@ -79,7 +71,6 @@ func fileTargets(files []deployment.ManagedFile) []string {
 	return targets
 }
 
-// aliasDestinations projects the alias destinations into one slice.
 func aliasDestinations(aliases []deployment.Alias) []string {
 	destinations := make([]string, len(aliases))
 	for index := range aliases {
@@ -88,8 +79,6 @@ func aliasDestinations(aliases []deployment.Alias) []string {
 	return destinations
 }
 
-// destinationsCollide reports whether two HOME-relative paths are portably
-// equivalent or one is a portable strict ancestor of the other.
 func destinationsCollide(first, second string) (bool, error) {
 	firstSegments, err := pathsafe.Segments(first)
 	if err != nil {
@@ -141,9 +130,6 @@ func aliasFileConflictIndex(alias deployment.Alias, files []deployment.ManagedFi
 	return -1, nil
 }
 
-// aliasFileCollide reports whether the alias destination collides with the
-// file target, exempting the intended identity between an alias and its own
-// canonical target (PLAN.md Section 6.2).
 func aliasFileCollide(alias deployment.Alias, file deployment.ManagedFile) (bool, error) {
 	destination, err := pathsafe.Segments(alias.AliasRelativePath)
 	if err != nil {
diff --git a/internal/repository/compiler.go b/internal/repository/compiler.go
index 7938b0b..4e5810a 100644
--- a/internal/repository/compiler.go
+++ b/internal/repository/compiler.go
@@ -1,6 +1,3 @@
-// This file composes the nine Section 12.3 phases into the immutable plan
-// for one platform: scan/overlay (1-4), routes (5), hooks (6), paths (7),
-// collisions (8), sorting (9). Read-only: no targets, state, SOPS, hooks.
 package repository
 
 import (
@@ -27,7 +24,6 @@ type CompileInput struct {
 	Selected       []string
 }
 
-// compiled holds the validated phase outputs of one compilation.
 type compiled struct {
 	groups  []string
 	files   []deployment.ManagedFile
@@ -50,7 +46,6 @@ func Compile(input CompileInput) (deployment.Plan, error) {
 	return finalize(input, records)
 }
 
-// compileRepository runs phases 1-7: scan, overlay, routes, hooks, paths.
 func compileRepository(input CompileInput) (compiled, error) {
 	base, err := scanAndSelect(input)
 	if err != nil {
@@ -74,7 +69,6 @@ func compileRepository(input CompileInput) (compiled, error) {
 	return compiled{groups: base.Groups, files: files, aliases: aliases, hooks: hookRecords}, nil
 }
 
-// scanAndSelect scans the repository and validates the selection.
 func scanAndSelect(input CompileInput) (ScanResult, error) {
 	base, err := Scan(input.RepositoryRoot)
 	if err != nil {
@@ -86,7 +80,6 @@ func scanAndSelect(input CompileInput) (ScanResult, error) {
 	return base, nil
 }
 
-// finalize filters to the selection, sorts, and wraps the immutable plan.
 func finalize(input CompileInput, records compiled) (deployment.Plan, error) {
 	selected := input.Selected
 	groups := records.groups
@@ -113,7 +106,6 @@ func finalize(input CompileInput, records compiled) (deployment.Plan, error) {
 	})
 }
 
-// selectRecords keeps the records the predicate accepts.
 func selectRecords[T any](records []T, selected []string, kept func(T) bool) []T {
 	filtered := make([]T, 0, len(records))
 	for _, record := range records {
@@ -124,12 +116,10 @@ func selectRecords[T any](records []T, selected []string, kept func(T) bool) []T
 	return filtered
 }
 
-// scopeKept keeps records of a selected scope.
 func scopeKept(group string, selected []string) bool {
 	return len(selected) == 0 || slices.Contains(selected, group)
 }
 
-// hookKept keeps repository hooks always and group hooks on selection.
 func hookKept(scope deployment.Scope, selected []string) bool {
 	if scope.Group == "" {
 		return true
@@ -137,7 +127,6 @@ func hookKept(scope deployment.Scope, selected []string) bool {
 	return scopeKept(scope.Group, selected)
 }
 
-// validateSelection rejects groups the repository does not contain.
 func validateSelection(groups, selected []string) error {
 	for _, name := range selected {
 		if !slices.Contains(groups, name) {
@@ -147,7 +136,6 @@ func validateSelection(groups, selected []string) error {
 	return nil
 }
 
-// activateRoutes activates every scope's route manifest.
 func activateRoutes(input CompileInput, records compiled) ([]deployment.Alias, error) {
 	var activated []deployment.Alias
 	for _, scope := range scopesOf(records.groups) {
@@ -160,7 +148,6 @@ func activateRoutes(input CompileInput, records compiled) ([]deployment.Alias, e
 	return activated, nil
 }
 
-// activateScope activates one scope's declarations and stamps its scope.
 func activateScope(input CompileInput, scope deployment.Scope, files []deployment.ManagedFile) ([]deployment.Alias, error) {
 	config, err := loadRoutes(input.RepositoryRoot, scope)
 	if err != nil {
@@ -186,7 +173,6 @@ func activateScope(input CompileInput, scope deployment.Scope, files []deploymen
 	return activated, nil
 }
 
-// loadRoutes decodes the scope's _routes.toml; missing yields no config.
 func loadRoutes(root string, scope deployment.Scope) (routes.Config, error) {
 	path := filepath.Join(root, scope.Group, "_routes.toml")
 	data, err := os.ReadFile(path)
@@ -199,7 +185,6 @@ func loadRoutes(root string, scope deployment.Scope) (routes.Config, error) {
 	return routes.Decode(data)
 }
 
-// discoverHooks validates the hook trees of every scope.
 func discoverHooks(input CompileInput, groups []string) ([]deployment.Hook, error) {
 	var hookRecords []deployment.Hook
 	for _, scope := range scopesOf(groups) {
@@ -212,7 +197,6 @@ func discoverHooks(input CompileInput, groups []string) ([]deployment.Hook, erro
 	return hookRecords, nil
 }
 
-// validateDestinations revalidates every compiled path (phase 7).
 func validateDestinations(files []deployment.ManagedFile, aliases []deployment.Alias) error {
 	for _, file := range files {
 		if err := validateTarget(file.TargetRelativePath); err != nil {
@@ -230,7 +214,6 @@ func validateDestinations(files []deployment.ManagedFile, aliases []deployment.A
 	return nil
 }
 
-// validateTarget wraps a lexical path rejection with repository context.
 func validateTarget(path string) error {
 	if _, err := pathsafe.Segments(path); err != nil {
 		return fmt.Errorf("repository: %w", err)
@@ -238,7 +221,6 @@ func validateTarget(path string) error {
 	return nil
 }
 
-// scopesOf returns the root scope followed by one scope per group.
 func scopesOf(groups []string) []deployment.Scope {
 	scopes := make([]deployment.Scope, 0, len(groups)+1)
 	scopes = append(scopes, deployment.NewScope(""))
diff --git a/internal/repository/compiler_test.go b/internal/repository/compiler_test.go
index 1e7d6a9..a496475 100644
--- a/internal/repository/compiler_test.go
+++ b/internal/repository/compiler_test.go
@@ -10,7 +10,6 @@ import (
 	"github.com/alyraffauf/cattery/internal/deployment"
 )
 
-// routesFixture is the repository manifest used by the plan fixtures.
 const routesFixture = `version = 1
 
 [symlinks.all]
@@ -36,7 +35,6 @@ func TestPlanCompilation(t *testing.T) {
 	}
 }
 
-// goldenScenario describes one platform's expected plan records.
 type goldenScenario struct {
 	platform deployment.Layer
 	files    []deployment.ManagedFile
@@ -76,7 +74,6 @@ func testPlanGolden(t *testing.T) {
 	}
 }
 
-// goldenWant builds the expected plan for one golden scenario.
 func goldenWant(root string, scenario goldenScenario) deployment.Plan {
 	return mustPlan(deployment.PlanInput{
 		RepositoryRoot: root,
@@ -156,8 +153,6 @@ func testPlanInvalidUnselected(t *testing.T) {
 	}
 }
 
-// compileFixture materializes a two-group repository with platform overlays,
-// a route manifest, and executable hooks.
 func compileFixture(t *testing.T) string {
 	t.Helper()
 	root := t.TempDir()
@@ -182,7 +177,6 @@ func writeRoutes(t *testing.T, root string, content string) {
 	}
 }
 
-// assertPlan fails when the compiled plan differs from the expectation.
 func assertPlan(t *testing.T, got deployment.Plan, want deployment.Plan) {
 	t.Helper()
 	if !reflect.DeepEqual(got, want) {
@@ -198,7 +192,6 @@ func mustPlan(input deployment.PlanInput) deployment.Plan {
 	return plan
 }
 
-// fileWant describes one expected managed file record.
 type fileWant struct {
 	scope    deployment.Scope
 	layer    deployment.Layer
@@ -207,7 +200,6 @@ type fileWant struct {
 	exec     fs.FileMode
 }
 
-// expectFile builds the expected managed file record.
 func expectFile(root string, want fileWant) deployment.ManagedFile {
 	return deployment.ManagedFile{
 		Scope: want.scope, Layer: want.layer, Kind: deployment.FileOrdinary,
@@ -216,7 +208,6 @@ func expectFile(root string, want fileWant) deployment.ManagedFile {
 	}
 }
 
-// aliasWant describes one expected alias record.
 type aliasWant struct {
 	scope       deployment.Scope
 	platform    string
@@ -224,7 +215,6 @@ type aliasWant struct {
 	canonical   string
 }
 
-// expectAlias builds the expected alias record.
 func expectAlias(want aliasWant) deployment.Alias {
 	return deployment.Alias{
 		Scope: want.scope, Platform: want.platform,
@@ -232,14 +222,12 @@ func expectAlias(want aliasWant) deployment.Alias {
 	}
 }
 
-// hookWant describes one expected hook record.
 type hookWant struct {
 	scope deployment.Scope
 	phase deployment.HookPhase
 	name  string
 }
 
-// expectHook builds the expected hook record beneath root.
 func expectHook(root string, want hookWant) deployment.Hook {
 	return deployment.Hook{
 		Scope: want.scope, Phase: want.phase, Name: want.name,
diff --git a/internal/repository/controls.go b/internal/repository/controls.go
index 740eaff..d6d62a0 100644
--- a/internal/repository/controls.go
+++ b/internal/repository/controls.go
@@ -1,14 +1,5 @@
 // Package repository classifies scope-root entries that govern how the
 // repository deploys.
-//
-// This file performs pure lexical classification of a single name at a scope
-// root: it does no directory traversal and no platform resolution. Known
-// controls, ignored unknown underscore entries, and repository-root metadata
-// are recognized; every other name is an ordinary deployable entry.
-//
-// Underscore-prefixed names INSIDE an ordinary target tree are literal and
-// deployable (PLAN 2.2). That nested case is out of scope for this lexical
-// classifier, which only inspects names at a scope root.
 package repository
 
 import "strings"
diff --git a/internal/repository/overlay.go b/internal/repository/overlay.go
index 05712cc..6be4796 100644
--- a/internal/repository/overlay.go
+++ b/internal/repository/overlay.go
@@ -40,7 +40,6 @@ type resolver struct {
 	platform deployment.Layer
 }
 
-// resolveScope merges one group scope, skipping groups replaced by files.
 func (resolver *resolver) resolveScope(scope deployment.Scope, platformRootView layerView) ([]deployment.ManagedFile, error) {
 	if _, replaced := platformRootView.files[scope.Group]; replaced {
 		return nil, nil
@@ -57,7 +56,6 @@ type layerView struct {
 	dirs  map[string]bool
 }
 
-// covers reports whether the platform layer replaces a base target.
 func (view layerView) covers(target string) bool {
 	if _, ok := view.files[target]; ok || view.dirs[target] {
 		return true
@@ -183,7 +181,6 @@ func (walker *layerWalker) walk(relativePath string, fileKind deployment.FileKin
 	return nil
 }
 
-// classifyEntry returns the storage kind for one layer entry.
 func classifyEntry(relative string, entry os.DirEntry, kind deployment.FileKind) (deployment.FileKind, bool, error) {
 	if relative != "" {
 		return kind, false, nil
diff --git a/internal/repository/overlay_test.go b/internal/repository/overlay_test.go
index 5912c8a..5522fc9 100644
--- a/internal/repository/overlay_test.go
+++ b/internal/repository/overlay_test.go
@@ -169,7 +169,6 @@ func testOverlayMalformed(t *testing.T) {
 	}
 }
 
-// resolvePaths materializes files beneath root, scans, and resolves platform.
 func resolvePaths(root string, platform deployment.Layer, paths ...string) ([]deployment.ManagedFile, error) {
 	for _, path := range paths {
 		if err := os.MkdirAll(filepath.Dir(filepath.Join(root, path)), 0o755); err != nil {
@@ -186,7 +185,6 @@ func resolvePaths(root string, platform deployment.Layer, paths ...string) ([]de
 	return ResolvePlatform(root, result, platform)
 }
 
-// wantRecord describes one expected managed-file record compactly.
 type wantRecord struct {
 	scope    deployment.Scope
 	layer    deployment.Layer
@@ -196,7 +194,6 @@ type wantRecord struct {
 	exec     fs.FileMode
 }
 
-// newRecord builds the expected record for a repo-relative path.
 func newRecord(root string, want wantRecord) deployment.ManagedFile {
 	layer := want.layer
 	if layer == "" {
@@ -215,13 +212,11 @@ func newRecord(root string, want wantRecord) deployment.ManagedFile {
 	}
 }
 
-// wantRecords bundles the expected records with their repository root.
 type wantRecords struct {
 	root    string
 	records []wantRecord
 }
 
-// assertRecords verifies got against the expected records.
 func assertRecords(t *testing.T, got []deployment.ManagedFile, want wantRecords) {
 	t.Helper()
 	if len(got) != len(want.records) {
diff --git a/internal/repository/scan.go b/internal/repository/scan.go
index 6964524..a3a0796 100644
--- a/internal/repository/scan.go
+++ b/internal/repository/scan.go
@@ -1,5 +1,3 @@
-// This file scans repository trees into base-layer candidates and raw hook
-// candidates (PLAN Task 28); overlay and route work belong to later phases.
 package repository
 
 import (
@@ -56,7 +54,6 @@ func Scan(root string) (ScanResult, error) {
 	return ScanResult{Groups: scanner.groups, Files: scanner.files, Hooks: scanner.hooks}, nil
 }
 
-// scopeScanner accumulates candidates while scanning one scope root.
 type scopeScanner struct {
 	repoRoot  string
 	scopeRoot string
@@ -80,7 +77,6 @@ func (s *scopeScanner) scanScopeRoot() error {
 	return nil
 }
 
-// scanEntry dispatches one scope-root entry.
 func (s *scopeScanner) scanEntry(entry os.DirEntry) error {
 	control := ClassifyRoot(entry.Name())
 	switch {
@@ -102,7 +98,6 @@ func (s *scopeScanner) scanEntry(entry os.DirEntry) error {
 	}
 }
 
-// beginGroup validates a group name and scans its scope.
 func (s *scopeScanner) beginGroup(entry os.DirEntry) error {
 	name := entry.Name()
 	if err := pathsafe.GroupName(name); err != nil {
@@ -171,7 +166,6 @@ func (s *scopeScanner) scanHookPhase(hooks string, phase deployment.HookPhase) e
 	return nil
 }
 
-// walkTree visits a literal subtree beneath relative.
 func (s *scopeScanner) walkTree(relative string, kind deployment.FileKind) error {
 	entries, err := os.ReadDir(filepath.Join(s.repoRoot, s.scopeRoot, relative))
 	if err != nil {
@@ -228,7 +222,6 @@ func (s *scopeScanner) nonRegular(relative string) error {
 	return fmt.Errorf("repository: non-regular source entry %q", filepath.Join(s.scopeRoot, relative))
 }
 
-// checkGroupCollisions rejects group names equivalent under PLAN 2.1, 6.3.
 func checkGroupCollisions(groups []string) error {
 	for first := 0; first < len(groups); first++ {
 		if match := duplicateGroupIndex(groups, first); match >= 0 {
@@ -238,8 +231,6 @@ func checkGroupCollisions(groups []string) error {
 	return nil
 }
 
-// duplicateGroupIndex returns the first later group index equivalent to
-// groups[first], or -1.
 func duplicateGroupIndex(groups []string, first int) int {
 	for second := first + 1; second < len(groups); second++ {
 		if pathsafe.SegmentsEquivalent(groups[first], groups[second]) {
diff --git a/internal/repository/scan_test.go b/internal/repository/scan_test.go
index f40af5e..46bd7d2 100644
--- a/internal/repository/scan_test.go
+++ b/internal/repository/scan_test.go
@@ -185,7 +185,6 @@ func testScanGroupCollisions(t *testing.T) {
 	}
 }
 
-// wantFile describes one expected base candidate compactly.
 type wantFile struct {
 	scope    deployment.Scope
 	repoPath string
@@ -193,7 +192,6 @@ type wantFile struct {
 	secret   bool
 }
 
-// newCandidate builds the expected Candidate for a repo-relative path.
 func newCandidate(root string, want wantFile) Candidate {
 	kind := deployment.FileOrdinary
 	if want.secret {
diff --git a/internal/routes/activate.go b/internal/routes/activate.go
index f7bc21b..430bc11 100644
--- a/internal/routes/activate.go
+++ b/internal/routes/activate.go
@@ -1,9 +1,3 @@
-// This file activates decoded _routes.toml declarations for one platform:
-// it unions the `all` section with the host platform section, verifies every
-// canonical key names a managed regular file in the same scope, and computes
-// the exact relative symlink payload each alias will carry. Activation is
-// pure with respect to the target tree: no HOME path is inspected and no
-// process or state store is touched (PLAN.md Sections 5.2-5.4).
 package routes
 
 import (
@@ -46,8 +40,6 @@ func Activate(config Config, platform deployment.Layer, canonical []string) ([]d
 	return records, nil
 }
 
-// recordsForDeclaration converts one active declaration into alias records,
-// rejecting an alias destination equal to its canonical target.
 func recordsForDeclaration(declaration Declaration, platform deployment.Layer) ([]deployment.Alias, error) {
 	var records []deployment.Alias
 	for _, destination := range declaration.Aliases {
@@ -67,8 +59,6 @@ func recordsForDeclaration(declaration Declaration, platform deployment.Layer) (
 	return records, nil
 }
 
-// rejectDuplicates rejects a destination repeated anywhere in the active
-// union, even when both declarations name the same canonical target.
 func rejectDuplicates(records []deployment.Alias) error {
 	seen := map[string]bool{}
 	for _, record := range records {
@@ -80,7 +70,6 @@ func rejectDuplicates(records []deployment.Alias) error {
 	return nil
 }
 
-// activeSection reports whether a declaration section applies on platform.
 func activeSection(section Section, platform deployment.Layer) bool {
 	switch platform {
 	case deployment.LayerDarwin:
@@ -127,7 +116,6 @@ func AliasPayload(canonical, alias string) (string, error) {
 	return strings.Repeat("../", up) + strings.Join(remaining, "/"), nil
 }
 
-// commonPrefix returns the length of the shared leading segment run.
 func commonPrefix(first, second []string) int {
 	length := min(len(first), len(second))
 	common := 0
diff --git a/internal/selection/groups.go b/internal/selection/groups.go
index ea984b2..ea13f19 100644
--- a/internal/selection/groups.go
+++ b/internal/selection/groups.go
@@ -1,12 +1,3 @@
-// This file resolves group selections for the repository-using commands
-// (PLAN.md Sections 8.5, 11.2, and 11.5). CompiledOnly serves validate, whose
-// explicit names must be current compiled groups; CompiledAndPersisted serves
-// status, diff, and apply, whose explicit names may also come from persisted
-// rows so a deleted group stays inspectable. Both reject unknown and
-// duplicate arguments and return sorted typed selections. Selection is pure:
-// the caller supplies the compiled group names and the persisted group names
-// read from state, so no compiler execution, state read, or mutation occurs
-// here.
 package selection
 
 import (
@@ -69,7 +60,6 @@ func CompiledAndPersisted(current []string, persisted PersistedGroups, arguments
 	return Selection{Groups: sortedUnique(arguments)}, nil
 }
 
-// rejectUnknown fails when an argument is not among the known groups.
 func rejectUnknown(arguments, known []string) error {
 	for _, argument := range arguments {
 		if !slices.Contains(known, argument) {
@@ -79,7 +69,6 @@ func rejectUnknown(arguments, known []string) error {
 	return nil
 }
 
-// rejectDuplicates fails when an argument repeats.
 func rejectDuplicates(arguments []string) error {
 	seen := make(map[string]bool, len(arguments))
 	for _, argument := range arguments {
@@ -91,12 +80,10 @@ func rejectDuplicates(arguments []string) error {
 	return nil
 }
 
-// union returns the combined members of both lists.
 func union(first, second []string) []string {
 	return append(append([]string(nil), first...), second...)
 }
 
-// sortedUnique returns the sorted unique members of items, or nil when empty.
 func sortedUnique(items []string) []string {
 	if len(items) == 0 {
 		return nil
diff --git a/internal/selection/repository_test.go b/internal/selection/repository_test.go
index 0f67fc4..ff2a97a 100644
--- a/internal/selection/repository_test.go
+++ b/internal/selection/repository_test.go
@@ -31,16 +31,12 @@ func TestRepositorySelection(t *testing.T) {
 	}
 }
 
-// newFixtureResolver builds a resolver over a fresh isolated store whose
-// canonical home is also the resolver home.
 func newFixtureResolver(t *testing.T) (*RepositoryResolver, *database.Fixture) {
 	t.Helper()
 	fixture := database.New(t)
 	return NewRepositoryResolver(fixture.Home, fixture.Store), fixture
 }
 
-// resolveSelection resolves without explicit or environment inputs and
-// fails the test on any error.
 func resolveSelection(t *testing.T, resolver *RepositoryResolver) state.Repository {
 	t.Helper()
 	result, err := resolver.Resolve(RepositoryRequest{WorkingDir: t.TempDir()})
diff --git a/internal/state/files_decode.go b/internal/state/files_decode.go
index 4e5d7ac..ee1e1f9 100644
--- a/internal/state/files_decode.go
+++ b/internal/state/files_decode.go
@@ -22,7 +22,6 @@ func scanFileBaseline(source scanner) (FileBaseline, error) {
 	return baseline, nil
 }
 
-// fileRawRow carries the stored text/byte form of one files row.
 type fileRawRow struct {
 	kind, layer, status, applied string
 	retired                      *string
diff --git a/internal/state/files_read.go b/internal/state/files_read.go
index 21600e3..7280962 100644
--- a/internal/state/files_read.go
+++ b/internal/state/files_read.go
@@ -20,7 +20,6 @@ func prepareFileBaseline(root, home string, baseline FileBaseline) (string, stri
 	return root, home, nil
 }
 
-// validateFileBaseline rejects rows that cannot be stored faithfully.
 func validateFileBaseline(baseline FileBaseline) error {
 	if err := validateFilePaths(baseline); err != nil {
 		return err
@@ -59,8 +58,6 @@ func validateFileMetadata(baseline FileBaseline) error {
 	return nil
 }
 
-// ensureKeyID recovers the hash key for secret rows so the transaction can
-// commit its identifier; ordinary rows need no key.
 func (store *Store) ensureKeyID(kind deployment.FileKind) (*deployment.Digest, error) {
 	if kind != deployment.FileSecret {
 		return nil, nil
@@ -100,8 +97,6 @@ func (store *Store) requireRepository(root, home string) (Repository, error) {
 	return store.LookupRepository(root, home)
 }
 
-// scanAndCommitFile reads the row back through the transaction and commits,
-// rolling back when the read fails so no open transaction leaks.
 func scanAndCommitFile(transaction *sql.Tx, key fileBaselineKey) (FileBaseline, error) {
 	return commitStateRead(transaction, func(transaction *sql.Tx) (FileBaseline, error) {
 		baseline, err := scanFileBaseline(transaction.QueryRow(fileByPairTargetSQL, key.root, key.home, key.target))
@@ -135,8 +130,6 @@ func (store *Store) readFileBaselines(statement, root, home string) ([]FileBasel
 	return CopyFileBaselines(baselines), nil
 }
 
-// checkRepresentationCorruption rejects a snapshot whose repository has paths
-// active in both tables, per PLAN.md Section 8.4.
 func (store *Store) checkRepresentationCorruption(root, home string) error {
 	rows, err := store.database.conn.Query(dualActiveByPairSQL, root, home)
 	if err != nil {
diff --git a/internal/subprocess/run.go b/internal/subprocess/run.go
index 9520f6d..b6f912e 100644
--- a/internal/subprocess/run.go
+++ b/internal/subprocess/run.go
@@ -83,14 +83,11 @@ func Run(ctx context.Context, request Request) (Result, error) {
 	return observed.result, observed.err
 }
 
-// outcome bundles a Result with its error so helpers stay under three params.
 type outcome struct {
 	result Result
 	err    error
 }
 
-// groupShutdown bundles the inputs needed by awaitShutdown so it stays under
-// the three-parameter limit.
 type groupShutdown struct {
 	handle  *processHandle
 	waitCh  chan error
diff --git a/internal/subprocess/run_test.go b/internal/subprocess/run_test.go
index 5f20134..43dfffd 100644
--- a/internal/subprocess/run_test.go
+++ b/internal/subprocess/run_test.go
@@ -85,8 +85,6 @@ func testMissingExecutable(t *testing.T) {
 	}
 }
 
-// scriptTarget bundles the inputs needed by writeScript so the helper stays
-// under the three-parameter limit. directory is created fresh when empty.
 type scriptTarget struct {
 	directory string
 	name      string
-- 
2.51.2