LLP 0103 names its CLI and reporting sections; the usage-policy fail-safe refs cite a live doc

llp/0103-machine-local-policy-classes.decision.md

@@ -60,7 +60,7 @@ the sensitive thing.
   The implicit default for unlisted directories remains `full`: enrollment,
   backfill, and the first sync keep meaning "everything you did not opt out
   ships".
-- **CLI**: `hyp ignore <path>` keeps its [LLP 0049 §cli](./0049-hypignore-usage-policy.spec.md#cli)
+- **CLI** {#cli}: `hyp ignore <path>` keeps its [LLP 0049 §cli](./0049-hypignore-usage-policy.spec.md#cli)
   dotfile meaning unchanged (repurposing a settled verb silently would be
   worse than a new flag). Machine-local writes get flags on the same verb:
   the existing `--local-only`, a new `--private` for a machine-local
@@ -85,7 +85,8 @@ the sensitive thing.
   ([LLP 0049 R1](./0049-hypignore-usage-policy.spec.md#requirements) applies
   to the new source unchanged); already-cached rows are
   [`hyp purge`](./0104-hyp-purge.decision.md)'s job.
-- `hyp ignore --check` and `hyp status` reporting must name which source
-  governs (dotfile vs machine-local entry) or debugging gets harder.
+- **Reporting names the governing source** {#reporting}: `hyp ignore --check`
+  and `hyp status` reporting must name which source governs (dotfile vs
+  machine-local entry) or debugging gets harder.
 - The store keeps every LLP 0071 property: never forwarded, never merged with
   config, survives cache rebuilds, untouched by `hyp leave`.

llp/0135-install-experience-overhaul.design.md

@@ -956,8 +956,9 @@ with `skip_reason` when it did not run). `hyp query overview` emits its own
 counts). The
 existing `walkthrough.start`/`write_config`/`finish` spans rename to their
 `wizard.*` equivalents in the same change that moves the code, per CLAUDE.md's
-"update or remove the `@ref` if not" rule for the `@ref LLP 0011#interactive-
-walkthrough` annotation currently on `runPickerWalkthrough`.
+"update or remove the `@ref` if not" rule for the
+`@ref LLP 0011#interactive-walkthrough` annotation currently on
+`runPickerWalkthrough`.
 
 ## Open questions {#open-questions}
 

src/core/commands/clients.js

@@ -1071,7 +1071,7 @@ export async function runUnmarkMachineLocal({ targetDir, ctx, targetClass, compo
  * `policy show`.
  *
  * @ref LLP 0049#prospective-only [implements]: `--check` reports the residual already-cached row count; it never deletes
- * @ref LLP 0103#cli [implements]: `--check` names which source governs (dotfile vs machine-local entry) and the entry's class
+ * @ref LLP 0103#reporting [implements]: `--check` names which source governs (dotfile vs machine-local entry) and the entry's class
  * @ref LLP 0111#show [implements]: also the shared implementation behind `policy show`; `vocabulary` moves only the human lines, so `--json` stays byte-compatible with the `--check --json` field set
  * @param {{ targetDir: string, ctx: CommandRunContext, json: boolean, vocabulary?: PolicyHumanVocabulary }} args
  * @returns {Promise<number>}

src/core/commands/policy.js

@@ -251,7 +251,8 @@ export async function runPolicySet(argv, ctx) {
  * @ref LLP 0110 [implements]: the class-neutral `policy show`, the `hyp ignore --check` successor
  * @ref LLP 0111#show [implements]: `--json` stays byte-compatible with today's `--check --json` field set
  * @ref LLP 0111#tokens [implements]: a corrupt store still speaks the policy-store wording, never "the local-only list"
- * @ref LLP 0103#cli [constrained-by]: names the governing source (dotfile vs machine-local) and class; store/resolver unchanged
+ * @ref LLP 0103#reporting [constrained-by]: the report names which source governs (dotfile vs machine-local entry) and the class
+ * @ref LLP 0103#cli [constrained-by]: the store, resolver, and class lattice are unchanged; only the verb spelling is new
  * @param {string[]} argv
  * @param {CommandRunContext} ctx
  * @returns {Promise<number>}
@@ -288,7 +289,7 @@ export async function runPolicyShow(argv, ctx) {
  * @ref LLP 0110 [implements]: the class-neutral `policy unset`, replacing per-class `hyp unignore` flags as the primary spelling
  * @ref LLP 0111#unset [implements]: class-neutral by default, an optional trailing class token scopes it
  * @ref LLP 0111#tokens [implements]: a corrupt store still speaks the policy-store wording, never "the local-only list"
- * @ref LLP 0103#cli [constrained-by]: reuses the shared `isEqualOrDescendant` ancestor predicate; store/resolver unchanged
+ * @ref LLP 0103#cli [constrained-by]: the symmetric removal `hyp unignore` grew, now spelled class-neutrally; store, resolver, and class lattice unchanged
  * @param {string[]} argv
  * @param {CommandRunContext} ctx
  * @returns {Promise<number>}

src/core/usage-policy/local_only.js

@@ -25,7 +25,12 @@ export const LOCAL_ONLY_LIST_UNREADABLE_ERROR_KIND = 'local_only_list_unreadable
  * silently treated as "no exclusions", so callers (the export-seam resolver,
  * `hyp status`) are expected to let this propagate rather than swallow it.
  *
- * @ref LLP 0080#fail-safe [implements]: a corrupt list fails loudly, naming the file, rather than resolving to empty
+ * The throw-rather-than-empty mechanics were first worked out in LLP 0080
+ * §fail-safe; that document is superseded (LLP 0102 retires its in-login
+ * picker) but its machine-local list substrate lives on, and the invariant the
+ * mechanics rest on is LLP 0049's, cited below.
+ *
+ * @ref LLP 0049#fail-safe [constrained-by]: an uninterpretable privacy signal resolves to "suppress more", never to "no exclusions"
  */
 export class LocalOnlyListUnreadableError extends Error {
   /**

src/core/usage-policy/matcher.js

@@ -210,9 +210,11 @@ export function createUsagePolicyResolver({
    * version-1 `dirs` array on read as all-`local-only` entries. Missing =>
    * `[]` (the common case); present-but-unreadable/malformed => throws
    * {@link LocalOnlyListUnreadableError}, mirroring `readLocalOnlyEntries`'s
-   * async fail-safe so both paths name the same `error_kind`.
+   * async fail-safe so both paths name the same `error_kind`. Throwing rather
+   * than yielding an empty list is LLP 0080 §fail-safe's mechanic; what makes
+   * it mandatory is the invariant cited below.
    *
-   * @ref LLP 0080#fail-safe [implements]: a corrupt list fails the resolve loudly, never silently to "no exclusions"
+   * @ref LLP 0049#fail-safe [constrained-by]: an uninterpretable privacy signal must resolve to "suppress more", never silently to "no exclusions"
    * @ref LLP 0103 [implements]: migrate-on-read for the sync capture-hot-path reader
    * @returns {LocalOnlyEntry[]}
    */