@hegemonart/get-design-done 1.28.8 → 1.30.0

package/reference/capability-gap-stage-gate.md

@@ -0,0 +1,261 @@
+# Capability-Gap Stage-0 → Stage-1 Gate Specification
+
+> Phase 29 reference doc. Specifies the deterministic gate that decides when
+> the reflector has gathered enough `capability_gap` signal to surface a
+> one-time opt-in prompt for Stage-1 (incubator authoring of new agents /
+> skills). **No code path in this repository auto-flips the stage** —
+> D-01 is the discipline.
+
+---
+
+## 1. Overview
+
+Phase 29 ships in two stages:
+
+- **Stage 0** (Wave A, v1.29.0) emits `capability_gap` events from
+  `/gdd:fast` no-skill-match (Plan 29-01), `gdd-router` unmatched-intent
+  (Plan 29-01), and the reflector pattern-detection pass (Plan 29-02).
+- **Stage 1** (Wave B) layers incubator authoring of agents and skills on
+  top of the Stage-0 signal (Plans 29-04 / 29-05 / 29-06).
+
+The transition Stage 0 → Stage 1 is **gated on data**, not on a calendar
+date or a release. The reflector aggregates events into per-cycle
+clusters (`scripts/lib/reflector-capability-gap-aggregator.cjs`) and
+evaluates a deterministic stability function against the project's
+cycle history. When the gate is crossed, `/gdd:apply-reflections`
+emits a **one-time user-facing prompt** in the cycle markdown — never
+an auto-stage-flip. The user opting in is a separate explicit action,
+out of scope for this gate spec.
+
+Reference: **Phase 29 CONTEXT.md decision D-01** (two-stage approach;
+user opts in per a one-time prompt; if data is thin, Stage 1 never
+auto-enables).
+
+---
+
+## 2. Default thresholds
+
+The gate has three knobs, all set in `.design/config.json`
+under the `capability_gap_gate` key. Defaults:
+
+| Knob | Default | Meaning |
+|------|---------|---------|
+| `K` | `3` | Minimum number of **stable clusters** required to cross the gate. |
+| `M` | `10` | Minimum number of **consecutive cycles** a cluster must appear in to be considered for stability. |
+| `stddev_threshold` | `0.05` | Maximum allowed posterior `stddev(Beta(α, β))` for a cluster to be considered stable. |
+
+All three are overridable via `.design/config.json`:
+
+```jsonc
+{
+  "capability_gap_gate": {
+    "K": 3,
+    "M": 10,
+    "stddev_threshold": 0.05
+  }
+}
+```
+
+Reference: **Phase 29 CONTEXT.md decision D-03** (defaults are starting
+points; first-N-users data should refine).
+
+Validation: `K` must be a positive integer, `M` a positive integer,
+`stddev_threshold` a number in `(0, 1]`. The evaluator silently falls
+back to defaults if any value is invalid (T-29.03-02 mitigation in the
+plan's threat model).
+
+---
+
+## 3. Stability formula
+
+A cluster `c` is **stable** iff both conditions hold:
+
+1. **Consecutive presence.** `c` appears in `≥ M` consecutive cycles
+   somewhere within the observed history. (The most recent unbroken
+   run is what matters — if a cluster missed a cycle, the run resets
+   and only the longest streak counts.)
+2. **Narrow posterior.** The closed-form posterior standard deviation
+   of the Beta distribution satisfies:
+
+   ```
+   stddev(Beta(α, β)) = sqrt( (α · β) / ((α + β)² · (α + β + 1)) )
+   ```
+
+   with the Laplace prior (matches Phase 23.5's bandit-router posterior
+   store):
+
+   ```
+   α = appearances + 1
+   β = (cycles_observed − appearances) + 1
+   ```
+
+   where `appearances` is the total number of cycles in which `c` was
+   present (across the full history, not just the M-window) and
+   `cycles_observed = history.length`.
+
+**Worked example.** A cluster present in 25 of the 30 observed cycles
+with a longest consecutive run of 18 has `α = 26`, `β = 6`, so
+`stddev ≈ sqrt((26·6)/(32²·33)) ≈ sqrt(0.0154) ≈ 0.124`. That fails
+the default `stddev_threshold = 0.05`. To clear `0.05`, that same
+cluster would need closer to 30/30 presence or a longer history.
+
+**Cross-link.** The closed-form Beta-stddev is shared with Phase 23.5
+(see `scripts/lib/bandit-arbitrage.cjs` and the
+"Bandit-arbitrage analysis" section in `agents/design-reflector.md`).
+The same posterior is what gates frontmatter-tier corrections; here it
+gates stage transition.
+
+---
+
+## 4. Evaluation cadence
+
+Gate evaluation runs every time `/gdd:apply-reflections` is invoked.
+Inputs:
+
+1. The reflector pass collects all cycle markdown files in
+   `.design/reflections/` and parses the `## Capability gaps observed`
+   sections (emitted by `renderGapsSection` in
+   `scripts/lib/reflector-capability-gap-aggregator.cjs`).
+2. The per-cycle cluster lists are folded into a history array of
+   `{ cycle_slug, clusters }` entries.
+3. `evaluateStageGate(history, config)` is called once and returns:
+
+   ```ts
+   { crossed: boolean, stable_cluster_ids: string[], cycles_observed: number }
+   ```
+
+4. If `crossed === true` and the project has not previously opted in
+   (see § 6), the prompt in § 5 is emitted into the cycle markdown.
+
+The evaluation is **deterministic** (no randomness), **idempotent**
+(no side-effects in the evaluator), and **read-only** with respect to
+`.design/config.json` — that file is only updated by the user's
+explicit opt-in action, never by the reflector.
+
+---
+
+## 5. Gate-crossed prompt
+
+When the gate crosses for the first time, `/gdd:apply-reflections`
+appends the following verbatim block to the cycle markdown:
+
+> ```markdown
+> ## Stage-0 → Stage-1 gate crossed — opt-in required
+>
+> Capability-gap detection has accumulated enough signal across recent
+> cycles to consider enabling Stage-1 (incubator authoring of new
+> agents / skills). The gate is informational only — **nothing has
+> changed in the runtime**, and Stage-1 will NOT auto-enable. Per
+> Phase 29 CONTEXT.md decision D-01, the user opts in explicitly.
+>
+> - Stable clusters observed: **<N>** (≥K = <K>)
+> - Cycles observed: **<cycles_observed>** (≥M = <M>)
+> - Stable cluster IDs (truncated):
+>   - `<cluster_id_1>`
+>   - `<cluster_id_2>`
+>   - `<cluster_id_3>`
+>
+> If you want to enable Stage-1 incubator authoring (Plans 29-04 / 29-05),
+> opt in with the project-local command below. You can always opt out
+> later by deleting the timestamps from `.design/config.json` (§ 7).
+>
+> <!-- TODO: confirm opt-in command — likely
+>      `node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config set capability_gap_gate.opted_in_at "$(date -Iseconds)"`
+>      or a project-local equivalent. Plan 29-05 (apply-reflections
+>      extension) will land the canonical command. -->
+>
+> This prompt is emitted at most once per project. If you ignore it,
+> the gate continues to evaluate every cycle but does not re-prompt
+> (the `user_prompted_at` timestamp in `.design/config.json` suppresses
+> it). To re-trigger the prompt for a fresh round of evaluation, delete
+> `capability_gap_gate.user_prompted_at` from `.design/config.json`.
+> ```
+
+The wiring side of this — actually writing the `user_prompted_at`
+timestamp and routing the opt-in confirmation — is deferred to
+**Plan 29-05** (`/gdd:apply-reflections` extension). This document
+specifies the prompt text and behavior; 29-05 implements the
+state-machine that consumes it.
+
+---
+
+## 6. Opt-in semantics
+
+Two timestamps in `.design/config.json` track the project's gate state:
+
+```jsonc
+{
+  "capability_gap_gate": {
+    "K": 3,
+    "M": 10,
+    "stddev_threshold": 0.05,
+    "user_prompted_at": "2026-05-19T22:00:00.000Z",   // set when § 5 emitted
+    "opted_in_at": "2026-05-19T22:05:00.000Z"         // set when user opts in
+  }
+}
+```
+
+- **`user_prompted_at`** is set the first time the gate crosses and the
+  prompt block is rendered. The prompt is not re-emitted while this
+  timestamp is present.
+- **`opted_in_at`** is set when the user explicitly opts into Stage-1.
+  Stage-1 incubator authoring (Plans 29-04+) becomes active once this
+  timestamp is present. **Stage 1 is NEVER enabled by the reflector
+  setting this timestamp itself** — D-01 lock.
+
+Once `opted_in_at` is set, the gate stops emitting prompts entirely
+(it's a one-shot mechanism, not a continuous nudge).
+
+---
+
+## 7. Reset / override
+
+Operators can manually reset the gate by editing `.design/config.json`:
+
+| Effect desired | Action |
+|----------------|--------|
+| Re-prompt on next gate cross | Delete `capability_gap_gate.user_prompted_at`. |
+| Revert from Stage-1 to Stage-0 | Delete `capability_gap_gate.opted_in_at`. (Stage-1 artifacts in `.design/reflections/incubator/` are NOT removed by this; deletion is the user's call.) |
+| Tighten / loosen thresholds | Edit `K` / `M` / `stddev_threshold` directly. Out-of-range values silently fall back to defaults (§ 2). |
+
+Reset is **explicit** and **idempotent**. The reflector never writes
+to these fields on its own — the only writers are (a) the
+`/gdd:apply-reflections` opt-in path (Plan 29-05) and (b) the human
+operator editing the file by hand.
+
+---
+
+## 8. Test fixtures
+
+Executable examples that exercise the gate live in
+`tests/reflector-capability-gap-aggregation.test.cjs`:
+
+- **T3** — 30 cycles × 3 always-present clusters → gate crosses with
+  default K=3 / M=10 / stddev_threshold=0.05.
+- **T3b** — 10 cycles × 1 always-present cluster → gate does NOT
+  cross (posterior stddev ≈ 0.077 with α=11, β=1 is above the 0.05
+  threshold; M=10 is the lower bound on observations, not a
+  sufficient condition for stability).
+- **T4** — 30 cycles, 2 always-present clusters + 1 "noisy" cluster
+  present in only the first 4 cycles → gate does NOT cross
+  (`stable_cluster_ids.length === 2 < K=3`).
+- **T4b** — 5 cycles total → gate does NOT cross (`cycles_observed < M`).
+- **T7** — Confirms `K` and `stddev_threshold` overrides flow through
+  `normalizeConfig` and reach the evaluation.
+
+These fixtures are synthetic and inline (D-11). The gate evaluator
+never reads `.design/gep/events.jsonl` directly in CI — fixtures
+seed the cluster lists by hand.
+
+---
+
+## Decisions referenced
+
+- **D-01** — Two-stage approach: Stage 0 telemetry-only ships first;
+  Stage 1 authoring gated on data; user opts in per a one-time prompt;
+  no auto-flip.
+- **D-03** — Default `K=3` / `M=10` / `stddev_threshold=0.05`,
+  overridable via `.design/config.json`.
+- **D-11** — Tests use synthetic fixtures (no live event chain reads).
+- **Phase 23.5** — Posterior `stddev(Beta(α, β))` closed form and
+  Laplace prior convention reused here.

package/reference/known-failure-modes.md

@@ -0,0 +1,185 @@
+# Known Failure Modes (Phase 30 Triage Gate)
+
+This file is the **catalogue of locally-fixable failure modes** that the
+Phase 30 issue-reporter consults *before* prompting the user to file a
+GitHub issue. The triage gate runs first (D-07): when an entry matches
+the user's error, the gate surfaces `this looks like X — try Y` and
+exits the report flow without prompting. `--force-report` bypasses the
+gate but still requires consent (D-11).
+
+## Schema
+
+Each entry is a single fenced ```yaml block with this flat key:value shape:
+
+- `id` — stable identifier (kebab-case or `KFM-NNN` numeric). Required.
+- `pattern` — JavaScript regex string. Matched against
+  `[error.message, error.stack].filter(Boolean).join("\n")`. Required.
+- `diagnosis` — one-sentence plain-English root cause. Required.
+- `remedy` — one-sentence user-runnable action. Required.
+- `severity` — advisory only, one of `low` / `medium` / `high`. Required.
+- `propose_report` — boolean. If `true`, this mode is on the D-11
+  whitelist: 30-04 may *propose* `--report` at error time for this
+  class. Defaults to `false`. Advisory; the matcher does not act on it.
+
+## Matching policy
+
+- **First match wins.** Entries are evaluated in file order. The matcher
+  returns the first entry whose regex tests true against the haystack.
+  No severity ranking, no aggregation, no blending.
+- **Invalid regex is non-fatal.** An entry whose `pattern` fails to
+  compile is skipped with a `console.warn`, never crashes the matcher.
+- **Missing catalogue is non-fatal.** If this file is absent or
+  unparseable, `matchKnownFailure` returns `{ matched: false }` and
+  warns once.
+
+Consumed by `scripts/lib/issue-reporter/triage-matcher.cjs`
+(`matchKnownFailure(errorContext)`). Wired into `skills/report-issue`
+(Plan 30-04) before the consent prompt.
+
+## Entries
+
+### KFM-001 — EACCES on `.design/` write
+
+Permission failure when the plugin writes into `.design/`. Common after
+`sudo`-cloning a repo or running CI as a user without write access to
+the project root.
+
+```yaml
+id: KFM-001
+pattern: 'EACCES.*\.design'
+diagnosis: 'Permission denied writing to .design/ — the plugin cannot persist its work-product directory.'
+remedy: 'Run `chown -R "$USER" .design` (or recreate the directory as your normal user) and retry the command.'
+severity: medium
+propose_report: false
+```
+
+### KFM-002 — `gh` CLI not on PATH
+
+The Phase 30 outbound submission path requires the user's `gh` CLI
+(D-05). If it's missing, Plan 30-06 falls back to clipboard + URL.
+This entry catches the typical shell-spawn error.
+
+```yaml
+id: KFM-002
+pattern: '(gh: command not found|spawn gh ENOENT|''gh'' is not recognized)'
+diagnosis: 'GitHub CLI (`gh`) is not installed or not on PATH; the issue reporter''s outbound path relies on it.'
+remedy: 'Install gh from https://cli.github.com and run `gh auth login`, then retry. (Or use the clipboard fallback: the payload is already on disk under .design/issue-drafts/.)'
+severity: low
+propose_report: false
+```
+
+### KFM-003 — Node.js version mismatch
+
+`package.json` declares `engines.node: ">=22"`. Older Node versions
+crash on the `--experimental-strip-types` test runner, or fail subtle
+TypeScript-import behaviour.
+
+```yaml
+id: KFM-003
+pattern: '(engine "node" is incompatible|Unsupported engine|SyntaxError.*Unexpected token.*satisfies|--experimental-strip-types)'
+diagnosis: 'Active Node.js version is below the plugin''s required >=22; modern syntax features and the strip-types test runner are unavailable.'
+remedy: 'Upgrade Node to >=22 (e.g. `nvm install 22 && nvm use 22`) and rerun.'
+severity: high
+propose_report: false
+```
+
+### KFM-004 — Figma token missing
+
+Figma-aware flows expect `FIGMA_TOKEN` (or the documented env-var alias)
+to be present. The 401/missing-env error class is recognisable.
+
+```yaml
+id: KFM-004
+pattern: '(FIGMA_TOKEN.*(not set|missing|undefined)|Figma.*401|figma.*unauthor)'
+diagnosis: 'FIGMA_TOKEN environment variable is missing or invalid; Figma-dependent commands cannot authenticate.'
+remedy: 'Generate a personal access token at https://www.figma.com/developers/api#access-tokens and `export FIGMA_TOKEN=<token>` in your shell profile.'
+severity: medium
+propose_report: false
+```
+
+### KFM-005 — Git working tree dirty
+
+Several phase-tooling commands assume a clean working tree (clean
+checkpoints between cycles). A dirty tree surfaces as a stderr line
+the matcher can recognise.
+
+```yaml
+id: KFM-005
+pattern: '(working tree (is )?(not clean|dirty)|uncommitted changes|Changes not staged for commit)'
+diagnosis: 'Git working tree has uncommitted changes; the command requires a clean checkpoint before proceeding.'
+remedy: 'Commit, stash (`git stash -u`), or discard your local changes, then rerun the command.'
+severity: low
+propose_report: false
+```
+
+### KFM-006 — `.planning/` directory missing
+
+GSD/GDD project commands assume `.planning/` has been initialised by
+`/gsd:new-project`. A bare ENOENT on that path is a clear self-fix.
+
+```yaml
+id: KFM-006
+pattern: 'ENOENT.*\.planning'
+diagnosis: '.planning/ directory does not exist; the project has not been initialised yet.'
+remedy: 'Run `/gsd:new-project` to bootstrap the planning structure, then retry.'
+severity: medium
+propose_report: false
+```
+
+### KFM-007 — `reference/registry.json` invalid JSON
+
+The Phase 14.5 registry is hand-edited; a stray trailing comma or
+unquoted key surfaces here. Self-fixable, not a maintainer issue.
+
+```yaml
+id: KFM-007
+pattern: '(reference/registry\.json.*(SyntaxError|JSON|Unexpected token)|Unexpected token.*registry\.json)'
+diagnosis: 'reference/registry.json failed to parse as JSON — likely a trailing comma or unbalanced brace from a recent edit.'
+remedy: 'Open reference/registry.json in your editor; the JSON parser error message will pinpoint the line. Fix the syntax and retry.'
+severity: medium
+propose_report: false
+```
+
+### KFM-008 — MCP server unreachable
+
+When the Figma / GDD MCP servers are not running, commands depending
+on them fail with a clear connection-refused class of error.
+
+```yaml
+id: KFM-008
+pattern: '(MCP.*(unreachable|ECONNREFUSED|not connected)|mcp.*server.*not.*running|connection refused.*ws://)'
+diagnosis: 'An MCP server (Figma, GDD-state, or GDD-tools) is not reachable; the plugin cannot route tool calls through it.'
+remedy: 'Start the relevant MCP server (see scripts/mcp-servers/) and confirm `claude mcp list` shows it as connected.'
+severity: medium
+propose_report: true
+```
+
+### KFM-009 — Plugin file accidentally deleted
+
+A user-side `git clean -fdx` or aggressive editor refactor can remove
+plugin files. This is a re-install path, not a bug report path — but
+it's on the whitelist because users typically can't tell it apart from
+an upstream regression.
+
+```yaml
+id: KFM-009
+pattern: 'Cannot find module.*(scripts/lib/|skills/.*SKILL\.md|reference/.*\.md)'
+diagnosis: 'A plugin file is missing — most often the result of a local `git clean` or a partial install.'
+remedy: 'Reinstall the plugin: `npm install -g @hegemonart/get-design-done` (or pull the repo fresh in dev). If the file should exist, the error message gives its path.'
+severity: medium
+propose_report: true
+```
+
+### KFM-010 — Disk full / ENOSPC
+
+Out-of-space failures masquerade as obscure write errors. Self-fixable
+by freeing space; not a maintainer report path.
+
+```yaml
+id: KFM-010
+pattern: '(ENOSPC|no space left on device|disk full)'
+diagnosis: 'Disk is full — no space left on the device the plugin is writing to.'
+remedy: 'Free space (e.g. clear `.design/cache/`, prune old worktrees, empty trash) and retry.'
+severity: high
+propose_report: false
+```

package/reference/pseudonymization-rules.md

@@ -0,0 +1,189 @@
+---
+title: Pseudonymization Rules
+phase: 30
+type: meta-rules
+status: stable
+created: 2026-05-20
+---
+
+# Pseudonymization Rules
+
+The 8 substitution rules applied by `scripts/lib/pseudonymize.cjs` to identity-correlatable content in Phase 30 issue payloads.
+
+## Pseudonymization, not anonymization
+
+These rules **reduce** identity correlation. They do not **eliminate** it. A determined adversary with side-channel data — writing style, code-style patterns, repository fingerprints, timing — may still re-identify a reporter. Phase 30 explicitly delivers pseudonymization-not-anonymization (CONTEXT D-01); over-promising would be misleading.
+
+Pseudonymization here serves three concrete goals:
+
+- **(a) Prevent casual identification** by other users who later read the public GitHub issue.
+- **(b) Reduce corporate-DLP false-positives** at submission time on common identifier shapes (usernames in paths, hostnames in stack traces, email patterns in logs). The pseudonymized payload is less likely to be intercepted by enterprise DLP tools that scan for these exact patterns.
+- **(c) Give the user a structural opportunity** to inspect and edit the payload before it leaves their machine. The pseudonymization step makes the payload's identity-correlation surface visible — the user can read it and decide.
+
+Submission is always user-initiated and user-reviewed per Plan 30-04 (CONTEXT D-03). Phase 30 does **not** auto-submit, ever.
+
+## Pipeline placement
+
+Pseudonymization runs **after** redaction (`scripts/lib/redact.cjs`, Phase 22) in the Plan 30-02 payload assembly. The two are orthogonal:
+
+| Layer | Module | What it scrubs |
+|---|---|---|
+| Secrets (high-stakes floor) | `scripts/lib/redact.cjs` | Tokens, API keys, JWTs, PEM blocks, AWS credentials, Slack/Stripe/GitHub tokens — strings that must **never** escape |
+| Identity (privacy) | `scripts/lib/pseudonymize.cjs` | Names, paths, hostnames, repo origins, env-var values, emails, IPs — strings that **may** be published but should not personally identify the reporter |
+
+Redaction handles "this string must never escape"; pseudonymization handles "this string is fine to publish but should not personally identify the reporter." The two modules do not import each other; composition lives at the caller (Plan 30-02 payload assembly). See CONTEXT D-01 for the framing rationale and CONTEXT references for the redaction prerequisite.
+
+## The rules
+
+Eight rules. Each rule has a stable id (R1..R8) used by `/gdd:update --show-privacy-diff` (Plan 30-07) to enumerate active rules.
+
+### R1 — git-identity
+
+**Replaces:** `user.name` and `user.email` from git config when they appear in payload strings (stack traces, log messages, commit-author lines).
+
+**Why:** The user's git identity is the most direct re-identification vector inside a payload. Substring matching is used for the name with a word-boundary guard (`\b`) so unrelated words containing the name as a substring (e.g., `alicewonderland` when the name is `alice`) are preserved. Email matching is case-insensitive.
+
+**Before/after example:**
+```
+Author: alice <alice@example.com> committed at 12:34
+Author: <user> <<user>@<domain>> committed at 12:34
+```
+
+**Coverage notes:** Word-boundary regex (`\b<name>\b`) prevents stripping unrelated substrings. Email match is case-insensitive (`alice@example.com` and `Alice@Example.Com` both replaced). Name values shorter than 2 chars and email values shorter than 3 chars are skipped to avoid over-eager matching on common short sequences.
+
+### R2 — absolute-paths
+
+**Replaces:** Home-directory absolute paths across all three OS conventions:
+
+- Linux: `/home/<user>/...`
+- macOS: `/Users/<user>/...`
+- Windows: `C:\Users\<user>\...` (any drive letter)
+
+**Why:** Issue payloads frequently include stack traces with absolute file paths. The path shape alone reveals the user's OS, and the username segment exposes identity. Critically: issue payloads from one OS may be processed on a maintainer's different OS, so the module handles all three shapes regardless of which OS the report was generated on.
+
+**Before/after example:**
+```
+/home/alice/code/proj/file.ts:42  →  <home>/code/proj/file.ts:42
+/Users/alice/code/proj/file.ts:42  →  <home>/code/proj/file.ts:42
+C:\Users\alice\code\proj\file.ts:42  →  <home>\code\proj\file.ts:42
+```
+
+**Coverage notes:** Six regex sweeps — three identity-aware (when the name is known) and three generic (matching `/Users/<any>/`, `/home/<any>/`, `<drive>:\Users\<any>\`). Identity-aware sweeps run first so the identity-aware substitution takes precedence; generic sweeps catch references to teammates or other users that may appear in stack traces.
+
+### R3 — hostname
+
+**Replaces:** `os.hostname()` value with `<host>`.
+
+**Why:** The machine hostname often encodes the user's name or organization (e.g., `alices-macbook.local`, `acme-corp-laptop-42`). Word-boundary substitution plus a special-case sweep for `@hostname` shapes inside ssh-like strings (where the standard `\b` lookaround does not fire as expected on `@`).
+
+**Before/after example:**
+```
+Connected to alices-macbook.local from alices-macbook
+Connected to <host>.local from <host>
+```
+
+**Coverage notes:** Two sweeps — one for `@hostname` (ssh-shape), one with standard word-boundary. Hostnames shorter than 2 chars are skipped.
+
+### R4 — repo-origin
+
+**Replaces:** Git origin URL with `<category>-hash:<sha8>` where:
+
+- `<category>` is `public-personal-hash` when the caller's `opts.repoVisibility === 'public-personal'`
+- `<category>` is `private-org-hash` for all other inputs (conservative default)
+- `<sha8>` is `sha256(normalized_origin_url)[:8]` where normalization strips protocol prefixes (`git@github.com:`, `https://github.com/`, `ssh://`, `git://`) and trailing `.git`, then lowercases
+
+**Why:** The repo URL identifies both the user and the organization. The hash gives maintainers a deterministic dedup key (same repo → same hash) without exposing the URL. The category prefix tells maintainers whether the reporter's repo is a personal public project or something more sensitive.
+
+**Before/after example:**
+```
+Remote: git@github.com:acme-corp/internal-tools.git
+Remote: private-org-hash:a1b2c3d4
+```
+
+**Coverage notes:** Caller resolves visibility via `gh repo view --json visibility` (or skips if `gh` is absent — module then uses the conservative `private-org-hash` default). The module performs no network calls; visibility is an injected `opts.repoVisibility` value. Owner-is-user vs owner-is-org distinction is the caller's responsibility (the module cannot tell from a URL alone). Both the raw `repoOrigin` substring and the normalized form are substituted so multiple shapes of the same URL in a stack trace all collapse to one placeholder.
+
+### R5 — env-vars
+
+**Replaces:** **VALUES** (not key names) of these environment variables wherever they appear in payload strings:
+
+- `USER`, `LOGNAME`, `HOSTNAME` (POSIX identity)
+- Any key ending in `_TOKEN`, `_KEY`, `_SECRET` (defense-in-depth alongside Phase 22 redaction)
+
+**Why:** Phase 22's `redact.cjs` catches specific token shapes (`sk-ant-...`, `ghp_...`). R5 catches the residual case where an env-var value appears in a payload because the user interpolated it into a log message (e.g., `console.log('TOKEN=' + process.env.MY_KEY)`). The defense-in-depth catches custom org-specific keys that don't match the Phase 22 token-shape regex catalogue.
+
+**Before/after example:**
+```
+Error: GITHUB_TOKEN=ghp_abcDEFghi123 was rejected
+(with process.env.GITHUB_TOKEN === 'ghp_abcDEFghi123')
+
+Error: GITHUB_TOKEN=<env:GITHUB_TOKEN> was rejected
+```
+
+**Coverage notes:** Empty / 1-char / 2-char values are skipped (corruption guard — short values would over-match unrelated content). Longer-value entries are processed first (descending by length) so a token that contains another's substring does not get half-replaced. R5 walks the entire payload tree (strings get value substitution, objects/arrays recurse, cycles detected via WeakSet) — value substitution works regardless of nesting depth.
+
+### R6 — email-in-logs
+
+**Replaces:** Email addresses that slipped past R1's identity-aware substitution (e.g., third-party emails mentioned in a stack trace or log line) with `<email>`.
+
+**Why:** R1 catches the user's own `user.email`. R6 is the generic catch-all for any other email addresses that may appear in a payload — including teammates' emails in error messages, vendor support emails in stack traces, or addresses pulled from data being processed at the time of the error.
+
+**Before/after example:**
+```
+Stack frame: at notify(maintainer@example.org)
+Stack frame: at notify(<email>)
+```
+
+**Coverage notes:** Standard RFC-5322-ish regex (`/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g`). R6 runs **after** R1 in the rule pipeline so identity-aware substitution takes precedence (the user's email becomes `<user>@<domain>`, not `<email>`).
+
+### R7 — ip-addresses
+
+**Replaces:** IPv4 and IPv6 addresses, retaining only network class:
+
+- IPv4 `a.b.c.d` → `<ipv4:a.b.c.0>` (zero out the last octet)
+- IPv6 → `<ipv6:<prefix>::>` (drop the last segment)
+
+**Why:** IP addresses reveal network topology and may identify the user's location, employer, or VPN egress. Retaining the network class (first three IPv4 octets, IPv6 prefix) preserves enough information for maintainer-side triage ("the error occurred over a corporate network") while dropping the specific host identifier.
+
+**Before/after example:**
+```
+Failed to reach 203.0.113.42  →  Failed to reach <ipv4:203.0.113.0>
+fe80::1ff:fe23:4567:890a       →  <ipv6:fe80::1ff:fe23:4567::>
+```
+
+**Coverage notes:** Regex guards prevent false-positives on:
+
+- Semver strings (`v1.2.3.4`) — leading `v` blocked by lookbehind
+- Email-adjacent strings (`@1.2.3.4`) — `@` blocked by lookbehind
+- Date strings (`2026-05-20`) — dashes don't match the dotted-octet pattern
+- Longer dotted strings (`1.2.3.4.5`) — trailing `.` blocked by lookahead
+
+IPv6 regex requires at least 5 segments to avoid false-positives on time strings (`12:34`, `12:34:56`).
+
+### R8 — stable-pseudonym
+
+**Replaces:** Nothing in payload text — R8 is a **separate utility export** (`stablePseudonym(userId, repoOrigin)`) the caller invokes when constructing payload metadata.
+
+**Why:** Maintainers want to group reports from the same user-and-repo without ever seeing identity. A deterministic 8-char hex pseudonym = `sha256(userId + ':' + normalized_repo_origin)[:8]` gives them that grouping key. Same user + same repo always hashes to the same 8 chars; different inputs produce different outputs. The URL normalization (strip protocol prefix, strip `.git`, lowercase) makes the hash stable across `git@github.com:foo/bar.git` and `https://github.com/foo/bar` shapes of the same origin.
+
+**Before/after example:**
+```
+userId: 'alice'
+repoOrigin: 'git@github.com:foo/bar.git'
+
+pseudonym: 'a1b2c3d4'
+```
+
+**Coverage notes:** Defensive sentinel — if either input is falsy, returns `'00000000'` so call sites never crash on missing inputs. Caller may check for the sentinel if it matters. The `:` separator between userId and repoOrigin prevents collisions between `userId='a' + repoOrigin='bcd'` and `userId='abc' + repoOrigin='d'`.
+
+## Consumed by
+
+- **`scripts/lib/pseudonymize.cjs`** — implements R1..R8. The module's `RULES` manifest constant has a 1:1 correspondence with the sections above (R1..R8 ids match `RULES[i].id`).
+- **Plan 30-02 (payload assembly)** — composes Phase 22 redaction + Phase 30 pseudonymization.
+- **Plan 30-04 (consent prompt)** — uses the `replacements` log returned by `pseudonymize()` to display "X replacements made (R1: 3, R2: 5, ...)" summary before the user submits.
+- **Plan 30-07 (`/gdd:update --show-privacy-diff`)** — diffs this document plus `pseudonymize.cjs` between installed and target versions of the plugin. Always-show on first run after upgrade that touched these files; opt-in afterward (CONTEXT D-09).
+
+## See also
+
+- `scripts/lib/redact.cjs` (Phase 22) — secrets-stripping prerequisite layer in the payload pipeline.
+- `.planning/phases/30-issue-reporter/CONTEXT.md` — D-01 pseudonymization-not-anonymization framing; D-13 synthetic-fixtures-plus-tmpdir test contract.
+- `reference/registry.json` — registry entry for this document (`name: 'pseudonymization-rules'`, `phase: 30`, `type: 'meta-rules'`).

package/reference/registry.json

@@ -1,7 +1,7 @@
 {
   "$schema": "./schemas/registry.schema.json",
   "version": 1,
-  "generated_at": "2026-05-18T12:47:59.666Z",
+  "generated_at": "2026-05-20T09:53:00.000Z",
   "entries": [
     {
       "name": "codex-tools",
@@ -52,6 +52,13 @@
       "phase": 27,
       "description": "Phase 27 ACP + ASP protocol cheat sheet for peer-CLI delegation — line-delimited JSON-RPC framing, initialize/prompt/threadStart/turn lifecycle, per-peer ACP entry points, error-path resolution semantics"
     },
+    {
+      "name": "pseudonymization-rules",
+      "path": "reference/pseudonymization-rules.md",
+      "type": "meta-rules",
+      "phase": 30,
+      "description": "Phase 30 pseudonymization rule catalog (R1..R8) — replaces git identity, paths, hostname, repo origin, env-var values, email, IPs; defines stable per-user pseudonym derivation. Consumed by /gdd:update --show-privacy-diff at 30-07."
+    },
     {
       "name": "DEPRECATIONS",
       "path": "reference/DEPRECATIONS.md",
@@ -839,6 +846,20 @@
       "type": "meta-rules",
       "phase": 28.5,
       "description": "Phase 28.5 skill-authoring contract — adapted from mattpocock/skills (MIT). SKILL.md <=100-line cap (warn >=100, block >=250 in CI), 1024-char description cap, <what>. Use when <triggers>. form (lax-mode default per Phase 33 A/B pending), frontmatter required fields, progressive-disclosure one-level-deep rule. Validator at scripts/validate-skill-length.cjs."
+    },
+    {
+      "name": "capability-gap-stage-gate",
+      "path": "reference/capability-gap-stage-gate.md",
+      "type": "meta-rules",
+      "phase": 29,
+      "description": "Phase 29 Stage-0 → Stage-1 capability-gap gate specification. Defaults K=3 stable clusters across M=10 cycles with closed-form posterior stddev(Beta(α,β)) < 0.05 (Laplace prior matches Phase 23.5). D-01 lock: gate emits a one-time user-facing prompt on crossing — NEVER an auto-stage-flip. Overridable via .design/config.json capability_gap_gate.{K,M,stddev_threshold}. Test fixtures at tests/reflector-capability-gap-aggregation.test.cjs."
+    },
+    {
+      "name": "known-failure-modes",
+      "path": "reference/known-failure-modes.md",
+      "type": "meta-rules",
+      "phase": 30,
+      "description": "Phase 30 triage gate catalogue — locally-fixable failure modes (id/pattern/diagnosis/remedy/severity, with optional propose_report whitelist flag per D-11) consulted by scripts/lib/issue-reporter/triage-matcher.cjs before the report-issue consent prompt (D-07/D-11)."
     }
   ]
 }