From 932560528099ff6adc402a2a7d159b752114e509 Mon Sep 17 00:00:00 2001
From: Aly Raffauf <aly@aly.codes>
Date: Mon, 10 Aug 2026 11:28:44 -0400
Subject: [PATCH] Remove stale PLAN section references

---
 cmd/cattery/main.go                        |  2 +-
 integration/secrets_test.go                |  2 +-
 internal/application/add/infer.go          |  8 ++++----
 internal/application/add/write_ordinary.go |  4 ++--
 internal/application/initialize/service.go | 10 +++++-----
 internal/application/inspect/status.go     |  2 +-
 internal/buildinfo/info.go                 |  2 +-
 internal/cli/execute.go                    |  2 +-
 internal/cli/version.go                    |  2 +-
 internal/deployment/file.go                |  4 ++--
 internal/diff/safe_test.go                 |  2 +-
 internal/failure/error.go                  |  4 ++--
 internal/filesystem/mode.go                |  2 +-
 internal/hooks/cancellation_test.go        |  2 +-
 internal/hooks/execute.go                  |  4 ++--
 internal/hooks/execute_test.go             |  4 ++--
 internal/reconcile/classify_file.go        |  7 +++----
 internal/reconcile/classify_file_test.go   |  7 +++----
 internal/reconcile/decisions_test.go       |  2 +-
 internal/repository/compiler.go            |  4 ++--
 internal/repository/overlay.go             |  2 +-
 internal/secrets/client.go                 |  6 +++---
 internal/secrets/decrypt.go                |  4 ++--
 internal/secrets/encrypt.go                |  6 +++---
 internal/selection/groups.go               |  4 ++--
 internal/selection/repository.go           |  2 +-
 internal/state/database.go                 |  2 +-
 internal/state/migrations.go               |  4 ++--
 internal/subprocess/run.go                 |  4 ++--
 29 files changed, 54 insertions(+), 56 deletions(-)

diff --git a/cmd/cattery/main.go b/cmd/cattery/main.go
index 113cd47..a7f46d3 100644
--- a/cmd/cattery/main.go
+++ b/cmd/cattery/main.go
@@ -47,7 +47,7 @@ func run() (exitStatus int) {
 }
 
 // exitCode runs the application and maps an interrupted context to the
