feat: add TestNoDeadExports audit check, quarantine 67 dead symbols

Uses go/types to detect exported constants, functions, types, and
vars with zero references anywhere in the codebase (including cmd/).
Methods (interface implementations) are excluded.

Quarantined 67 dead exports to quarantine/deadcode/ with .go.dead
extension, mirroring the source tree. 17 test-only exports added
to an allowlist (used exclusively from _test.go files).

Also removed 5 cascaded orphan DescKey constants whose only callers
were among the deleted functions.

Signed-off-by: Jose Alekhinne <jose@ctx.ist>

Author: josealekhine

.gitignore

@@ -81,3 +81,6 @@ ideas
 # Generated skills
 .claude/skills/generated
 .claude/skills/gitnexus
+
+# Dead code quarantine
+quarantine/

internal/assets/hooks/messages/doc.go

@@ -8,8 +8,7 @@
 //
 // The embedded registry.yaml maps each hook+variant pair to a
 // category and description. [Registry] returns all entries,
-// [Lookup] finds a specific one, and [Hooks]/[Variants] enumerate
-// the available names. Categories are [CategoryCustomizable]
-// (user can override the template) or [CategoryCtxSpecific]
-// (internal to ctx).
+// [Lookup] finds a specific one, and [Variants] enumerates
+// the available names. [CategoryCtxSpecific] marks entries
+// internal to ctx.
 package messages

internal/assets/read/hook/doc.go

@@ -9,6 +9,5 @@
 //
 // [Message] reads a specific template file by hook name and
 // filename. [MessageRegistry] returns the raw registry.yaml.
-// [MessageList] and [VariantList] enumerate available hooks
-// and their template variants for discovery and testing.
+// [TraceScript] reads an embedded trace git hook script.
 package hook

internal/assets/read/hook/hook.go

