fix(analyze-service): an alias could silently shadow a real index entry, and an unmarked client-sensitive file read as publishable

[ZacxDev]

Four surgical repairs to the /analyze-service index schema, found by an experiment that hand-authored a process entry and an org entry in the current schema to see where it breaks. The larger "generalize into subsystems" proposal was rejected on that evidence — this PR adds no type:-driven sections, no dependency graph, no CLI. Prose/spec only, one file.

Deliberately does not touch scripts/analyze-service-index/, nix/home.nix or scripts/claude-hooks/ — #361 owns those, and claude/commands/analyze-service.md is not in its diff. Zero overlap.

1. Addressing — the shadowing bug

Two defects were conflated:

• A slug can collide between different kinds of thing: devrc/repo-cos names both a code subsystem and the weekly ritual about it.
• Worse, the old resolver matched filename and aliases: in one breath before declaring a miss — so an alias silently won and a later real entry became unreachable, with no error. Live example: bastion.md claims the alias ssh; a future real ssh.md would have been shadowed by it.

Fix:

• Optional kind-qualified filename <slug>.<kind>.md (repo-cos.process.md), kind ∈ service | process | org | doc, used only when disambiguation is needed. A trailing dot-segment counts as a kind only if it is in that enum, so a dotted slug is unaffected.
• Two-tier resolution, ambiguity is an ERROR. Tier 1 = filename (bare and qualified, together); tier 2 = aliases, consulted only when tier 1 returned zero hits. An alias can never outrank a filename. More than one hit in a tier → stop, call it ambiguous, list the candidates, let the human choose. Never pick.
• _ → - during normalization, keeping the pre-fold spelling in aliases:. The old rule (any char outside [a-z0-9._-] → -) preserved _, so image_ingestion ≠ image-ingestion — while the index links _-spelled MEMORY.md slugs throughout.

Backward compatibility is a hard requirement and is stated as one. None of the 20 existing files needs renaming, and none resolves differently:

• No existing filename contains _, so the fold changes nothing about what they match — image-ingestion.md, spine-controller.md, civitai-dp-prod.md resolve exactly as before.
• No existing filename has a second dot, so nothing is retroactively parsed as kind-qualified.
• With zero qualified files in a scope, tier 1 can only ever return 0 or 1 hit — bit-identical to today's behaviour.
• Alias resolution still works and now works better: pghero.md carries aliases: [pg-hero, pg_hero]; both fold to pg-hero, both still resolve, and pg_hero now also matches when typed against a --spelled entry.

2. Sensitivity marking

New sensitivity: front-matter field — client-confidential | personal | public — with a fail-safe default: absent or unrecognized means client-confidential, never public, and public is a deliberate operator claim a recon run may never infer.

This is live, not hypothetical: bastion.md:10 carries a client bastion's public IP and SSH port, orchestration.md names a client engineer by handle, and several aliases: lists carry client hostnames. The spec now writes down that the store must never gain a git remote and that none of its content may be copied into devrc (PUBLIC) or any other public repo, PR body, issue, gist or commit message — pointing at 60e6d9d, which exists because this exact data class had to be scrubbed retroactively.

Marking only. Enforcement lands separately, on top of #361.

3. Front-matter repair

• repo: → scope:, and a scope may be a non-repo word — a ritual is owned by no repo, a client spans several. <repo-slug> derivation stays the default so nothing breaks; older files still carrying repo: read as scope.
• namespace: becomes optional rather than removed — genuinely load-bearing for k8s infra entries, and meaningless for the non-infra test entries that were reduced to writing n/a. Omit it rather than writing n/a.

4. Process-liveness convention

"Is this still being followed?" is the question for a process subsystem, but the anti-bloat rule forbids persisting live status — correctly, for infra, where a kubectl is two seconds away. For a ritual there is no live probe.

Convention: persist the derivation method and the stale-tell, never the current reading. From the experiment — liveness of a weekly ritual was derived from an exclusions-file mtime vs. the timer's last fire; that method is the durable knowledge, and the answer it returned ("last followed 2026-08-01") is live status exactly like a pod count and stays forbidden. Written as an application of the existing rule, nested under it, not an exception to it.

Byte budget

12,460 → 15,358 (+2,898). Evictions taken in the same commit to offset:

• the recon-start index-read paragraph was stated twice, near-verbatim — kept the operational copy in step 1;
• "Always re-derived live" on Lives at / Config duplicated the Provenance-honesty line three lines below them;
• the "Pointers, not copies" bloat bullet restated the ## Pointers schema it sits under.

Verification

• test_no_public_ips.py + test_no_client_hostnames.py: 33 passed on this branch.
• Negative control on that gate — injecting a routable IP into this file makes test_no_public_ips fail naming this exact path and line, so the green is a real read of the changed file, not a scan that misses it. Reverted; file restored byte-identical.
• Full scripts/tests suite: 26 failed / 1388 passed on this branch and the identical 26 failures, by name, at the untouched base checkout. They are ad-hoc-nix-shell toolchain gaps (no logrotate on PATH, no opencode engine, run-tests preconditions harness), not regressions from this change.
• No new files, so nothing can be silently omitted from the flake deploy.

Takes effect only after a home-manager switch — this path is a read-only nix-store symlink at ~/.claude/commands/, and it also ships to opencode.

🤖 Generated with Claude Code