-// Section 11.8 signal status.
+// signal status.
 func exitCode(ctx context.Context, application *cli.Application, args []string) int {
 	code := cli.Execute(ctx, application, args)
 	if ctx.Err() == nil {
diff --git a/integration/secrets_test.go b/integration/secrets_test.go
index 3925869..565fec6 100644
--- a/integration/secrets_test.go
+++ b/integration/secrets_test.go
@@ -177,7 +177,7 @@ func testSecretsRealRoundTrip(t *testing.T) {
 	env.applyRealSecret(t, keyHome, payload)
 }
 
-// realSecretPayload builds the Section 13 27-byte fixture containing NUL
+// realSecretPayload builds the 27-byte fixture containing NUL
 // and invalid UTF-8 bytes.
 func realSecretPayload() []byte {
 	payload := make([]byte, 27)
diff --git a/internal/application/add/infer.go b/internal/application/add/infer.go
index 02d812a..911f283 100644
--- a/internal/application/add/infer.go
+++ b/internal/application/add/infer.go
@@ -44,7 +44,7 @@ type sourceLocation struct {
 // Infer derives one ItemPlanInput per target in raw command-line order. It is
 // pure and read-only: each canonical absolute target is mapped to its owner
 // when the plan already manages it, or to the inferred scope, layer, kind, and
-// repository-relative source path under Section 2's grammar. ExecutableBits
+// repository-relative source path under the path grammar. ExecutableBits
 // stays zero; preflight fills it from the live target mode.
 func Infer(context inferContext, request Request) ([]ItemPlanInput, error) {
 	items := make([]ItemPlanInput, 0, len(context.targets))
@@ -93,7 +93,7 @@ func inferManaged(request Request, ref targetRef, owner deployment.ManagedFile)
 }
 
 // inferUnmanaged derives the default location, proves the target is
-// representable there, and inverts Section 2's grammar to produce the source.
+// representable there, and inverts the path grammar to produce the source.
 func inferUnmanaged(context inferContext, request Request, ref targetRef) (ItemPlanInput, error) {
 	location, err := inferLocation(context, request)
 	if err != nil {
@@ -130,7 +130,7 @@ func inferLocation(context inferContext, request Request) (sourceLocation, error
 	return sourceLocation{scope: scope, layer: layer, kind: inferKind(request)}, nil
 }
 
-// sourcePath inverts Section 2's grammar into a repository-relative source
+// sourcePath inverts the path grammar into a repository-relative source
 // path from the location and the HOME-relative target.
 func (location sourceLocation) sourcePath(target string) string {
 	var builder strings.Builder
@@ -195,7 +195,7 @@ func inferKind(request Request) deployment.FileKind {
 	return deployment.FileOrdinary
 }
 
-// checkRepresentable enforces Section 2.1: underscore-prefixed targets are
+// checkRepresentable enforces the path rules: underscore-prefixed targets are
 // unrepresentable everywhere; root base additionally rejects metadata names
 // and multi-segment non-dot targets that the grammar would route to a group.
 func checkRepresentable(scope deployment.Scope, layer deployment.Layer, relative string) error {
diff --git a/internal/application/add/write_ordinary.go b/internal/application/add/write_ordinary.go
index 8549e6e..20fae66 100644
--- a/internal/application/add/write_ordinary.go
+++ b/internal/application/add/write_ordinary.go
@@ -21,7 +21,7 @@ type writeOutcome struct {
 }
 
 // writeOrdinary atomically writes one ordinary source from freshly validated
-// target bytes. The source mode follows Section 7.1: 0644 plus exec bits when
+// target bytes. The source mode is 0644 plus exec bits when
 // the source is new, or the preserved read/write bits plus exec bits when it
 // already exists.
 func (service *Service) writeOrdinary(ctx context.Context, identity RepositoryIdentity, item ItemPlan) (writeOutcome, error) {
@@ -41,7 +41,7 @@ func (service *Service) writeOrdinary(ctx context.Context, identity RepositoryId
 	return writeOutcome{published: target, target: target, result: result}, nil
 }
 
-// sourceMode applies Section 7.1 to the frozen source: a new source takes
+// sourceMode applies the mode policy to the frozen source: a new source takes
 // 0644 plus exec bits; an existing source preserves its read/write bits.
 func sourceMode(target filesystem.TargetFacts, exec fs.FileMode) fs.FileMode {
 	if target.Kind() == filesystem.KindAbsent {
diff --git a/internal/application/initialize/service.go b/internal/application/initialize/service.go
index 03298d0..0e8c177 100644
--- a/internal/application/initialize/service.go
+++ b/internal/application/initialize/service.go
@@ -97,7 +97,7 @@ type roots struct {
 }
 
 // ensureRoot returns the canonical repository root, creating it first when
-// missing, after validating the Section 6.1 overlaps.
+// missing, after validating the repository/home/state overlaps.
 func ensureRoot(anchors roots) (string, error) {
 	existing, err := existingDirectory(anchors.repository)
 	if err != nil {
@@ -114,7 +114,7 @@ func existingRoot(anchors roots) (string, error) {
 	return canonicalRepositoryRoot(anchors)
 }
 
-// createdRoot materializes a missing root, validating the Section 6.1 overlaps
+// createdRoot materializes a missing root, validating the repository/home/state overlaps
 // before MkdirAll and rechecking the canonical form after creation.
 func createdRoot(anchors roots) (string, error) {
 	canonical, err := canonicalRepositoryRoot(anchors)
@@ -140,7 +140,7 @@ func recheckRoot(anchors roots) (string, error) {
 }
 
 // canonicalRepositoryRoot canonicalizes the repository path and rejects the
-// Section 6.1 repository/home/state overlaps in one step.
+// repository/home/state overlaps in one step.
 func canonicalRepositoryRoot(anchors roots) (string, error) {
 	canonical, err := canonicalPath(anchors.repository)
 	if err != nil {
@@ -152,7 +152,7 @@ func canonicalRepositoryRoot(anchors roots) (string, error) {
 	return canonical, nil
 }
 
-// canonicalHome resolves the home to canonical form, requiring an existing real directory (Section 6.2).
+// canonicalHome resolves the home to canonical form, requiring an existing real directory.
 func canonicalHome(home string) (string, error) {
 	canonical, err := pathsafe.CanonicalRoot(home)
 	if err != nil {
@@ -173,7 +173,7 @@ func canonicalPath(path string) (string, error) {
 	return canonical, nil
 }
 
-// stateDirectory returns the canonical directory holding the store's database, the protected state tree for the Section 6.1 overlap checks.
+// stateDirectory returns the canonical directory holding the store's database, the protected state tree for overlap checks.
 func (service *Service) stateDirectory() (string, error) {
 	database := service.store.Database()
 	if database == nil {
diff --git a/internal/application/inspect/status.go b/internal/application/inspect/status.go
index 3115d69..4d2cf2b 100644
--- a/internal/application/inspect/status.go
+++ b/internal/application/inspect/status.go
@@ -88,7 +88,7 @@ func (result StatusResult) Converged() bool { return result.converged }
 // Status evaluates one request and translates the evaluation into sorted
 // semantic status/retired records, counts, and convergence. A Difference
 // failure accompanies the partial result whenever drift remains, so
-// renderers print the records and the exit mapper applies Section 11.8.
+// renderers print the records and the exit mapper applies the appropriate status.
 func (service *Service) Status(ctx context.Context, request Request) (StatusResult, error) {
 	evaluation, err := service.evaluate(ctx, request)
 	if err != nil {
diff --git a/internal/buildinfo/info.go b/internal/buildinfo/info.go
index 1009bb3..9601d85 100644
--- a/internal/buildinfo/info.go
+++ b/internal/buildinfo/info.go
@@ -6,7 +6,7 @@ import (
 )
 
 // Version, Commit, and BuildTimestamp are the three linker-populated package
-// variables permitted by Section 12.1. They describe a development build until
+// variables used for build metadata. They describe a development build until
 // a release overrides them with -ldflags -X.
 var (
 	Version        = "dev"
diff --git a/internal/cli/execute.go b/internal/cli/execute.go
index cb4a047..f8c6f61 100644
--- a/internal/cli/execute.go
+++ b/internal/cli/execute.go
@@ -20,7 +20,7 @@ const (
 
 // Execute runs one application over the given arguments, writes one
 // diagnostic on failure, and maps every joined category and signal to the
-// Section 11.8 exit status. Status constants stay here and os.Exit remains in
+// exit status. Status constants stay here and os.Exit remains in
 // the process entrypoint.
 func Execute(ctx context.Context, application *Application, args []string) int {
 	err := application.Execute(ctx, args)
diff --git a/internal/cli/version.go b/internal/cli/version.go
index 7acd412..9d7b528 100644
--- a/internal/cli/version.go
+++ b/internal/cli/version.go
@@ -8,7 +8,7 @@ import (
 )
 
 // newVersionCommand declares only the version subcommand and renders the
-// typed build fields in the exact Section 11.7 single-line format, without
+// typed build fields in the exact single-line format, without
 // touching the Cobra root Version field.
 func newVersionCommand(runtime Runtime) *cobra.Command {
 	command := &cobra.Command{
diff --git a/internal/deployment/file.go b/internal/deployment/file.go
index c595d83..84a1643 100644
--- a/internal/deployment/file.go
+++ b/internal/deployment/file.go
@@ -79,7 +79,7 @@ func validateFile(file ManagedFile) error {
 const ExecutableBitMask fs.FileMode = 0o111
 
 // SecretMode and SecretExecutableMode are the exact modes enforced on every
-// secret target (Section 4.5): non-executable secrets are 0600, executable
+// secret target: non-executable secrets are 0600, executable
 // secrets are 0700. These are POSIX guarantees only.
 const (
 	SecretMode           fs.FileMode = 0o600
@@ -87,7 +87,7 @@ const (
 )
 
 // SecretTargetMode returns the exact mode a secret target must hold: SecretMode,
-// or SecretExecutableMode when any executable bit is set (Section 4.5). This is
+// or SecretExecutableMode when any executable bit is set. This is
 // the single source of truth for secret-target mode policy; upper layers
 // (filesystem, reconcile) delegate here so the rule cannot drift between them.
 func SecretTargetMode(sourceExec fs.FileMode) fs.FileMode {
diff --git a/internal/diff/safe_test.go b/internal/diff/safe_test.go
index 7a97ef7..cd7cadb 100644
--- a/internal/diff/safe_test.go
+++ b/internal/diff/safe_test.go
@@ -42,7 +42,7 @@ type safeDiffCase struct {
 	wantLines   []string
 }
 
-// safeDiffCases enumerates the Section 9.6 rules: printable text produces a
+// safeDiffCases enumerates the rules: printable text produces a
 // unified diff, equal content produces a metadata-only record, carriage
 // return/ESC/bidi/invalid UTF-8 or an oversized side demotes to binary,
 // secrets carry only classification, and labels never expose control runes.
diff --git a/internal/failure/error.go b/internal/failure/error.go
index a2c19aa..b301bb6 100644
--- a/internal/failure/error.go
+++ b/internal/failure/error.go
@@ -10,7 +10,7 @@ import (
 // status so this package never depends on CLI or exit-code concepts.
 type Kind string
 
-// The five presentation-neutral categories from Section 12.6.
+// The five presentation-neutral categories.
 const (
 	InvalidInput Kind = "InvalidInput"
 	Operational  Kind = "Operational"
@@ -78,7 +78,7 @@ func HasKind(err error) (Kind, bool) {
 // maps these to process termination statuses; no numeric value lives here.
 type Signal string
 
-// The two cancellation causes from Section 14.4.
+// The two cancellation causes.
 const (
 	Interrupt Signal = "Interrupt"
 	Terminate Signal = "Terminate"
diff --git a/internal/filesystem/mode.go b/internal/filesystem/mode.go
index f4ec058..b61daf9 100644
--- a/internal/filesystem/mode.go
+++ b/internal/filesystem/mode.go
@@ -6,7 +6,7 @@ import (
 	"github.com/alyraffauf/cattery/internal/deployment"
 )
 
-// ordinaryNewFileMode is the default for a new ordinary target (Section 7.1);
+// ordinaryNewFileMode is the default for a new ordinary target;
 // source executable bits are OR-combined onto it.
 const ordinaryNewFileMode fs.FileMode = 0o644
 
diff --git a/internal/hooks/cancellation_test.go b/internal/hooks/cancellation_test.go
index f9d82c7..9de1ebc 100644
--- a/internal/hooks/cancellation_test.go
+++ b/internal/hooks/cancellation_test.go
@@ -1,6 +1,6 @@
 //go:build unix
 
-// This file exercises the Section 10.4 cancellation contract of Execute:
+// This file exercises the cancellation contract of Execute:
 // a canceled context stops execution, signals each started hook's process
 // group, and kills descendants, and neither phase starts further hooks.
 package hooks
diff --git a/internal/hooks/execute.go b/internal/hooks/execute.go
index 50149d2..3287b3f 100644
--- a/internal/hooks/execute.go
+++ b/internal/hooks/execute.go
@@ -11,7 +11,7 @@ import (
 	"github.com/alyraffauf/cattery/internal/subprocess"
 )
 
-// ExecuteInput carries the Section 10.4 runtime values of one hook phase.
+// ExecuteInput carries the runtime values of one hook phase.
 // Empty stream fields inherit the caller's process streams.
 type ExecuteInput struct {
 	RepositoryRoot string
@@ -27,7 +27,7 @@ type ExecuteInput struct {
 }
 
 // Execute runs the ordered hooks of one phase synchronously, each in its own
-// process group with inherited streams and the Section 10.4 environment.
+// process group with inherited streams and the configured environment.
 // Before hooks stop at the first failure; after hooks run every hook and
 // return the joined failures. Cancellation returns the context error without
 // starting further hooks. Dry-run and no-hooks suppress execution entirely.
diff --git a/internal/hooks/execute_test.go b/internal/hooks/execute_test.go
index 0dfc359..46eb10b 100644
--- a/internal/hooks/execute_test.go
+++ b/internal/hooks/execute_test.go
@@ -1,7 +1,7 @@
-// This file exercises the Section 10.4 execution contract of Execute:
+// This file exercises the execution contract of Execute:
 // suppression for empty sequences, dry-run, and no-hooks, inherited streams
 // and environment, before-stop versus after-aggregate failures, and the
-// order the Section 12.2 comparators produce.
+// order the comparators produce.
 package hooks
 
 import (
diff --git a/internal/reconcile/classify_file.go b/internal/reconcile/classify_file.go
index e073044..4514aec 100644
--- a/internal/reconcile/classify_file.go
+++ b/internal/reconcile/classify_file.go
@@ -25,9 +25,8 @@ type FileClassification struct {
 // ClassifyFile purely classifies one complete file evaluation against its
 // persisted baseline: the five core matrix rows, the unbaselined safety rows,
 // independent executable-bit
-// reconciliation per Section 7.1, and unexpected target types per Section
-// 7.3. A retired row with a current producer reconciles against its retained
-// baseline (Section 9.5 reactivation). Records without a file producer
+// reconciliation, and unexpected target types. A retired row with a current
+// producer reconciles against its retained baseline (reactivation). Records without a file producer
 // belong to the alias and retirement classifiers and return the zero
 // classification.
 func ClassifyFile(record Evaluation, semantics FileSemantics) FileClassification {
@@ -73,7 +72,7 @@ func classifyUnbaselined(record Evaluation, semantics FileSemantics) FileClassif
 // For a secret source, raw storage equality with the baseline source proves
 // the source unchanged without any semantic digest; raw change is a semantic
 // source change only when the keyed plaintext digest also differs, so a
-// SOPS re-encryption with unchanged plaintext stays converged (Section 8.3).
+// SOPS re-encryption with unchanged plaintext stays converged.
 func classifyBaselined(record Evaluation, row *FileState, semantics FileSemantics) FileClassification {
 	sourceChanged := semantics.Source != row.BaselineSource()
 	if row.SourceKind() == deployment.FileSecret {
diff --git a/internal/reconcile/classify_file_test.go b/internal/reconcile/classify_file_test.go
index 7aa3d32..02e6911 100644
--- a/internal/reconcile/classify_file_test.go
+++ b/internal/reconcile/classify_file_test.go
@@ -37,10 +37,9 @@ type fileCase struct {
 }
 
 // fileClassificationCases enumerates the classification Cartesian product:
-// the five core baselined rows of Section 9.2, secret storage semantics of
-// Section 8.3, the unbaselined safety rows of Section 9.3, independent mode
-// reconciliation of Sections 4.5 and 7.1, unexpected target types of Section
-// 7.3, and retained-baseline reactivation of Section 9.5.
+// the five core baselined rows, secret storage semantics, the unbaselined
+// safety rows, independent mode reconciliation, unexpected target types, and
+// retained-baseline reactivation.
 var fileClassificationCases = []fileCase{
 	{name: "no-op", kind: KindFile, source: sourceA, target: sourceA, mode: 0o644,
 		baseline: stateAt(sourceA, sourceA, 0),
diff --git a/internal/reconcile/decisions_test.go b/internal/reconcile/decisions_test.go
index 84a2e5a..62cddc1 100644
--- a/internal/reconcile/decisions_test.go
+++ b/internal/reconcile/decisions_test.go
@@ -56,7 +56,7 @@ type eligibilityCase struct {
 	want   []DecisionChoice
 }
 
-// decisionEligibilityCases enumerates the Section 9.4 prompt rule: every
+// decisionEligibilityCases enumerates the prompt rule: every
 // decision offers overwrite, skip, and abort; diff rides only on ordinary
 // byte-comparing file rows; automatic and non-decision pairs offer nothing.
 var decisionEligibilityCases = []eligibilityCase{
diff --git a/internal/repository/compiler.go b/internal/repository/compiler.go
index 18a6772..5d51b4b 100644
--- a/internal/repository/compiler.go
+++ b/internal/repository/compiler.go
@@ -123,8 +123,8 @@ func scopeKept(group string, selected []string) bool {
 // hookKept applies the documented asymmetry between repository-scope hooks
 // and root files under explicit group selection. Repository-scope (root)
 // hooks — identified by scope.Group == "" — always run even when a subset of
-// groups is selected, whereas root files are dropped, because Section 10.1
-// mandates that repository hooks run for every apply.
+// groups is selected, whereas root files are dropped, because repository hooks
+// run for every apply.
 func hookKept(scope deployment.Scope, selected []string) bool {
 	if scope.Group == "" {
 		return true
diff --git a/internal/repository/overlay.go b/internal/repository/overlay.go
index d270445..2a5e575 100644
--- a/internal/repository/overlay.go
+++ b/internal/repository/overlay.go
@@ -114,7 +114,7 @@ func mergeCandidate(files map[string]Candidate, target string, candidate Candida
 }
 
 // representableRootSecretTarget reports whether target can be produced by a
-// root-scope secret source under Section 2.1: a root secret must target either
+// root-scope secret source: a root secret must target either
 // a dot-prefixed tree (ungrouped HOME tree) or a single non-underscore segment.
 // Multi-segment non-dot paths (e.g. bin/...) and leading-underscore targets are
 // not representable at the root layer and require a group or a platform overlay.
diff --git a/internal/secrets/client.go b/internal/secrets/client.go
index 0f25726..6e153a7 100644
--- a/internal/secrets/client.go
+++ b/internal/secrets/client.go
@@ -16,7 +16,7 @@ import (
 	"github.com/alyraffauf/cattery/internal/subprocess"
 )
 
-// maxStderr is the Section 4.3 stderr capture bound. Excess stderr is drained
+// maxStderr is the stderr capture bound. Excess stderr is drained
 // and discarded so a chatty process can never block its pipe.
 const maxStderr = 64 * 1024
 
@@ -36,7 +36,7 @@ func NewClient(executable string, directory string, environment []string) *Clien
 	return &Client{executable: executable, directory: directory, environment: slices.Clone(environment)}
 }
 
-// SetDirectory rebinds the client to the repository root that Section 4.3
+// SetDirectory rebinds the client to the repository root where
 // SOPS invocations must run in. Bootstrap cannot know the repository, so the
 // binding happens once the selected command resolves it; the client is used
 // by one single-use application for exactly one repository.
@@ -123,7 +123,7 @@ func classifyRun(stdout *boundedCapture, outcome runOutcome, diag diagnosis) err
 	return failure.New(failure.Operational, diag.operation+" "+diag.source+" launch failed", outcome.err)
 }
 
-// exitFailure reports a nonzero exit with the Section 4.3 diagnostic shape.
+// exitFailure reports a nonzero exit with the diagnostic shape.
 func exitFailure(result subprocess.Result, diag diagnosis) error {
 	if result.ExitCode == 0 {
 		return nil
diff --git a/internal/secrets/decrypt.go b/internal/secrets/decrypt.go
index f525054..7d63b19 100644
--- a/internal/secrets/decrypt.go
+++ b/internal/secrets/decrypt.go
@@ -5,7 +5,7 @@ import (
 	"math"
 )
 
-// Decrypt runs the Section 4.3 sops decrypt shape against /dev/stdin with the
+// Decrypt runs the sops decrypt shape against /dev/stdin with the
 // repository-relative source name as the filename override. The ciphertext
 // bytes are caller-validated; sops never reopens a repository source path.
 // The returned plaintext slice is caller-owned, and the client retains
@@ -20,7 +20,7 @@ func (client *Client) Decrypt(ctx context.Context, ciphertext []byte, relativePa
 	})
 }
 
-// decryptArguments is the exact Section 4.3 decryption invocation.
+// decryptArguments is the exact decryption invocation.
 func decryptArguments(relativePath string) []string {
 	return []string{
 		"decrypt",
diff --git a/internal/secrets/encrypt.go b/internal/secrets/encrypt.go
index 26c90f5..b263160 100644
--- a/internal/secrets/encrypt.go
+++ b/internal/secrets/encrypt.go
@@ -8,10 +8,10 @@ import (
 	"github.com/alyraffauf/cattery/internal/failure"
 )
 
-// outputSlack is the Section 4.3 allowance added to expected output sizes.
+// outputSlack is the allowance added to expected output sizes.
 const outputSlack = 1024 * 1024
 
-// Encrypt runs the Section 4.3 sops encrypt shape against /dev/stdin with the
+// Encrypt runs the sops encrypt shape against /dev/stdin with the
 // repository-relative source name as the filename override. It requires
 // nonempty valid JSON output, clears and rejects anything else, and never
 // writes plaintext anywhere but the caller-supplied stdin. The returned
@@ -34,7 +34,7 @@ func (client *Client) Encrypt(ctx context.Context, plaintext []byte, relativePat
 	return output, nil
 }
 
-// encryptArguments is the exact Section 4.3 encryption invocation.
+// encryptArguments is the exact encryption invocation.
 func encryptArguments(relativePath string) []string {
 	return []string{
 		"encrypt",
diff --git a/internal/selection/groups.go b/internal/selection/groups.go
index b0f7624..ae32e23 100644
--- a/internal/selection/groups.go
+++ b/internal/selection/groups.go
@@ -26,7 +26,7 @@ type PersistedGroups struct {
 }
 
 // CompiledOnly validates explicit group arguments against the current compiled
-// groups (Section 11.2). No arguments select root scope plus every current
+// groups. No arguments select root scope plus every current
 // group; unknown and duplicate arguments are errors.
 func CompiledOnly(current []string, arguments []string) (Selection, error) {
 	if len(arguments) == 0 {
@@ -42,7 +42,7 @@ func CompiledOnly(current []string, arguments []string) (Selection, error) {
 }
 
 // CompiledAndPersisted expands and validates a group selection against the
-// current groups and the persisted rows (Section 8.5). No arguments select
+// current groups and the persisted rows. No arguments select
 // root scope plus every current and active state-only group; an explicit name
 // may exist in the current plan or any active/retired state row. Unknown and
 // duplicate arguments are errors.
diff --git a/internal/selection/repository.go b/internal/selection/repository.go
index fdf6cf7..b190254 100644
--- a/internal/selection/repository.go
+++ b/internal/selection/repository.go
@@ -26,7 +26,7 @@ type RepositoryRequest struct {
 	WorkingDir  string
 }
 
-// RepositoryResolver applies the Section 8.2 precedence and returns the
+// RepositoryResolver applies the configured precedence and returns the
 // canonical repository identity. Explicit and environment paths are resolved
 // against the initial working directory; only the default lookup may touch
 // state, and it never registers a row.
diff --git a/internal/state/database.go b/internal/state/database.go
index cdfdfd8..1d10e05 100644
--- a/internal/state/database.go
+++ b/internal/state/database.go
@@ -51,7 +51,7 @@ func (database *Database) Path() string {
 }
 
 // Open prepares the private state directory and database file, opens SQLite with
-// a single connection, and applies the Section 8.5 PRAGMAs. It performs no
+// a single connection, and applies the required PRAGMAs. It performs no
 // locking and no schema migration.
 func (database *Database) Open() error {
 	if err := prepareStateDirectory(filepath.Dir(database.path)); err != nil {
diff --git a/internal/state/migrations.go b/internal/state/migrations.go
index 4034deb..9646f0c 100644
--- a/internal/state/migrations.go
+++ b/internal/state/migrations.go
@@ -7,8 +7,8 @@ import (
 	_ "embed"
 )
 
-// initialMigrationSQL is the embedded Section 8.4 schema. It is one of the two
-// package-variable exceptions permitted by Section 12.1.
+// initialMigrationSQL is the embedded schema. It is one of the two
+// package-variable exceptions permitted in this package.
 //
 //go:embed migrations/001_initial.sql
 var initialMigrationSQL string
diff --git a/internal/subprocess/run.go b/internal/subprocess/run.go
index 93b5efc..a81cffe 100644
--- a/internal/subprocess/run.go
+++ b/internal/subprocess/run.go
@@ -16,7 +16,7 @@ import (
 	"time"
 )
 
-// gracePeriod is the SIGTERM-to-SIGKILL interval mandated by Section 10.4.
+// gracePeriod is the SIGTERM-to-SIGKILL interval for canceled processes.
 const gracePeriod = 5 * time.Second
 
 // groupPollInterval paces the bounded wait for a canceled process group to
@@ -75,7 +75,7 @@ func (e *LaunchError) Unwrap() error {
 	return e.Cause
 }
 
-// Run executes request synchronously, applying the Section 10.4 process-group
+// Run executes request synchronously, applying the process-group
 // cancellation policy: SIGTERM to the child group on ctx cancellation, a
 // gracePeriod wait, then SIGKILL. Nonzero exit codes return (Result, nil);
 // only launch failures and cancellation return an error.
-- 
2.51.2