@rmyndharis/aimhooman 0.2.0 → 0.3.1

package/rules/paths.json

@@ -216,120 +216,6 @@
             "git restore --staged <path>"
         ]
     },
-    {
-        "id": "secret.dotenv",
-        "version": 4,
-        "provider": "generic",
-        "category": "secret",
-        "confidence": "high",
-        "kind": "path",
-        "match": {
-            "path_case": "insensitive",
-            "paths": [
-                ".env",
-                "**/.env",
-                ".env.*",
-                "**/.env.*"
-            ],
-            "except": [
-                "**/*.example",
-                "**/*.sample",
-                "**/*.template",
-                "**/*.dist",
-                "**/*.defaults",
-                "**/*.minimal"
-            ]
-        },
-        "actions": {
-            "clean": "block",
-            "strict": "block",
-            "compliance": "block"
-        },
-        "reason": "Environment files often carry secrets and should not be committed.",
-        "remediation": [
-            "git restore --staged <path>",
-            "commit a .env.example with placeholders instead"
-        ]
-    },
-    {
-        "id": "secret.private-key",
-        "version": 3,
-        "provider": "generic",
-        "category": "secret",
-        "confidence": "high",
-        "kind": "path",
-        "match": {
-            "path_case": "insensitive",
-            "paths": [
-                "**/id_rsa",
-                "**/id_dsa",
-                "**/id_ecdsa",
-                "**/id_ed25519",
-                "**/*.p12",
-                "**/*.pfx"
-            ]
-        },
-        "actions": {
-            "clean": "block",
-            "strict": "block",
-            "compliance": "block"
-        },
-        "reason": "A path matching a private-key filename (id_rsa, id_ed25519, *.p12, *.pfx, ...) is blocked by name — content is not inspected. If this is a real key, it must never be committed; if the name is coincidental, rename the file.",
-        "remediation": [
-            "git restore --staged <path>",
-            "if this is a real key, rotate it if it was ever exposed",
-            "if the name is coincidental (a fixture, a doc), rename the file so it no longer matches a private-key pattern"
-        ]
-    },
-    {
-        "id": "secret.aws-credentials",
-        "version": 2,
-        "provider": "generic",
-        "category": "secret",
-        "confidence": "high",
-        "kind": "path",
-        "match": {
-            "path_case": "insensitive",
-            "paths": [
-                ".aws/credentials",
-                "**/.aws/credentials"
-            ]
-        },
-        "actions": {
-            "clean": "block",
-            "strict": "block",
-            "compliance": "block"
-        },
-        "reason": "AWS credentials must never be committed.",
-        "remediation": [
-            "git restore --staged <path>"
-        ]
-    },
-    {
-        "id": "secret.claude-credentials",
-        "version": 1,
-        "provider": "claude-code",
-        "category": "secret",
-        "confidence": "high",
-        "kind": "path",
-        "match": {
-            "path_case": "insensitive",
-            "paths": [
-                ".claude/.credentials.json",
-                "**/.claude/.credentials.json"
-            ]
-        },
-        "actions": {
-            "clean": "block",
-            "strict": "block",
-            "compliance": "block"
-        },
-        "reason": "This file holds an OAuth access token and must never be committed.",
-        "remediation": [
-            "git restore --staged <path>",
-            "Revoke the token if it already reached a commit."
-        ]
-    },
     {
         "id": "generic.agent-instructions",
         "version": 2,

package/schemas/overrides.schema.json

@@ -14,7 +14,10 @@
             "required": ["target"],
             "properties": {
                 "target": { "type": "string", "minLength": 1 },
-                "scope": { "enum": ["path", "rule", "secret-path"] },
+                "scope": {
+                    "enum": ["path", "rule"],
+                    "$comment": "v0.3.0 retired the secret-path scope with built-in secret scanning; the loader drops legacy entries with a warning instead of failing the file."
+                },
                 "reason": { "type": "string" },
                 "actor": { "type": "string" },
                 "at": { "type": "string", "format": "date-time" }

package/skills/aimhooman/SKILL.md

@@ -3,8 +3,8 @@ name: aimhooman
 description: >
   Keep AI tooling artifacts out of Git. Use whenever staging, committing, or
   pushing changes: block AI session/state files (.claude/session.json,
-  .codex/history, .copilot, .cursor/session, .aider.*, .specstory, .agent),
-  secrets (.env, private keys, .aws/credentials), and unwanted AI attribution in
+  .codex/history, .copilot, .cursor/session, .aider.*, .specstory, .agent)
+  and unwanted AI attribution in
   commit messages (Co-authored-by an AI, "Generated with AI"). Also use when the user says
   "aimhooman", "ship it like a hooman", or asks to clean AI residue before a commit.
 license: MIT
@@ -24,13 +24,16 @@ Its policy:
   `.copilot/*`, `.cursor/session*`, `.cursor/chats/*`, `.cursor/logs/*`,
   `.aider.*`, `.specstory/*`, `.continue/sessions/*`, `.playwright-mcp/*`,
   `.remember/*`, `.superpowers/*`, and `.agent/*`. The examples are not
-  exhaustive; the packaged `rules/paths.json` is the detection source of truth.
-  If one is staged, unstage it and keep it out of Git instead.
+  exhaustive; the packaged `rules/paths.json` is the detection source of truth
+  for these artifacts. If one is staged, unstage it and keep it out of Git
+  instead.
 - Never commit secrets: a real `.env` (not `.env.example`), private keys
   (`id_rsa` and files containing a private-key header), `.aws/credentials`,
   `.claude/.credentials.json`, service-account keys, or a provider API key
   (GitHub, GitLab, npm, Slack, Anthropic, OpenAI, Google, Stripe, Hugging Face,
-  SendGrid). Public certificates are allowed.
+  SendGrid). Public certificates are allowed. aimhooman does not scan for
+  secrets — this rule is on you, and a dedicated scanner such as gitleaks is
+  the right backstop for it.
 - Never add AI attribution to commit messages: no `Co-authored-by` trailer naming
   an AI (Claude, Copilot, Codex), no "Generated with/by <AI>" lines, no AI-service
   noreply emails. A commit message reads as if a human wrote it.
