fix(security): remove blanket gosec G101 exclusion; fix findings with…

.golangci.yml

@@ -34,10 +34,6 @@ linters:
       - linters: [gosec]
         text: "G30[16]"
         path: "_test\\.go"
-      # TextDescKey constants are i18n keys, not credentials
-      - linters: [gosec]
-        text: "G101"
-        path: "internal/config/embed/text/"
 
 run:
   timeout: 5m

hack/lint-docstrings.sh

@@ -26,6 +26,12 @@
 
 set -euo pipefail
 
+# Collect every violation first, then fail if any were found. Without
+# this the checks would print findings but still exit 0, letting
+# docstring regressions slip silently through `make audit`. The
+# `{ ...; } || true` wrapper keeps a mid-scan non-zero from aborting
+# the collection so the report stays complete.
+violations="$({
 find internal/ cmd/ -name '*.go' ! -name '*_test.go' ! -name 'doc.go' | sort | while read -r file; do
   grep -n '^func [a-zA-Z]' "$file" | while IFS=: read -r lineno rest; do
     funcname=$(echo "$rest" | sed 's/^func \([A-Za-z0-9_]*\).*/\1/')
@@ -152,3 +158,9 @@ find internal/ cmd/ -name 'doc.go' | sort | while read -r file; do
     echo "SHALLOW_DOC $file ($doclines doc lines, package $pkg)"
   fi
 done 2>/dev/null
+} || true)"
+
+if [ -n "$violations" ]; then
+  printf '%s\n' "$violations"
+  exit 1
+fi

internal/assets/commands/text/errors.yaml

@@ -756,7 +756,7 @@ err.kb.evidence.mkdir-dir:
   short: 'mkdir evidence-index parent: %w'
 err.kb.evidence.open-index:
   short: 'open evidence-index: %w'
-err.kb.evidence.write-row:
+err.kb.evidence.append-row:
   short: 'write evidence row: %w'
 err.kb.evidence.parse-id-number:
   short: 'parse EV number %q: %w'
@@ -784,39 +784,39 @@ err.kb.glossary.mkdir-dir:
   short: 'mkdir glossary parent: %w'
 err.kb.glossary.open-file:
   short: 'open glossary: %w'
-err.kb.glossary.write-row:
+err.kb.glossary.append-row:
   short: 'write glossary row: %w'
 err.kb.timeline.read-file:
   short: 'stat timeline: %w'
 err.kb.timeline.mkdir-dir:
   short: 'mkdir timeline parent: %w'
 err.kb.timeline.open-file:
   short: 'open timeline: %w'
-err.kb.timeline.write-row:
+err.kb.timeline.append-row:
   short: 'write timeline row: %w'
 err.kb.sourcemap.read-file:
   short: 'stat source-map: %w'
 err.kb.sourcemap.mkdir-dir:
   short: 'mkdir source-map parent: %w'
 err.kb.sourcemap.open-file:
   short: 'open source-map: %w'
-err.kb.sourcemap.write-row:
+err.kb.sourcemap.append-row:
   short: 'write source-map row: %w'
 err.kb.relationship.read-file:
   short: 'stat relationship-map: %w'
 err.kb.relationship.mkdir-dir:
   short: 'mkdir relationship-map parent: %w'
 err.kb.relationship.open-file:
   short: 'open relationship-map: %w'
-err.kb.relationship.write-row:
+err.kb.relationship.append-row:
   short: 'write relationship-map row: %w'
 err.kb.contradiction.read-file:
   short: 'read contradictions: %w'
 err.kb.contradiction.mkdir-dir:
   short: 'mkdir contradictions parent: %w'
 err.kb.contradiction.open-file:
   short: 'open contradictions: %w'
-err.kb.contradiction.write-row:
+err.kb.contradiction.append-row:
   short: 'write contradictions row: %w'
 err.kb.contradiction.parse-c-number:
   short: 'parse C number %q: %w'
@@ -826,7 +826,7 @@ err.kb.decision.mkdir-dir:
   short: 'mkdir decisions parent: %w'
 err.kb.decision.open-file:
   short: 'open decisions: %w'
