@hegemonart/get-design-done 1.28.7 → 1.30.0

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)."
     }
   ]
 }

package/reference/schemas/events.schema.json

@@ -10,7 +10,7 @@
     "type": {
       "type": "string",
       "minLength": 1,
-      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error."
+      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap."
     },
     "timestamp": {
       "type": "string",
@@ -34,7 +34,7 @@
     },
     "payload": {
       "type": "object",
-      "description": "Event-type-specific payload. Opaque at the envelope level."
+      "description": "Event-type-specific payload. Opaque at the envelope level. When type === 'capability_gap', the payload is narrowed by the conditional schema in allOf[0] to the 7-field CapabilityGapPayload (Phase 29 D-02)."
     },
     "_meta": {
       "type": "object",
@@ -51,5 +51,99 @@
       "type": "boolean",
       "description": "Writer-set flag indicating the payload exceeded maxLineBytes and has been replaced by a placeholder."
     }
-  }
+  },
+  "definitions": {
+    "TrajectoryRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["trajectory_path", "byte_start", "byte_end", "content_hash"],
+      "properties": {
+        "trajectory_path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Repo-relative or absolute path to the trajectory-JSONL file containing the referenced evidence slice."
+        },
+        "byte_start": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Inclusive byte offset into the trajectory file marking the start of the evidence slice."
+        },
+        "byte_end": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Exclusive byte offset into the trajectory file marking the end of the evidence slice."
+        },
+        "content_hash": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$",
+          "description": "Hash-pinned content fingerprint (Phase 29 D-07). Detects retroactive chain mutation."
+        }
+      },
+      "description": "Pointer to a slice of a trajectory-JSONL file (Phase 29 D-07). Hash-pinned so consumers can detect chain mutation. Used inside CapabilityGapPayload.evidence_refs to keep payloads small while preserving audit-traceability — pointers, NOT duplicated trajectory content."
+    },
+    "CapabilityGapPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "event_id",
+        "parent_event_id",
+        "source",
+        "context_hash",
+        "intent_summary",
+        "suggested_kind",
+        "evidence_refs"
+      ],
+      "properties": {
+        "event_id": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+          "description": "UUIDv4 identifying this capability_gap event. Stable across emit + read cycles."
+        },
+        "parent_event_id": {
+          "type": ["string", "null"],
+          "description": "UUIDv4 of the parent chain event when the gap was surfaced inside a larger trajectory; null when this is a root emit (e.g. /gdd:fast bail-out)."
+        },
+        "source": {
+          "type": "string",
+          "enum": ["fast", "router", "reflector_pattern"],
+          "description": "Which surface detected the gap. fast = /gdd:fast no-skill-match path; router = gdd-router unmatched-intent path; reflector_pattern = reflector pattern-detection pass (Plan 29-02)."
+        },
+        "context_hash": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable hash of the intent/context that surfaced the gap. Used by 29-03 aggregation to cluster recurring gaps with the same hash."
+        },
+        "intent_summary": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "Short human-readable description of the failed lookup. Capped at 256 chars per D-02 — keeps payload small + auditable."
+        },
+        "suggested_kind": {
+          "type": "string",
+          "enum": ["agent", "skill"],
+          "description": "Drafter hint for 29-04 incubator-author. fast emits 'skill' (narrow primitive); router emits 'agent' (multi-step workflow); reflector_pattern may emit either."
+        },
+        "evidence_refs": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/TrajectoryRef" },
+          "description": "Pointers to trajectory-JSONL slices that evidence the gap (D-07). Hash-pinned to detect chain mutation. Empty array allowed for low-evidence emits (e.g. /gdd:fast which has no trajectory)."
+        }
+      },
+      "description": "Phase 29 D-02 capability_gap payload — exactly 7 fields, additionalProperties: false. Validated when the envelope's type === 'capability_gap' via the allOf[0] conditional."
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "type": { "const": "capability_gap" } },
+        "required": ["type"]
+      },
+      "then": {
+        "properties": {
+          "payload": { "$ref": "#/definitions/CapabilityGapPayload" }
+        }
+      }
+    }
+  ]
 }