@@ -61,7 +64,7 @@ npm test
 npm run test:coverage
 ```
 
-aimhooman also enforces this at commit time, so a blocked commit means a real
-violation to fix, not a check to bypass. The rule is simple: AI works, hoomans
-ship.
+aimhooman also enforces the artifact and attribution rules at commit time, so
+a blocked commit means a real violation to fix, not a check to bypass. The rule
+is simple: AI works, hoomans ship.
 <!-- aimhooman:ruleset-end -->

package/src/args.mjs

@@ -27,7 +27,7 @@ export function parseArguments(args, definition = {}) {
             const inlineValue = equal > 0 ? argument.slice(equal + 1) : undefined;
             const option = byName.get(name);
             if (!option) throw new ArgumentError(`unknown option "${name}"`);
-            if (seen.has(option.key) && !option.repeatable) {
+            if (seen.has(option.key)) {
                 throw new ArgumentError(`option "${name}" may only be used once`);
             }
             seen.add(option.key);
@@ -49,12 +49,7 @@ export function parseArguments(args, definition = {}) {
             if (option.choices && !option.choices.includes(value)) {
                 throw new ArgumentError(`invalid value for ${name}: "${value}"`);
             }
-            if (option.repeatable) {
-                if (!options[option.key]) options[option.key] = [];
-                options[option.key].push(value);
-            } else {
-                options[option.key] = value;
-            }
+            options[option.key] = value;
             continue;
         }
         positionals.push(argument);

package/src/exclude.mjs

@@ -8,8 +8,8 @@ const END = '# <<< aimhooman managed excludes';
 
 // Local AI residue kept out of `git status`. Deriving this list from the rule
 // catalog prevents the prevention layer from drifting behind enforcement. We
-// intentionally exclude only unambiguous tooling state/settings: secret and
-// review-required rules must remain visible to users.
+// intentionally exclude only unambiguous tooling state/settings: review-
+// required and policy rules must remain visible to users.
 const AUTO_EXCLUDE_CATEGORIES = new Set(['ephemeral-state', 'local-settings']);
 
 export function patternsForRules(rules) {

package/src/gitx.mjs

@@ -1,17 +1,5 @@
 import { execFileSync } from 'node:child_process';
-import {
-    cpSync,
-    lstatSync,
-    mkdirSync,
-    mkdtempSync,
-    readFileSync,
-    realpathSync,
-    readdirSync,
-    readlinkSync,
-    renameSync,
-    rmSync,
-    symlinkSync,
-} from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { gitEnvironment, GIT_TIMEOUT_MS } from './git-environment.mjs';
 

package/src/hook.mjs

@@ -8,6 +8,7 @@ import { newEngineWithDiagnostics } from './scan.mjs';
 import { openRepo, stagedEntries } from './gitx.mjs';
 import { applyExclude, patternsForRules } from './exclude.mjs';
 import { activeGitHook, installedHooks } from './githooks.mjs';
+import { loadConfig } from './state.mjs';
 import { visible } from './report.mjs';
 import { extractRuleset } from './ruleset-text.mjs';
 import { resolvePolicy } from './policy-resolver.mjs';
@@ -84,7 +85,25 @@ export function hookSessionStart() {
         const repo = openRepo();
         const policy = resolvePolicy(repo, { target: 'worktree' });
         const { engine: eng } = newEngineWithDiagnostics(policy.profile, repo.stateDir);
-        applyExclude(repo.excludeFile, patternsForRules(eng.rules));
+        const patterns = patternsForRules(eng.rules);
+        // Each refresh is housekeeping with its own silent failure, mirroring
+        // the pre-tool-use path: a read-only .git/info must not skip the
+        // worktree .gitignore refresh below, and neither may decide anything.
+        try {
+            applyExclude(repo.excludeFile, patterns);
+        } catch {
+            /* exclude refresh is best effort */
+        }
+        // A clone that opted into the committed variant gets the same refresh in
+        // its worktree .gitignore; every failure degrades silently, same as the
+        // exclude write above.
+        try {
+            if (loadConfig(repo.stateDir).gitignore?.enabled) {
+                applyExclude(join(repo.root, '.gitignore'), patterns);
+            }
+        } catch {
+            /* gitignore refresh is best effort */
+        }
     } catch {
         /* not a repo; nothing to exclude */
     }
@@ -383,11 +402,23 @@ function hookPreToolUse(input) {
     // above so a read-only .git/info (CI checkout, read-only volume, a
     // repository owned by another user) cannot decide what is allowed.
     if (repo) {
+        const patterns = patternsForRules(eng.rules);
         try {
-            applyExclude(repo.excludeFile, patternsForRules(eng.rules));
+            applyExclude(repo.excludeFile, patterns);
         } catch (e) {
             hygieneWarning = `could not refresh ${repo.excludeFile}: ${e.message}`;
         }
+        // The committed variant of the block gets the same best-effort refresh
+        // when this clone opted into it; a failure there is housekeeping too,
+        // never part of the verdict.
+        try {
+            if (loadConfig(repo.stateDir).gitignore?.enabled) {
+                applyExclude(join(repo.root, '.gitignore'), patterns);
+            }
+        } catch (e) {
+            const gitignoreWarning = `could not refresh ${join(repo.root, '.gitignore')}: ${e.message}`;
+            hygieneWarning = hygieneWarning ? `${hygieneWarning}; ${gitignoreWarning}` : gitignoreWarning;
+        }
     }
     // A strict policy cannot make a meaningful guarantee if Git's own guards
     // are explicitly bypassed. Deny before the shell can stage-and-commit in a
@@ -402,7 +433,7 @@ function hookPreToolUse(input) {
     // A preceding command that may have changed the repository or its hooks is
     // also a potential pre-commit bypass. Strict rejects it above; clean and
     // compliance still need the staged-content backstop so a hook mutation
-    // cannot expose a secret that was already in the index.
+    // cannot sneak a blocked staged file past the guard.
     const commitPrefixRisk = parsed.commands.some((candidate) => (
         (candidate.verb === 'commit' || candidate.verb === 'unknown')
         && candidate.prefixRisk
@@ -426,8 +457,8 @@ function hookPreToolUse(input) {
     // them. A build, a test run, ls — those leave pre-commit to answer, and
     // refusing them taught agents to drop the `&&` gate rather than to run the
     // command separately. hiddenBypass stays wider on purpose; it is what keeps
-    // the staged-content backstop reading the blobs, so a secret already in the
-    // index still stops the commit here.
+    // the staged-content backstop reading the blobs, so a blocked file already
+    // in the index still stops the commit here.
     const prefixHookBypass = opaqueCommitRisk
         || (commitPrefixRisk && (noVerify || bypassHooks || parsed.prefixHooksRisk));
     // The same distinction, for the deny paths that ask "will anything scan this
@@ -460,7 +491,7 @@ function hookPreToolUse(input) {
     const blocks = [];
     // potentialCommit treats a command as leading to a commit. uncertainShell
     // was too broad: it flagged any pipe, so a benign read-only pipeline
-    // (gh ... | tail) was scanned and denied as if it staged a secret.
+    // (gh ... | tail) was scanned and denied as if it staged a blocked file.
     // opaqueCommitHiding keeps every commit-hiding shape (subshells,
     // substitution, script-feeds, code-executing/unlisted pipe segments) while
     // excluding pipelines of known read-only commands.
@@ -503,8 +534,8 @@ function hookPreToolUse(input) {
     // disables the real pre-commit guard, leaving this hook the only check.
     // When the commit also stages files at commit time (-a/--all/-u/--patch, or
     // a preceding `git add`), those files are neither in stagedPaths(repo) now
-    // nor in addPaths, so they were never scanned. Rather than let an unscanned
-    // secret through, deny. (Strict already denied the bypass above.) The rare
+    // nor in addPaths, so they were never scanned. Rather than let unscanned
+    // content through, deny. (Strict already denied the bypass above.) The rare
     // false-positive on an explicit `git add <path> && git commit --no-verify`
     // is safe-side; drop --no-verify to proceed.
     //
@@ -512,7 +543,8 @@ function hookPreToolUse(input) {
     // a --no-verify inside the inner command, where parsed.noVerify cannot see
     // it (the parser only inspects literal argv). Such an uncertain commit is
     // therefore treated as a potential hook bypass for the clean/compliance
-    // secret backstop, so a secret cannot slip past the guard wrapped in eval.
+    // staged-content backstop, so a blocked file cannot slip past the guard
+    // wrapped in eval.
     const indexReplacement = parsed.commands.some((candidate) => (
         candidate.verb === 'commit' && candidate.indexMutationRisk
     ));
@@ -553,9 +585,9 @@ function hookPreToolUse(input) {
     }
     // clean / compliance: advisory only (the git pre-commit unstage is the real
     // enforcement) — except when --no-verify/core.hooksPath bypasses that hook.
-    // A bypassed guard is the one case clean cannot delegate to git, so a blocked
-    // secret is denied here, matching the documented "secret stops the commit when
-    // automatic unstaging fails"; hygiene findings stay advisory.
+    // A bypassed guard is the one case clean cannot delegate to git, so a
+    // secret-category finding (a local rule pack can still declare one) is
+    // denied here; hygiene findings stay advisory.
     const bypassed = Boolean(potentialCommit && hiddenBypass);
     if (bypassed && blocks.some((f) => f.category === 'secret')) {
         return emitDecision(

package/src/report.mjs

@@ -7,33 +7,6 @@
 // for the rest. The JSON report (aimhooman review / --json) is never capped.
 const HUMAN_FINDING_CAP = 20;
 
-// UT-06: prefix -> provider for secret.provider-token findings. The rule packs
-// every provider into one pattern set (rules/secrets.json), so the provider
-// name is recovered from the raw matched line at report time — before the
-// redaction below runs. Only the label is ever rendered, never the token.
-// Mirrors the rule's patterns; keep the rule's alternation order.
-const TOKEN_PROVIDERS = [
-    ['ghp_', 'GitHub'], ['gho_', 'GitHub'], ['ghu_', 'GitHub'], ['ghs_', 'GitHub'],
-    ['ghr_', 'GitHub'], ['github_pat_', 'GitHub'],
-    ['glpat-', 'GitLab'],
-    ['npm_', 'npm'],
-    ['xoxb-', 'Slack'], ['xoxp-', 'Slack'], ['xoxa-', 'Slack'], ['xoxr-', 'Slack'], ['xoxs-', 'Slack'],
-    ['sk-ant-', 'Anthropic'],
-    ['sk-proj-', 'OpenAI'],
-    ['AIza', 'Google'],
-    ['sk_live_', 'Stripe'], ['rk_live_', 'Stripe'],
-    ['hf_', 'Hugging Face'],
-    ['SG.', 'SendGrid'],
-];
-
-function tokenProvider(text) {
-    if (!text) return undefined;
-    for (const [prefix, provider] of TOKEN_PROVIDERS) {
-        if (text.includes(prefix)) return provider;
-    }
-    return undefined;
-}
-
 export function human(findings, tone) {
     if (!findings.length) return '';
     let out = tone === 'professional' ? '\n' : '\nnot very hooman.\n\n';
@@ -56,22 +29,16 @@ export function human(findings, tone) {
         const related = (f.matchedRuleIds || []).filter((id) => id !== f.ruleId);
         const identity = related.length ? `${f.ruleId} (+ ${related.join(', ')})` : f.ruleId;
         const commit = f.commit ? ` [commit ${String(f.commit).slice(0, 12)}]` : '';
-        // UT-06: a provider-token finding used to say only "a provider access
-        // token", leaving the developer to guess which credential to revoke.
-        // Name the provider in the reason; the token itself stays redacted.
-        const provider = f.ruleId === 'secret.provider-token' ? tokenProvider(f.text) : undefined;
-        const reason = provider
-            ? f.reason.replace('provider access token', `provider access token (${provider})`)
-            : f.reason;
-        out += `${f.decision.toUpperCase().padEnd(6)} ${identity}${commit}\n       ${loc}\n       ${reason}\n`;
+        out += `${f.decision.toUpperCase().padEnd(6)} ${identity}${commit}\n       ${loc}\n       ${f.reason}\n`;
         if (f.text && f.text.trim()) {
             out += `       > ${isSensitive(f) ? '[redacted]' : visible(f.text.trim())}\n`;
         }
         // Render the whole remediation array, not just the first entry. Several
-        // rules carry a second line (e.g. "rotate the key if it was ever exposed")
-        // that the previous single-index render dropped silently. UT-08: print a
-        // rule's fix once — a repeated rule (20 hits of the same secret rule)
-        // used to reprint the identical fix block for every finding.
+        // rules carry a second line (e.g. "or unstage if it is personal" on
+        // generic.agent-instructions) that the previous single-index render
+        // dropped silently. UT-08: print a rule's fix once — a repeated rule
+        // (20 hits of the same path rule) used to reprint the identical fix
+        // block for every finding.
         const remedies = f.remediation || [];
         if (remedies.length && fixesPrinted.has(f.ruleId)) {
             out += `       fix: as above for ${f.ruleId}\n`;
@@ -111,13 +78,22 @@ export function jsonReport(findings, metadata = {}) {
     return JSON.stringify({ schema_version: 1, ...metadata, findings: safe }, null, 2);
 }
 
+// Built-in secret scanning is gone, but a local rule pack can still declare
+// category "secret"; findings from such a rule keep their matched text out of
+// every report, the same courtesy the built-in rules got.
 function isSensitive(finding) {
     return finding?.category === 'secret'
         || finding?.matchedRules?.some((match) => match.category === 'secret') === true;
 }
 
 // Exit codes: 0 clean, 10 blocked, 11 review required, 31 incomplete scan.
-export function exitCode(findings, profile, complete = true) {
+// An incomplete scan stops the operation only where no later guard can vouch
+// for the skipped content: on the strict profile, or when the caller is the
+// final ref boundary (failClosedIncomplete). Frictionless profiles warn and
+// continue — the reference-transaction guard still scans introduced commits
+// with failClosedIncomplete set, so the skipped content is checked before any
+// ref moves.
+export function exitCode(findings, profile, complete = true, { failClosedIncomplete = false } = {}) {
     let block = false;
     let review = false;
     for (const f of findings) {
@@ -125,7 +101,7 @@ export function exitCode(findings, profile, complete = true) {
         else if (f.decision === 'review') review = true;
     }
     if (block) return 10;
-    if (!complete) return 31;
+    if (!complete && (profile === 'strict' || failClosedIncomplete)) return 31;
     if (review && findings.some((finding) => (finding.scanProfile || profile) !== 'clean')) return 11;
     return 0;
 }

package/src/scan-session.mjs

@@ -52,10 +52,10 @@ export function scanEntries(repo, engine, entries, options = {}) {
     }
 
     // Oversized files: probe the first 8 KB to separate binary from text.
-    // A binary file (PSD, WOFF, PNG) can't hide text-pattern secrets that
-    // the full content scan would find, so it skips as 'binary' (complete).
-    // A text file that exceeds the budget is a genuine 'size-limit' skip
-    // (incomplete) and the caller must raise the limit to cover it.
+    // A binary file (PSD, WOFF, PNG) holds no text lines the content rules
+    // could match, so it skips as 'binary' (complete). A text file that
+    // exceeds the budget is a genuine 'size-limit' skip (incomplete) and the
+    // caller must raise the limit to cover it.
     // Cap probing at 16 MiB: cat-file --batch reads the full blob into memory,
     // so probing a 500 MB file just to check for NULs is wasteful. Files above
     // the cap are classified as size-limit without probing.
@@ -100,25 +100,18 @@ export function scanEntries(repo, engine, entries, options = {}) {
         // Binary detection still reads the blob. Count every examined byte so
         // later commits cannot reset the total budget merely by using NUL data.
         stats.bytes_scanned += blob.length;
-        let matched;
         if (isBinary(blob)) {
+            // Content rules match text lines, so a binary blob carries nothing
+            // they could fire on. Skipping it loses no coverage: the skip is
+            // recorded as 'binary', which does not mark the scan incomplete.
             increment(stats.skipped, 'binary');
             appendPath(stats.skippedPaths, 'binary', entry.path, blob.length);
-            // Binary classification only skips text-oriented policy rules. Secret
-            // signatures are ASCII byte sequences, so latin1 preserves a
-            // one-byte-to-one-code-unit view and keeps the existing byte limits.
-            // Stripping NULs is what defeats hiding credential material behind
-            // them: one injected NUL breaks a signature, and a multi-byte
-            // encoding like UTF-16 injects one per character.
-            matched = engine.checkContent(entry.path, blob.toString('latin1').replace(/\0/g, ''), {
-                categories: ['secret'],
-            });
-        } else {
-            stats.files_scanned += 1;
-            const ranges = lineRanges.get(entry.path);
-            matched = engine.checkContent(entry.path, blob.toString('utf8'),
-                ranges && ranges.length ? { lineRanges: ranges } : {});
+            continue;
         }
+        stats.files_scanned += 1;
+        const ranges = lineRanges.get(entry.path);
+        const matched = engine.checkContent(entry.path, blob.toString('utf8'),
+            ranges && ranges.length ? { lineRanges: ranges } : {});
         stats.findings_total += matched.length;
         for (const finding of matched) {
             if (findings.length >= limits.maxFindings) continue;
@@ -139,7 +132,7 @@ export function scanEntries(repo, engine, entries, options = {}) {
     }
 
     const incompleteReasons = new Set([
-        'metadata-unavailable', 'size-limit', 'total-byte-limit', 'object-read-failed',
+        'metadata-unavailable', 'size-limit', 'total-byte-limit',
         'missing-object', 'unexpected-object', 'finding-limit', 'local-input-limit',
     ]);
     const complete = !Object.keys(stats.skipped).some((reason) => incompleteReasons.has(reason));
@@ -253,8 +246,8 @@ function isBinary(buffer) {
 //
 // Entries without commit/parents (tracked snapshots, staged views, root
 // commits) are omitted from the map; the caller treats a missing key as "scan
-// the whole blob" — the safe side for a secret scanner is to scan MORE, not
-// less, so a failure to compute hunks falls back to the pre-W4 behaviour.
+// the whole blob" — the safe side is to scan MORE, not less, so a failure to
+// compute hunks falls back to the pre-W4 behaviour.
 function collectLineRanges(repo, entries) {
     // Group text-candidate entries by their first parent to batch the diffs.
     // Key by `${commit}\0${parent}` so a merge with multiple parents produces

package/src/scan-target.mjs

@@ -389,8 +389,8 @@ function scanEntryGroup(repo, engine, entries, policy, accumulator, options = {}
     // Content scanning can target a narrower set than the path check. When
     // contentEntries is provided (e.g. only changed files in a commit), read
     // blobs only for those entries instead of the full snapshot. Path-based
-    // rules already ran on the full tree above, so secrets like .env are still
-    // caught even when their blob isn't re-read.
+    // rules already ran on the full tree above, so a path-only finding still
+    // fires even when its blob isn't re-read.
     const contentScannable = (options.contentEntries ?? entries)
         .filter((entry) => entry.status !== 'D' && entry.type !== 'deleted');
     const remaining = accumulator.remaining();
@@ -405,14 +405,14 @@ function scanEntryGroup(repo, engine, entries, policy, accumulator, options = {}
 function scanReviewPathChanges(engine, entries, policy, accumulator, options = {}) {
     for (const entry of entries) {
         // A deleted path is gone, so only structural policy rules (agent
-        // instructions, project policy) can still matter: deleting a secret or a
-        // session file is hygiene, not a violation. A renamed-away path is
-        // different — its content survives under a new name, so a path-only
-        // secret (e.g. .env) must still fire or a `git mv` to a neutral name
-        // would slip past the destination scan, which only catches content-shaped
-        // secrets. That finding is reported on the destination path (where the
-        // bytes now live) so clean-profile repair unstages the blob that carries
-        // the secret rather than the old name.
+        // instructions, project policy) can still matter: deleting a flagged
+        // file is hygiene, not a violation. A renamed-away path is different —
+        // its content survives under a new name, so a path-only secret-category
+        // rule from a local pack must still fire or a `git mv` to a neutral
+        // name would slip past the destination scan, which only catches
+        // content-shaped matches. That finding is reported on the destination
+        // path (where the bytes now live) so clean-profile repair unstages the
+        // blob that carries the match rather than the old name.
         const deleted = entry.status === 'D' || entry.type === 'deleted';
         const renamed = entry.status === 'R' && entry.sourcePath && entry.sourcePath !== entry.path;
         if (!deleted && !renamed) continue;