feat: integrate the Finding Your Unknowns corpus — reference doc, conventions, and contract deltas across 8 plugins

docs/GLOSSARY.md

@@ -72,6 +72,21 @@ The healthiest of `context-guard`'s three context zones (`smart` / `acceptable`
 the band rather than any token figure — the band numbers are declared judgment defaults and tunable
 per consumer.
 
+**unknowns quadrants**
+
+The four-way pre-prompt breakdown — known knowns, known unknowns, unknown knowns, unknown
+unknowns — used to decide which unknown-finding pass a task needs. Owned by
+[`FINDING-YOUR-UNKNOWNS.md`](FINDING-YOUR-UNKNOWNS.md); entries cite it rather than restating the
+quadrants.
+
+**blindspot finding types**
+
+The typed taxonomy a blindspot pass reports its findings in: Landmine (breaks something
+non-obvious), History (a constraint the code no longer shows), Convention (an unwritten team
+rule), Missing concept (a domain idea the prompt never named). The output contract lives in
+`discovery:blindspot`; the taxonomy's rationale in
+[`FINDING-YOUR-UNKNOWNS.md`](FINDING-YOUR-UNKNOWNS.md).
+
 ## Rejected terms
 
 Names considered for a concept this project already owns, recorded so they are not reintroduced.
@@ -86,11 +101,17 @@ Each maps to the term or doctrine that owns the concept.
 | cache *(the doc-restating-environment sense)* | `docs-hygiene:audit-derivability`'s derivable-from-environment doctrine; the word is overloaded here (plugin cache, prompt cache) |
 | sediment | the `docs-hygiene` audit family's pruning doctrine; collides with the code-sense use in `playbooks:fable-5` |
 | sycophancy | nothing — a generic LLM-behavior term with no distinct project meaning. Free-prose use is unaffected; it is simply not project vocabulary |
+| map / territory | the source author's metaphor, cited where it appears in [`FINDING-YOUR-UNKNOWNS.md`](FINDING-YOUR-UNKNOWNS.md) "The unknowns taxonomy"; never house vocabulary (metaphor-jargon risk) |
 
 ## Provenance
 