-err.kb.decision.write-row:
+err.kb.decision.append-row:
   short: 'write decisions row: %w'
 err.kb.decision.parse-dd-number:
   short: 'parse DD number %q: %w'
@@ -836,7 +836,7 @@ err.kb.question.mkdir-dir:
   short: 'mkdir questions parent: %w'
 err.kb.question.open-file:
   short: 'open questions: %w'
-err.kb.question.write-row:
+err.kb.question.append-row:
   short: 'write questions row: %w'
 err.kb.question.parse-q-number:
   short: 'parse Q number %q: %w'

internal/bootstrap/cmd.go

@@ -28,7 +28,7 @@ import (
 	writeBootstrap "github.com/ActiveMemory/ctx/internal/write/bootstrap"
 )
 
-// version is set at build time via ldflags:
+// version is set at build time via `ldflags`:
 //
 //	-X github.com/ActiveMemory/ctx/internal/bootstrap.version=$(cat VERSION)
 var version = cfgBootstrap.DefaultVersion
@@ -49,7 +49,7 @@ func RootCmd() *cobra.Command {
 		Long:    long,
 		Example: desc.Example(cmd.DescKeyCtx),
 		Version: version,
-		// Cobra auto-prints returned errors to stderr by default;
+		// Cobra auto-prints returned errors to standard error by default;
 		// main.go also prints them via writeErr.With, producing a
 		// double-printed error. Silence cobra's path so writeErr is
 		// the sole printer. (SilenceUsage stays per-return so

internal/cli/dream/core/doc.go

@@ -7,5 +7,7 @@
 // Package core groups the ctx dream command's domain logic into
 // focused subpackages: paths (root/notebook resolution), pass (one
 // executor-agnostic run), and dispose (loading a proposal by id and
-// applying accept/reject/amend through the engine).
+// applying accept/reject/amend through the engine). The command
+// itself stays a thin Cobra wrapper; all triage behavior lives here
+// so it can be exercised without the CLI layer.
 package core

internal/cli/dream/core/paths/doc.go

@@ -7,5 +7,7 @@
 // Package paths resolves the ctx dream working locations from the
 // cwd-anchored project root: the gitignored dreams/ notebook and the
 // ideas/ source directory. The project root is the parent of the
-// .context directory, by contract.
+// .context directory, by contract. Resolution is pure path
+// computation — it does not create directories or read their
+// contents, leaving those side effects to the caller.
 package paths

internal/cli/hub/cmd/revoke/cmd.go

@@ -47,7 +47,7 @@ func Cmd() *cobra.Command {
 			// the CTX_HUB_ADMIN_TOKEN environment variable.
 			token := adminToken
 			if token == "" {
-				token = os.Getenv(env.HubAdminToken)
+				token = os.Getenv(env.HubAdmin)
 			}
 			if token == "" {
 				cobraCmd.SilenceUsage = true
@@ -59,7 +59,7 @@ func Cmd() *cobra.Command {
 
 	flagbind.StringFlag(
 		c, &adminToken,
-		cFlag.Token, flag.DescKeyHubRevokeToken,
+		cFlag.Token, flag.DescKeyHubRevokeAuth,
 	)
 
 	return c

internal/cli/kb/core/topic/template.go

@@ -25,7 +25,7 @@ import (
 //   - string: substituted body.
 func Substitute(body, name, slug string) string {
 	body = strings.ReplaceAll(body, cfgKbCli.TokenTopicName, name)
-	body = strings.ReplaceAll(body, cfgKbCli.TokenTopicSlug, slug)
+	body = strings.ReplaceAll(body, cfgKbCli.TopicSlugPlaceholder, slug)
 	body = strings.ReplaceAll(body, cfgKbCli.TokenName, name)
 	body = strings.ReplaceAll(body, cfgKbCli.TokenSlug, slug)
 	return body

internal/cli/pad/core/tag/types.go

@@ -7,6 +7,10 @@
 package tag
 
 // Count holds a tag name and its occurrence count.
+//
+// Fields:
+//   - Tag: The tag name
+//   - Count: Number of occurrences of the tag
 type Count struct {
 	Tag   string `json:"tag"`
 	Count int    `json:"count"`

internal/cli/trace/core/file/file.go

@@ -58,7 +58,7 @@ func ParsePathArg(arg string) string {
 	return arg[:idx]
 }
 
-// TraceFile runs git log to retrieve commits touching the given file and
+// Trace runs git log to retrieve commits touching the given file and
 // prints context refs for each commit.
 //
 // Parameters:

internal/cli/trace/core/show/types.go

@@ -7,6 +7,14 @@
 package show
 
 // JSONRef represents a resolved context reference for JSON output.
+//
+// Fields:
+//   - Raw: The reference as written (e.g. "T-3")
+//   - Type: Reference kind (task, decision, learning, ...)
+//   - Number: Numeric ID parsed from the reference (0 if none)
+//   - Title: Resolved entry title (empty if not found)
+//   - Detail: Additional resolved detail (empty if not found)
+//   - Found: True when the reference resolved to a known entry
 type JSONRef struct {
 	Raw    string `json:"raw"`
 	Type   string `json:"type"`
@@ -17,6 +25,11 @@ type JSONRef struct {
 }
 
 // JSONCommit represents a commit with its context refs for JSON output.
+//
+// Fields:
+//   - Commit: The commit hash
+//   - Message: The commit subject line
+//   - Refs: Context references found in the commit
 type JSONCommit struct {
 	Commit  string    `json:"commit"`
 	Message string    `json:"message"`

internal/config/embed/flag/hub.go

@@ -18,7 +18,6 @@ const (
 	DescKeyHubStartPeers = "hub.start.peers"
 	// DescKeyHubStopDataDir is the text key for hub stop --data-dir.
 	DescKeyHubStopDataDir = "hub.stop.data-dir"
-	// DescKeyHubRevokeToken is the text key for hub revoke --token.
-	//nolint:gosec // G101: i18n desc key, not a credential
-	DescKeyHubRevokeToken = "hub.revoke.token"
+	// DescKeyHubRevokeAuth is the text key for hub revoke --token.
+	DescKeyHubRevokeAuth = "hub.revoke.token"
 )

internal/config/embed/text/err_hub.go

@@ -8,9 +8,9 @@ package text
 
 // DescKeys for hub error messages.
 const (
-	// DescKeyErrHubGenerateToken is the text key for token
+	// DescKeyErrHubGenerateFailed is the text key for token
 	// generation failures.
-	DescKeyErrHubGenerateToken = "err.hub.generate-token"
+	DescKeyErrHubGenerateFailed = "err.hub.generate-token"
 	// DescKeyErrHubInternal is the text key for internal hub
 	// errors.
 	DescKeyErrHubInternal = "err.hub.internal"
@@ -20,9 +20,9 @@ const (
 	// DescKeyErrHubUnknownClient is the text key for a
 	// revocation targeting a client ID that is not registered.
 	DescKeyErrHubUnknownClient = "err.hub.unknown-client"
-	// DescKeyErrHubAdminTokenRequired is the text key for an
+	// DescKeyErrHubAdminRequired is the text key for an
 	// admin-gated command invoked with no admin token supplied.
-	DescKeyErrHubAdminTokenRequired = "err.hub.admin-token-required"
+	DescKeyErrHubAdminRequired = "err.hub.admin-token-required"
 	// DescKeyErrHubInvalidPeerAction is the text key for
 	// unrecognized peer action errors.
 	DescKeyErrHubInvalidPeerAction = "err.hub.invalid-peer-action"

internal/config/embed/text/err_kb_artifacts.go

@@ -16,8 +16,8 @@ const (
 	// DescKeyErrKbGlossaryOpenFile wraps an open-for-append
 	// failure.
 	DescKeyErrKbGlossaryOpenFile = "err.kb.glossary.open-file"
-	// DescKeyErrKbGlossaryWriteRow wraps a row-write failure.
-	DescKeyErrKbGlossaryWriteRow = "err.kb.glossary.write-row"
+	// DescKeyErrKbGlossaryAppendRow wraps a row-write failure.
+	DescKeyErrKbGlossaryAppendRow = "err.kb.glossary.append-row"
 )
 
 // Timeline writer DescKeys.
@@ -30,8 +30,8 @@ const (
 	// DescKeyErrKbTimelineOpenFile wraps an open-for-append
 	// failure.
 	DescKeyErrKbTimelineOpenFile = "err.kb.timeline.open-file"
-	// DescKeyErrKbTimelineWriteRow wraps a row-write failure.
-	DescKeyErrKbTimelineWriteRow = "err.kb.timeline.write-row"
+	// DescKeyErrKbTimelineAppendRow wraps a row-write failure.
+	DescKeyErrKbTimelineAppendRow = "err.kb.timeline.append-row"
 )
 
 // Source-map writer DescKeys.
@@ -44,8 +44,8 @@ const (
 	// DescKeyErrKbSourcemapOpenFile wraps an open-for-append
 	// failure.
 	DescKeyErrKbSourcemapOpenFile = "err.kb.sourcemap.open-file"
-	// DescKeyErrKbSourcemapWriteRow wraps a row-write failure.
-	DescKeyErrKbSourcemapWriteRow = "err.kb.sourcemap.write-row"
+	// DescKeyErrKbSourcemapAppendRow wraps a row-write failure.
+	DescKeyErrKbSourcemapAppendRow = "err.kb.sourcemap.append-row"
 )
 
 // Relationship-map writer DescKeys.
@@ -59,9 +59,9 @@ const (
 	// DescKeyErrKbRelationshipOpenFile wraps an open-for-append
 	// failure.
 	DescKeyErrKbRelationshipOpenFile = "err.kb.relationship.open-file"
-	// DescKeyErrKbRelationshipWriteRow wraps a row-write
+	// DescKeyErrKbRelationshipAppendRow wraps a row-write
 	// failure.
-	DescKeyErrKbRelationshipWriteRow = "err.kb.relationship.write-row"
+	DescKeyErrKbRelationshipAppendRow = "err.kb.relationship.append-row"
 )
 
 // Contradiction writer DescKeys.
@@ -75,9 +75,9 @@ const (
 	// DescKeyErrKbContradictionOpenFile wraps an
 	// open-for-append failure.
 	DescKeyErrKbContradictionOpenFile = "err.kb.contradiction.open-file"
-	// DescKeyErrKbContradictionWriteRow wraps a row-write
+	// DescKeyErrKbContradictionAppendRow wraps a row-write
 	// failure.
-	DescKeyErrKbContradictionWriteRow = "err.kb.contradiction.write-row"
+	DescKeyErrKbContradictionAppendRow = "err.kb.contradiction.append-row"
 	// DescKeyErrKbContradictionParseCNumber wraps a
 	// strconv.Atoi failure on a C-### digit string.
 	DescKeyErrKbContradictionParseCNumber = "err.kb.contradiction.parse-c-number"
@@ -93,8 +93,8 @@ const (
 	// DescKeyErrKbDecisionOpenFile wraps an open-for-append
 	// failure.
 	DescKeyErrKbDecisionOpenFile = "err.kb.decision.open-file"
-	// DescKeyErrKbDecisionWriteRow wraps a row-write failure.
-	DescKeyErrKbDecisionWriteRow = "err.kb.decision.write-row"
+	// DescKeyErrKbDecisionAppendRow wraps a row-write failure.
+	DescKeyErrKbDecisionAppendRow = "err.kb.decision.append-row"
 	// DescKeyErrKbDecisionParseDDNumber wraps a strconv.Atoi
 	// failure on a DD-### digit string.
 	DescKeyErrKbDecisionParseDDNumber = "err.kb.decision.parse-dd-number"
@@ -110,8 +110,8 @@ const (
 	// DescKeyErrKbQuestionOpenFile wraps an open-for-append
 	// failure.
 	DescKeyErrKbQuestionOpenFile = "err.kb.question.open-file"
-	// DescKeyErrKbQuestionWriteRow wraps a row-write failure.
-	DescKeyErrKbQuestionWriteRow = "err.kb.question.write-row"
+	// DescKeyErrKbQuestionAppendRow wraps a row-write failure.
+	DescKeyErrKbQuestionAppendRow = "err.kb.question.append-row"
 	// DescKeyErrKbQuestionParseQNumber wraps a strconv.Atoi
 	// failure on a Q-### digit string.
 	DescKeyErrKbQuestionParseQNumber = "err.kb.question.parse-q-number"

internal/config/embed/text/err_kb_evidence.go

@@ -23,9 +23,9 @@ const (
 	// DescKeyErrKbEvidenceOpenIndex wraps an open-for-append
 	// failure on the evidence-index.
 	DescKeyErrKbEvidenceOpenIndex = "err.kb.evidence.open-index"
-	// DescKeyErrKbEvidenceWriteRow wraps a row-write failure on
+	// DescKeyErrKbEvidenceAppendRow wraps a row-write failure on
 	// the evidence-index.
-	DescKeyErrKbEvidenceWriteRow = "err.kb.evidence.write-row"
+	DescKeyErrKbEvidenceAppendRow = "err.kb.evidence.append-row"
 	// DescKeyErrKbEvidenceParseIDNumber wraps a strconv.Atoi
 	// failure parsing an EV-### number.
 	DescKeyErrKbEvidenceParseIDNumber = "err.kb.evidence.parse-id-number"

internal/config/env/doc.go

@@ -20,7 +20,7 @@
 //   - Home: the user's home directory ($HOME)
 //   - CtxDir: overrides the default .context/
 //     directory location ($CTX_DIR)
-//   - CtxTokenBudget: overrides the default token
+//   - CtxBudget: overrides the default token
 //     budget for context window sizing
 //     ($CTX_TOKEN_BUDGET)
 //   - SessionID: active AI session identifier used

internal/config/env/env.go

@@ -14,21 +14,19 @@ const (
 	Home = "HOME"
 	// User is the environment variable for the current username.
 	User = "USER"
-	// CtxTokenBudget is the environment variable for overriding
+	// CtxBudget is the environment variable for overriding
 	// the token budget.
-	//nolint:gosec // G101: env var name, not a credential
-	CtxTokenBudget = "CTX_TOKEN_BUDGET"
+	CtxBudget = "CTX_TOKEN_BUDGET"
 	// SessionID is the environment variable for the active AI session ID.
 	// Used by ctx trace for context linking.
 	SessionID = "CTX_SESSION_ID"
 	// SkipPathCheck is the environment variable that skips the PATH
 	// validation during init. Set to True in tests.
 	SkipPathCheck = "CTX_SKIP_PATH_CHECK"
-	// HubAdminToken is the environment variable holding the hub
+	// HubAdmin is the environment variable holding the hub
 	// admin token, used as a fallback when --token is not passed
 	// to admin-gated commands like `ctx hub revoke`.
-	//nolint:gosec // G101: env var name, not a credential
-	HubAdminToken = "CTX_HUB_ADMIN_TOKEN"
+	HubAdmin = "CTX_HUB_ADMIN_TOKEN"
 )
 
 // Environment toggle values.

internal/config/handover/handover.go

@@ -48,11 +48,9 @@ const FoldEntryPrefix = "- `"
 // mode field with a colon.
 const FoldEntryModePrefix = "`: mode="
 
-// FoldEntryPassModePrefix opens the optional pass-mode field
+// FoldEntryModeAttrPrefix opens the optional pass-mode field
 // in a folded entry's metadata section.
-//
-//nolint:gosec // G101: literal markdown delimiter, not a credential
-const FoldEntryPassModePrefix = ", pass-mode="
+const FoldEntryModeAttrPrefix = ", pass-mode="
 
 // FoldEntryGeneratedAtPrefix opens the generated-at timestamp
 // in a folded entry's metadata section.