@@ -51,49 +51,3 @@ func Message(hook, filename string) ([]byte, error) {
 func MessageRegistry() ([]byte, error) {
 	return assets.FS.ReadFile(asset.PathMessageRegistry)
 }
-
-// MessageList returns available hook message directory names.
-//
-// Each hook is a directory under hooks/messages/ containing one or
-// more variant .txt template files.
-//
-// Returns:
-//   - []string: List of hook directory names
-//   - error: Non-nil if directory read fails
-func MessageList() ([]string, error) {
-	entries, readErr := assets.FS.ReadDir(asset.DirHooksMessages)
-	if readErr != nil {
-		return nil, readErr
-	}
-
-	names := make([]string, 0, len(entries))
-	for _, entry := range entries {
-		if entry.IsDir() {
-			names = append(names, entry.Name())
-		}
-	}
-	return names, nil
-}
-
-// VariantList returns available variant filenames for a hook.
-//
-// Parameters:
-//   - hook: Hook directory name (e.g., "qa-reminder")
-//
-// Returns:
-//   - []string: List of variant filenames (e.g., "gate.txt")
-//   - error: Non-nil if the hook directory is not found or read fails
-func VariantList(hook string) ([]string, error) {
-	entries, readErr := assets.FS.ReadDir(path.Join(asset.DirHooksMessages, hook))
-	if readErr != nil {
-		return nil, readErr
-	}
-
-	names := make([]string, 0, len(entries))
-	for _, entry := range entries {
-		if !entry.IsDir() {
-			names = append(names, entry.Name())
-		}
-	}
-	return names, nil
-}

internal/assets/read/project/doc.go

@@ -7,7 +7,6 @@
 // Package project provides access to project-root files and
 // directory README templates from embedded assets.
 //
-// [File] reads a project-root file by name (e.g. .gitignore
-// additions). [Readme] reads the README template for a specific
+// [Readme] reads the README template for a specific
 // subdirectory (e.g. specs/README.md).
 package project

internal/assets/read/project/project.go

@@ -13,21 +13,6 @@ import (
 	"github.com/ActiveMemory/ctx/internal/config/asset"
 )
 
-// File reads a project-root file by name from the embedded filesystem.
-//
-// These files are deployed to the project root (not .context/) by dedicated
-// handlers during initialization.
-//
-// Parameters:
-//   - name: Filename (e.g., "Makefile.ctx")
-//
-// Returns:
-//   - []byte: File content
-//   - error: Non-nil if the file is not found or read fails
-func File(name string) ([]byte, error) {
-	return assets.FS.ReadFile(path.Join(asset.DirProject, name))
-}
-
 // Readme reads a project directory README template by directory name.
 //
 // Templates are stored as project/<dir>-README.md in the embedded filesystem.

internal/assets/tpl/tpl_recall.go

@@ -15,11 +15,6 @@ const (
 	// Args: date, slug, shortID.
 	RecallFilename = "%s-%s-%s.md"
 
-	// RecallTokens formats the token stats line.
-	// Args: total, in, out.
-	//nolint:gosec // G101: display template, not a credential
-	RecallTokens = "**Tokens**: %s (in: %s, out: %s)"
-
 	// RecallPartOf formats the part indicator.
 	// Args: part, totalParts.
 	RecallPartOf = "**Part %d of %d**"
@@ -40,9 +35,6 @@ const (
 	// Args: name, count.
 	RecallToolCount = "- %s: %d"
 
-	// RecallSummaryPlaceholder is the placeholder text in the summary section.
-	RecallSummaryPlaceholder = "[Add your summary of this session]"
-
 	// RecallErrorMarker is the error indicator for tool results.
 	RecallErrorMarker = "❌ Error"
 

internal/audit/dead_exports_test.go

@@ -0,0 +1,232 @@
+//   /    ctx:                         https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package audit
+
+import (
+	"go/types"
+	"strings"
+	"testing"
+	"unicode"
+
+	"golang.org/x/tools/go/packages"
+)
+
+// TestNoDeadExports flags exported constants, variables,
+// functions, and types in internal/ that have zero
+// references outside their definition file.
+//
+// Test files are exempt (both as definition and usage
+// sites).
+//
+// Unexported symbols are skipped: they are package-
+// internal and may be used via reflection or are
+// genuinely file-scoped helpers.
+
+// testOnlyExports lists exported symbols that exist
+// solely for test usage. The dead-export scanner skips
+// test files, so these would otherwise be false
+// positives. Keep this list small: prefer eliminating
+// the export over adding it here.
+var testOnlyExports = map[string]bool{
+	"github.com/ActiveMemory/ctx/internal/assets/hooks/messages.CategoryCustomizable":       true,
+	"github.com/ActiveMemory/ctx/internal/assets/hooks/messages.Hooks":                      true,
+	"github.com/ActiveMemory/ctx/internal/assets/hooks/messages.RegistryError":              true,
+	"github.com/ActiveMemory/ctx/internal/cli/initialize/core/vscode.CreateVSCodeArtifacts": true,
+	"github.com/ActiveMemory/ctx/internal/cli/journal/core/lock.LockedFrontmatterLine":      true,
+	"github.com/ActiveMemory/ctx/internal/cli/pad/core/store.EnsureGitignore":               true,
+	"github.com/ActiveMemory/ctx/internal/cli/system/core/state.SetDirForTest":              true,
+	"github.com/ActiveMemory/ctx/internal/config/asset.DirReferences":                       true,
+	"github.com/ActiveMemory/ctx/internal/config/regex.Phase":                               true,
+	"github.com/ActiveMemory/ctx/internal/inspect.StartsWithCtxMarker":                      true,
+	"github.com/ActiveMemory/ctx/internal/journal/parser.Parser":                            true,
+	"github.com/ActiveMemory/ctx/internal/journal/parser.RegisteredTools":                   true,
+	"github.com/ActiveMemory/ctx/internal/mcp/proto.ErrCodeInvalidReq":                      true,
+	"github.com/ActiveMemory/ctx/internal/mcp/proto.InitializeParams":                       true,
+	"github.com/ActiveMemory/ctx/internal/mcp/proto.UnsubscribeParams":                      true,
+	"github.com/ActiveMemory/ctx/internal/rc.Reset":                                         true,
+	"github.com/ActiveMemory/ctx/internal/task.MatchFull":                                   true,
+}
+
+func TestNoDeadExports(t *testing.T) {
+	pkgs := loadPackages(t)
+
+	// Also load cmd/ packages to catch cross-boundary
+	// usage (cmd/ctx/main.go calls internal/ exports).
+	cmdPkgs := loadCmdPackages(t)
+	allPkgs := make([]*packages.Package, 0, len(pkgs)+len(cmdPkgs))
+	allPkgs = append(allPkgs, pkgs...)
+	allPkgs = append(allPkgs, cmdPkgs...)
+
+	// Phase 1: collect all exported definitions.
+	// Key: "pkgPath.Name" (stable across type-checker
+	// instances). Value: definition metadata.
+	type defInfo struct {
+		label string // e.g. "const config/dep.BuilderGo"
+		pos   string // file:line
+		file  string // definition filename
+	}
+	defs := make(map[string]defInfo)
+
+	for _, pkg := range pkgs {
+		for ident, obj := range pkg.TypesInfo.Defs {
+			if obj == nil {
+				continue
+			}
+			if !isExported(ident.Name) {
+				continue
+			}
+
+			pos := pkg.Fset.Position(ident.Pos())
+			if isTestFile(pos.Filename) {
+				continue
+			}
+
+			kind := objectKind(obj)
+			if kind == "" {
+				continue
+			}
+
+			key := obj.Pkg().Path() + "." + obj.Name()
+			defs[key] = defInfo{
+				label: kind + " " +
+					shortPkg(pkg.PkgPath) +
+					"." + ident.Name,
+				pos:  pos.String(),
+				file: pos.Filename,
+			}
+		}
+	}
+
+	// Phase 2: collect all usage sites. Remove any
+	// def that has at least one use outside its own
+	// definition file. Scan both internal/ and cmd/.
+	for _, pkg := range allPkgs {
+		for ident, obj := range pkg.TypesInfo.Uses {
+			if obj == nil || obj.Pkg() == nil {
+				continue
+			}
+
+			pos := pkg.Fset.Position(ident.Pos())
+			if isTestFile(pos.Filename) {
+				continue
+			}
+
+			key := obj.Pkg().Path() + "." + obj.Name()
+			_, defined := defs[key]
+			if !defined {
+				continue
+			}
+
+			// Any use (same or different package)
+			// means the symbol is alive.
+			delete(defs, key)
+		}
+	}
+
+	// Phase 3: remove test-only allowlist entries.
+	for key := range testOnlyExports {
+		delete(defs, key)
+	}
+
+	// Phase 4: report survivors as dead exports.
+	var violations []string
+	for _, info := range defs {
+		violations = append(violations,
+			info.pos+
+				": dead export: "+info.label,
+		)
+	}
+
+	if len(violations) == 0 {
+		return
+	}
+
+	t.Errorf(
+		"%d dead exports found:", len(violations),
+	)
+	limit := 30
+	if len(violations) < limit {
+		limit = len(violations)
+	}
+	for _, v := range violations[:limit] {
+		t.Error(v)
+	}
+	if len(violations) > 30 {
+		t.Errorf(
+			"... and %d more",
+			len(violations)-30,
+		)
+	}
+}
+
+// loadCmdPackages loads cmd/ packages for cross-
+// boundary usage detection.
+func loadCmdPackages(t *testing.T) []*packages.Package {
+	t.Helper()
+	cfg := &packages.Config{
+		Mode: packages.NeedName |
+			packages.NeedFiles |
+			packages.NeedSyntax |
+			packages.NeedTypes |
+			packages.NeedTypesInfo,
+		Tests: false,
+	}
+	pkgs, err := packages.Load(
+		cfg,
+		"github.com/ActiveMemory/ctx/cmd/...",
+	)
+	if err != nil {
+		t.Fatalf("packages.Load cmd: %v", err)
+	}
+	return pkgs
+}
+
+// isExported reports whether name starts with an
+// uppercase letter.
+func isExported(name string) bool {
+	if name == "" {
+		return false
+	}
+	return unicode.IsUpper(rune(name[0]))
+}
+
+// objectKind returns a human-readable kind string for
+// a types.Object, or "" to skip.
+func objectKind(obj types.Object) string {
+	switch o := obj.(type) {
+	case *types.Const:
+		return "const"
+	case *types.Var:
+		// Skip struct fields and function parameters.
+		// Only flag package-level vars.
+		if obj.Parent() == nil {
+			return ""
+		}
+		return "var"
+	case *types.Func:
+		// Skip methods (have receivers) — they may
+		// implement interfaces via dynamic dispatch.
+		if o.Type().(*types.Signature).Recv() != nil {
+			return ""
+		}
+		return "func"
+	case *types.TypeName:
+		return "type"
+	default:
+		return ""
+	}
+}
+
+// shortPkg returns the last two path elements of a
+// package path for readable labels.
+func shortPkg(path string) string {
+	parts := strings.Split(path, "/")
+	if len(parts) <= 2 {
+		return path
+	}
+	return strings.Join(parts[len(parts)-2:], "/")
+}

internal/cli/pad/core/store/doc.go

@@ -7,7 +7,7 @@
 // Package store manages scratchpad file persistence including.
 //
 // Key exports: [ScratchpadPath], [KeyPath],
-// [EnsureKey], [EnsureGitignore], [ReadEntries].
+// [EnsureKey], [ReadEntries], [WriteEntries].
 // Shared helpers used by sibling cmd/ packages.
 // Used by core cmd/ packages.
 package store

internal/cli/system/core/journal/types.go

@@ -10,8 +10,3 @@ package journal
 type CheckResult struct {
 	Value string
 }
-
-// MarkResult holds the outcome of marking a stage.
-type MarkResult struct {
-	Marked bool
-}