-Every term above was graded and adopted in lane 6 of the AI Hero course vetting
+Terms through "smart zone" were graded and adopted in lane 6 of the AI Hero course vetting
 (2026-08-18). The decision rows, including the basis for each verdict and the rejected-term
 mappings, are in [`upstream/aihero-course.md`](upstream/aihero-course.md) under "Term adoption".
 Materialization of this file was tracked as
 [#3000](https://github.com/melodic-software/claude-code-plugins/issues/3000).
+
+"unknowns quadrants", "blindspot finding types", and the map/territory rejected-terms row were
+adopted at the finding-your-unknowns integration sign-off (2026-09-01); the decision record is
+[ADR 0025](adr/0025-adopt-the-unknowns-corpus-as-judgment-preserving-contract-deltas.md) and the
+shipping PR carries the full decision sheet.

docs/PLUGIN-PHILOSOPHY.md

@@ -637,6 +637,8 @@ doc before a second plugin adopts it. Fleet audits check conformance per row.
 | Always-on hook cost ceiling | [`docs/conventions/hook-budget/`](conventions/hook-budget/README.md) |
 | Tracker reference form inside a code comment | [`docs/conventions/tracker-reference-form/`](conventions/tracker-reference-form/README.md) |
 | Untrusted-content framing contract | [`docs/conventions/untrusted-content/`](conventions/untrusted-content/README.md) |
+| Reply affordance on decision-collecting artifacts | [`docs/FINDING-YOUR-UNKNOWNS.md`](FINDING-YOUR-UNKNOWNS.md#reply-affordance-convention) |
+| Export button on interactive HTML artifacts | [`docs/FINDING-YOUR-UNKNOWNS.md`](FINDING-YOUR-UNKNOWNS.md#export-button-rule) |
 
 ## Cross-platform contract
 

docs/adr/0025-adopt-the-unknowns-corpus-as-judgment-preserving-contract-deltas.md

@@ -0,0 +1,60 @@
+# Adopt the "Finding Your Unknowns" corpus as judgment-preserving contract deltas
+
+- Status: accepted
+- Date: 2026-09-01
+
+## Context
+
+A practitioner corpus on artifact-first development — Thariq Shihipar's "A field guide to
+Claude Fable 5: Finding your unknowns" (Anthropic blog, 2026-07-06), its X-article
+methodology substrate "The Unreasonable Effectiveness of HTML", and a 20-demo example
+collection — was ingested as 17 verified digest slices (byte-exact quoting, dual
+verification) and worked through a full decision chain: a relentless interview, a
+read-only evidence pass grading every named-skill collision, dual fresh-context
+validators, external research grounding seven practice areas in primary sources,
+blindspot/brainstorm/devils-advocate passes, and a signed single-sheet decision surface.
+The working material lived in the branch's contract slice and prunes with it per the
+topic-docs convention; the shipping PR (#3592) carries the full plan and verification
+record, and the corpus itself is the primary source a future auditor reads.
+
+The corpus's own author warns against exactly the move a plugin marketplace is tempted to
+make — turning the material into generator skills — and the marketplace's instruction
+economy separately requires observed, repeated stumble evidence before any standing
+instruction lands. Genuine alternatives existed: adopt the techniques as new skills,
+adopt them as standing instructions, or reject codification entirely.
+
+## Decision
+
+Absorb the corpus behind a per-row evidence-gate classification, with the author's
+anti-premature-codification warning treated as a binding constraint:
+
+- CONTRACT / POLICY / CONVENTION rows land now as team conventions adopted at the
+  sign-off, as additive lines in the owning skills' bodies with same-commit eval
+  expectations, never as generator skills.
+- BEHAVIORAL rows never land as standing instructions: they ship as doc lines in
+  `docs/FINDING-YOUR-UNKNOWNS.md` plus tracked eval candidates (#3589), awaiting
+  observed-stumble evidence.
+- `docs/FINDING-YOUR-UNKNOWNS.md` is the graduated reference and the owner doc for the
+  reply-affordance and export-button conventions (registry rows point at it,
+  owner-doc-first); it quotes the warning byte-faithfully under a stated fair-quotation
+  basis.
+- Quiz-as-merge-gate reroutes to `verification:confirm`'s existing gate (one mechanism
+  per concern); the external-reference port gate is scoped to sources of truth outside
+  the repo's tree via the corrector method's declared-step-delta seam; the deviation log
+  ships opt-in with a recorded registry trigger (a second plugin reading `DEVIATIONS.md`
+  graduates it to an owner doc).
+- The corpus's context-engineering companion routes to the incumbent effort recorded in
+  [ADR 0004](0004-rightsize-instruction-surfaces-by-incumbent-first-arbitration.md)
+  rather than a parallel lane; its three candidate inputs are tracked on the issue
+  tracker since that effort's contract slice has graduated.
+
+## Consequences
+
+Eight plugins gained contract lines and minor version bumps (discovery, education,
+verification, prototype, planning, discipline, session-flow, implementation), each with
+evals extended in the same commit. Two conventions are in force with named conformance
+surfaces. Deferred sub-decisions carry recorded triggers on the tracker (#3590 buy-in
+skill extension behind demand evidence; #3591 register-schema flag, tweak-likelihood
+flip, deviation-log registry row, digest-pipeline hardening). Reversal is possible but
+priced: each convention names its conformance surfaces, and the eval expectations
+outlive any instruction ablation, which is what makes a future deletion round provable.

plugins/discipline/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "discipline",
-  "version": "0.12.20",
+  "version": "0.13.0",
   "description": "Discipline correctors that re-anchor a standing rule mid-session, then audit both the work in flight and the pre-existing state and choices it trusts, and correct what has drifted: do-your-research (research and no-assumptions discipline; sibling do-your-research-deep escalates to a typed full inventory of the session's claims — assumptions, asserted facts, concrete specifics, load-bearing premises — verified at a configurable depth and reported as a per-item ledger), follow-our-standards (alignment to the consuming org's engineering conventions), point-dont-copy (pointer-over-copy discipline — no copied content, internal-name coupling, or closed capability lists), reason-dont-recite (interrogate inherited content — precedent is evidence of what is, never self-justifying authority), tighten-your-output (terseness discipline — fewer words or lines with no loss of meaning or correctness), recheck-against-upstream (existing state is not evidence of its own correctness — audit config, code, and infra against current official upstream docs; sibling recheck-against-upstream-deep fans subagents doc-by-doc over a whole subsystem), pick-for-the-problem (tool, library, framework, and approach selection fitted to the problem, not reached for out of habit, availability, incumbency, or preconception), mind-your-maxims (cooperative-communication discipline per Grice plus the AI-augmented transparency maxim), script-the-deterministic-work (offload deterministic sub-work — counts, diffs, sorts, transforms, and scaffolds — to a script that runs, reserving model output for judgment over its real output; the audit runs both ways, also catching an existing script that over-reaches into judgement), use-your-skills (actually use the skills already in context — scan the listing, map the task, invoke the fitting skill instead of reinventing it, and name skills when delegating to a subagent), and reuse-or-replace (anti-fragmentation — new work reuses an established way of doing something or openly replaces it (migrate the old uses, record the decision), never silently stands up a second parallel way; divergence is allowed but owes a recorded reason proportional to blast radius), and scrutinize-dont-coast (adversarial self-scrutiny — stop coasting on your own recent output and re-examine whether it is sound, not merely confidently produced, through a fresh-context pass blind to the reasoning that made it, then remediate with the user; it stops the trajectory first and remediates collaboratively rather than autonomously). Plus further species that are not correctors (examples, not a fixed list — each skill's own description is authoritative), including setup, sweep-all, a posture-batch runbook that composes them — it fans out an audit-only subagent per in-scope corrector, then applies the corrections on the main thread in a fixed order, with batch membership and order set by each corrector's own colocated tier metadata and an optional userConfig overlay — and wait-what, a one-shot user-invoked-only communication repair: type /discipline:wait-what when the last message did not land and the model re-pitches it, backing up as far as needed, adding the missing context, in ASD-STE100 Simplified Technical English, using the project's ubiquitous language; never model-invoked and never in the batch. Firing a corrector is a re-anchor, not an accusation; the audit may return clean.",
   "author": {
     "name": "Melodic Software",

plugins/discipline/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to the `discipline` plugin are documented here. Format follo
 
 Entries below `0.9.0` were released under the plugin's former name, `re-anchor`.
 
+## [0.13.0]
+
+### Added
+
+- **`point-dont-copy`: the no-analogue trap check and a canonical invocation hint.** The audit
+  list gains the cross-stack port trap: a source-side primitive with no target-side analogue (a
+  language feature, a library guarantee, an implicit runtime behavior) whose invariant the port
+  silently drops — the port must name the convention now carrying that invariant, or the finding
+  stands. The skill also gains an `argument-hint` showing the canonical invocation. Adopted from
+  the "Finding Your Unknowns" corpus at the integration sign-off (E7, E8; provenance in
+  `docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository). Evals extended.
+- **`point-dont-copy`: semantics map + confirmation gate for external-reference ports.** A
+  declared step delta on the shared re-anchor/audit/correct loop, scoped to ports whose source
+  of truth lives outside this repo's tree (vendored, foreign-language, other-repo): between
+  audit and correct-forward, produce a five-section semantics map (what the source does,
+  side-by-side pairs, preserved/changed/dropped ledger, edge-case parity table, open questions)
+  and stop at a confirmation gate until the user confirms it — "semantics confirmed" recommended,
+  not required. In-tree corrections stay do-it-now; the no-analogue trap check feeds the dropped
+  ledger. Same adoption basis (E6, boundary per the signed C3); a new eval case covers the gate.
+
 ## [0.12.20]
 
 ### Changed

plugins/discipline/skills/point-dont-copy/SKILL.md

@@ -1,5 +1,6 @@
 ---
 description: "Re-anchor pointer-over-copy discipline, then audit the work in flight for copied content, internal-name coupling, and closed capability lists, and correct by pointing at the living source. Use when: 'point don't copy', 'you copied that', 'don't duplicate the docs', 'cite instead of paste', 'link don't restate', 'you enumerated the tools', 'that couples to internal names', 'this will drift', or at conversation start on documentation work."
+argument-hint: "[target] (e.g., /discipline:point-dont-copy the new setup guide, or empty to audit the work in flight)"
 user-invocable: true
 disable-model-invocation: false
 metadata:
@@ -81,14 +82,39 @@ Name concrete, located findings (per the method doc's step 2, self-audit):
   invocation contract would do;
 - a closed enumeration of duties or mechanisms that will drift as the
   surface evolves;
-- the same passage, literal, or concept appearing in two or more places.
+- the same passage, literal, or concept appearing in two or more places;
+- in a port from another stack or language: a source-side primitive with no
+  target-side analogue (a language feature, a library guarantee, an
+  implicit runtime behavior) whose invariant the port silently drops. The
+  port must name the convention now carrying that invariant, or the
+  finding stands.
 
 Correct each forward now: replace the copy with a pointer to its owner,
 swap an internal-name reference for the public contract, and reopen a
 closed enumeration into a general duty with marked examples. Where content
 is genuinely this project's own to hold (an adapted config, a self-pinned
 constraint, a dated research deliverable), say so and leave it.
 
+## External-reference ports. Semantics map + confirmation gate
+
+**Scope.** This section governs external-reference ports only: work whose source of truth
+lives outside this repo's tree: vendored, foreign-language, other-repo. In-tree
+corrections stay on the method doc's do-it-now side; nothing here changes that.
+
+**Declared step delta** (per the method doc's "Declared step deltas" allowance): for an
+external-reference port, insert between the loop's steps 2 and 3 a semantics map and a
+confirmation gate, because a port that starts before the semantics are agreed bakes
+misreads into working code, where the audit can no longer see them as findings:
+
+- **Semantics map**, externalized, five sections: what the source does; side-by-side
+  pairs (source construct against port construct); a preserved / changed / dropped
+  ledger; an edge-case parity table; the open questions the port cannot settle alone.
+  The no-analogue trap check above feeds the dropped ledger: every dropped source
+  primitive names the convention now carrying its invariant.
+- **Confirmation gate.** Stop and wait for the user to confirm the map before port work
+  proceeds. A reply of "semantics confirmed" is the recommended token, not a required
+  one; any clear confirmation opens the gate.
+
 ## What this skill does NOT do
 
 - **Does not strip legitimate local content.** An adapted config, a

plugins/discipline/skills/point-dont-copy/evals/evals.json

@@ -10,7 +10,8 @@
       "expectations": [
         "Flags both the verbatim-pasted reference and the reworded paraphrase as duplication findings",
         "States that a reworded paraphrase drifts the same as a verbatim copy",
-        "Corrects forward by replacing the copied content with a pointer/citation to the owning source"
+        "Corrects forward by replacing the copied content with a pointer/citation to the owning source",
+        "In a cross-stack port, a source-side primitive with no target analogue is flagged unless the port names the convention now carrying its invariant"
       ]
     },
     {
@@ -48,6 +49,19 @@
         "Recommends consolidating to a single source and pointing at it",
         "Leaves room for a merits-based legitimate-divergence exception rather than an absolute rule"
       ]
+    },
+    {
+      "id": 5,
+      "name": "external-reference-port-gate",
+      "prompt": "Port this Python rate-limiter module from the vendored library into our TypeScript services package. Keep the behavior identical.",
+      "expected_output": "Recognizes an external-reference port (source of truth outside this repo's tree: vendored, foreign-language, other-repo) and applies the declared step delta: produces the five-section semantics map (what the source does; side-by-side pairs; preserved/changed/dropped ledger; edge-case parity table; open questions), with the no-analogue trap check feeding the dropped ledger, then stops at the confirmation gate and waits for the user to confirm the map before any port code is written. A 'semantics confirmed' reply is recommended, not required.",
+      "files": [],
+      "expectations": [
+        "Classifies the task as an external-reference port (source of truth outside this repo's tree) and applies the semantics-map step delta",
+        "Produces a semantics map with side-by-side pairs, a preserved/changed/dropped ledger, and an edge-case parity table before porting",
+        "Stops and waits for the user to confirm the map before port work proceeds, recommending but not requiring a 'semantics confirmed' reply",
+        "Does not extend the stop-and-wait gate to in-tree corrections, which stay do-it-now per the shared method doc"
+      ]
     }
   ]
 }

plugins/discovery/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "discovery",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Structured discovery before changes: explore the local codebase, run disciplined multi-source external research, and reconstruct why a past decision was made from evidence outside the code — each dispatching a purpose-built subagent by default so the reading stays out of the main conversation, with source tiers, falsification, recency gates, an intent-evidence tier, and a corpus-coverage ledger — persisting EXPLORE.md / RESEARCH.md / INTENT.md index-plus-sidecar handoff artifacts.",
   "author": {
     "name": "Melodic Software",

plugins/discovery/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog — discovery plugin
 
+## [0.19.0]
+
+### Added
+
+- **`blindspot`: typed finding cards and a scan-scope disclosure line.** Each blindspot card now
+  leads with a finding type from a four-way taxonomy — Landmine (breaks something non-obvious),
+  History (a constraint whose reason the code no longer shows), Convention (an unwritten team
+  rule), Missing concept (a domain idea the framing never named) — so repeated runs teach the user
+  which kinds of unknowns they tend to carry. The output also ends with a one-line scan-scope
+  disclosure naming which lane(s) ran and what was and was not scanned. Adopted from the
+  "Finding Your Unknowns" corpus at the integration sign-off (team-convention tier, evidence and
+  provenance in `docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository); evals extended to
+  cover both contract lines.
+
 ## [0.18.0]
 
 ### Changed