linersh 0.5.7 → 1.0.1

package/cli-update-docs/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: curating-mixtapes
-description: Use when the user wants to build a "mixtape" — a curated bundle of sources (videos, articles, papers, specs) assembled as AI context for a specific job-to-be-done. Triggers include "help me make a mixtape on X", "curate sources on Y for AI", "build a context bundle for Z", "let's research X with Liner", "make me a tape on Y", "help me build a Liner mixtape". Drives the eight-phase Liner curation methodology end-to-end and produces a mixtape project folder — `tape.yaml`, `synthesis.md`, and `working/*` notes — ready for `liner compile`. Defaults to quick mode (the AI does the heavy lifting, the user confirms at two gates); methodology mode is available when the user wants to engage substantively at every step or is targeting library contribution.
+description: Use when the user wants to build a "mixtape" — a curated bundle of sources (videos, articles, papers, specs) assembled as AI context for one hyper-specific future-agent task. Triggers include "help me make a mixtape on X", "curate sources on Y for AI", "build a context bundle for Z", "let's research X with Liner", "make me a tape on Y", "help me build a Liner mixtape", or "I want this Liner to help my AI agent do X". Drives the eight-phase Liner curation methodology end-to-end and produces a corpus folder — `tape.yaml`, `synthesis.md`, and `working/*` notes, under `mixtape/` in v2 projects — ready for `liner compile`. Defaults to quick mode (the AI does the heavy lifting, the user confirms at two gates); methodology mode is available when the user wants to engage substantively at every step or is targeting library contribution.
 ---
 
 # Curating Mixtapes
 
-This skill implements the Liner curation methodology (CURATION.md v2.0). A mixtape is a curated bundle of sources designed to make AI conversations meaningfully better within a specific domain. The bar: a good mixtape demonstrably improves AI output on tasks within its job-to-be-done.
+This skill implements the Liner curation methodology (CURATION.md v2.0). A mixtape is a curated bundle of sources designed to make future AI sessions meaningfully better at one hyper-specific task. The bar: a good mixtape demonstrably improves agent output inside the capability it was built for.
 
 The output of this skill is a project folder ready for `liner compile`. The skill does not compile.
 
@@ -14,25 +14,26 @@ The output of this skill is a project folder ready for `liner compile`. The skil
 ## Terminology — get these right
 
 - **Tape file** (`tape.yaml`) — the recipe. Sources with notes and sections.
-- **Mixtape** — the project folder. Recipe + synthesis + working notes + source content + master file.
-- **Consumable mixtape** — `MIXTAPE.md` plus the `sources/*.md` files. What gets pasted into an AI conversation. Produced by `liner compile`.
+- **Mixtape** — the corpus folder. In v2 projects it lives under `mixtape/`.
+- **Consumable mixtape** — `MIXTAPE.md` plus the `sources/*.md` files inside the corpus folder. What gets pasted into an AI conversation. Produced by `liner compile`.
 
 Tape ≠ mixtape. The recipe is small; the mixtape is the realized artifact.
 
 ## What this skill produces
 
-A project folder named for the topic (e.g., `mobile-design-foundations/`) containing:
+A project folder named for the topic (e.g., `mobile-design-foundations/`) containing a corpus folder. In v2 projects, these files live under `mixtape/`; legacy or standalone skill runs may use the project root:
 
 - `tape.yaml` — the recipe, conforming to MIXTAPE-FORMAT v1 (with v1.1 additions: `mode`, `jtbd`, `local_file` sources, optional `render` field on web sources)
 - `synthesis.md` — the curator's distilled understanding of the domain
-- `working/01-jtbd-and-knowledge-map.md` — framing artifacts
+- `working/01-jtbd-and-knowledge-map.md` — framing artifacts: JTBD, capability brief, knowledge map, and required source roles
 - `working/02-candidate-longlist.md` — the unfiltered candidate pool
-- `working/03-evaluation.yaml` — keep/trim/drop decisions with rationales and ratings
-- `working/04-quality-checks.md` — redundancy, coverage, disagreement, and framing-gap findings
+- `working/03-evaluation.yaml` — keep/trim/drop decisions with rationales, ratings, content evidence, and source-role mapping
+- `working/04-quality-checks.md` — redundancy, coverage, disagreement, framing-gap, source-kind, note-quality, and source-role findings
+- `working/05-operating-fit-audit.md` — optional improvement recommendation when the corpus is not yet strong enough for the Operating Layer
 
-`sources/` and `MIXTAPE.md` are produced later by `liner compile`. The optional `working/05-empirical-test.md` file is produced only when the curator runs the methodology validation step; it is not a driven TUI phase.
+`sources/` and `MIXTAPE.md` are produced later by `liner compile` in the same corpus folder. The optional `working/06-empirical-test.md` file is produced only when the curator runs the methodology validation step; it is not a driven TUI phase.
 
-When the curator has supplied local material (book chapters, exported PDFs, Reader-Mode-saved articles), the skill may write `local_file` entries in `tape.yaml` pointing at files the curator has placed under `personal/`. This is a methodology-mode affordance — the curator's local context belongs to them, not the public web, and the `local_file` source type makes it first-class. Library contributions still exclude `local_file` sources; the skill should not invent them or suggest paths the curator hasn't supplied.
+When the curator has supplied local material (book chapters, exported PDFs, Reader-Mode-saved articles), the skill may write `local_file` entries in `tape.yaml` pointing at files the curator has placed under `local-sources/` or the legacy `personal/` folder. This is a methodology-mode affordance — the curator's local context belongs to them, not the public web, and the `local_file` source type makes it first-class. Library contributions still exclude `local_file` sources; the skill should not invent them or suggest paths the curator hasn't supplied.
 
 ## Companion files
 
@@ -44,7 +45,7 @@ This skill is split across files in its own directory. Read each companion file
 - `quality-check-tests.md` — read before Phase 5
 - `synthesis-guidance.md` — read before Phase 6
 
-The orchestration logic, the two modes, the two gates, the AI-bias list, and the failure-mode list stay in this file because they apply across the whole lifecycle.
+The orchestration logic, the two modes, the review gates, the AI-bias list, and the failure-mode list stay in this file because they apply across the whole lifecycle.
 
 ## Two modes
 
@@ -69,27 +70,40 @@ Run these phases in order. Each phase's output feeds the next. Do not reorder.
 
 ### Phase 1 — Framing
 
-Define the job-to-be-done and sketch a knowledge map.
+Define the reusable capability and sketch a knowledge map.
 
-**The JTBD is a Job Story, not a topic.** Required form: `When [circumstance], I want [motivation], so I can [outcome].` All three slots required. "Mobile design" is a topic. *"When I'm designing the core UI of a consumer iOS app, I want to follow Apple's interaction conventions while choosing where to deviate visually, so I can ship something that feels native without looking generic."* is a JTBD. Three different Job Stories in the same topic area produce three different mixtapes.
+The user-facing question is: **What do you want this Liner to help your AI agent do?** The user can answer in plain language. Do not make them supply source categories, research lanes, or a formal Job Story.
 
-Elicit the JTBD using the [JTBD Master Prompt](JTBD-MASTER-PROMPT.md) — drop its body into this phase as your interview script. It opens with a single short context-sharing question (offering to read project material if the user has any), reads what's shared if anything, then either runs a budgeted interview (five questions max) or descends the scope ladder from what was inferred. It drafts silently, checks the draft against a six-test rubric, and emits one sentence. If the user pushes back, take the correction and re-run the rubric — don't defend.
+Your job in Phase 1 is to translate that plain-language goal into a Capability Brief:
 
-If you can't use the master prompt as-is (e.g., you're in a context where pasting it doesn't make sense), the minimum bar is: refuse any answer that's a bare topic, an aspiration ("be better at X"), a slot-missing fragment, or two jobs joined by "and." Stay on framing until the JTBD is a concrete single-sentence Job Story.
+- what future AI sessions should be able to do,
+- what outputs, decisions, or behaviors the resource should support,
+- the internal job-to-be-done that will let later phases judge fit,
+- research lanes inferred from the goal,
+- source requirements and exclusions,
+- runtime behavior for the future agent, including when it should ask the user clarifying questions.
+
+The internal JTBD should be hyper-specific. "SEO" is a topic. "SEO keyword research for a mental-health startup specialized in brain surgery" is a capability narrow enough to research. If the user's goal is still broad, ask targeted questions and descend until the capability is specific enough that a corpus built for it could outperform generic model knowledge.
+
+**Capability brief.** A short statement of the concrete capability this mixtape should give a downstream AI agent. This is not a persona or project name. It is the work the corpus must make the agent better at.
 
 **Knowledge map.** A short outline of the conceptual territory the corpus needs to cover. Four to eight sections, each with a few sub-areas. Treat it as a hypothesis — it will get revised during research.
 
-Write both to `working/01-jtbd-and-knowledge-map.md`. In quick mode: draft, show, get a one-line confirmation. In methodology mode: iterate with the curator until both feel right.
+**Required source roles.** The evidence plan for the corpus. Name the kinds of sources the downstream agent needs before the mixtape can be trusted. Each role must include: role name, why it matters, what good evidence looks like, and minimum coverage. These are inferred from the user's desired capability, not hardcoded categories.
+
+**Capability patterns.** If the user's goal implies a recurring evidence shape, name it in the Capability Brief. The most important current pattern is `reference-translation`: the future agent receives images, moodboards, visual references, inspiration, style examples, artifacts, or examples from one medium/domain and must turn them into another output. For this pattern, source roles must separate input/reference-domain interpretation, cross-domain translation method, target-output constraints, critique/clarification, and caller handoff language. Target-output implementation sources are bridge evidence; they cannot satisfy the reference-domain or translation-method roles by themselves.
+
+Write the Capability Brief, internal JTBD, research lanes, knowledge map, and Required source roles to `working/01-jtbd-and-knowledge-map.md`. In quick mode: draft, show, get a one-line confirmation. In methodology mode: iterate with the curator until the capability brief, knowledge map, and source roles feel right.
 
 ### Phase 2 — Candidate discovery
 
 **Read `source-finding-tactics.md` before starting this phase.**
 
-Generate a long list of candidate sources across the knowledge map. URLs and titles only — no fetching yet. Aim wide: two to four times the eventual kept count. This phase is recall, not precision.
+Generate a long list of candidate sources across the knowledge map and required source roles. URLs and titles only — no fetching yet. Aim wide enough for the evidence contract: roughly two to four times the eventual kept count, with the actual candidate count derived from the required source roles, capability pattern, and source ecology. This phase is recall, not precision.
 
 Verify each candidate exists at the URL given. AI is prone to hallucinating plausible-sounding URLs. Treat unverified URLs as candidates only until they're confirmed.
 
-Write to `working/02-candidate-longlist.md`, grouped by knowledge-map section. For each candidate: URL, title, one-line reason it's a candidate.
+Write to `working/02-candidate-longlist.md`, grouped by knowledge-map section. For each candidate: URL, title, required source role served, and one-line reason it's a candidate.
 
 **At Gate 1, show the long-list and ask:** "Anything obviously missing? Anything obviously wrong? Confirm to start fetching." In quick mode the default is "looks good, continue." In methodology mode, expect real edits.
 
@@ -101,6 +115,8 @@ For each URL, retrieve the full text. YouTube: transcript. Articles, papers, doc
 
 If a URL fails to fetch (paywall, dead link, no transcript, geographic block): note the failure, decide whether the source is critical enough to chase via an alternate route (Wayback Machine, alternate venue), and either find a substitute or drop it. Don't silently lose candidates.
 
+Bound the chase: try one direct fetch/read and at most one recovery attempt per candidate. After two failed retrieval attempts total, stop searching for that candidate and carry the failure into Phase 4 as part of the decision rationale.
+
 A successful transcript fetch is not the same as a high-value source. Many tutorial videos transcribe cleanly but contain no transferable content. The next phase handles that judgment.
 
 Don't write fetched content into the project folder yet. That happens at compile time, only for kept sources.
@@ -111,7 +127,15 @@ Don't write fetched content into the project folder yet. That happens at compile
 
 Read every fetched source against the JTBD. Decide keep / trim / drop. Rate kept sources 1–5. Draft curator notes for kept and trim sources.
 
-Write decisions to `working/03-evaluation.yaml`:
+If content was unavailable after the bounded fetch attempts, still write a decision for that candidate. Usually choose `dropped`. Do not mark a source `kept` or `trim` from title, URL, search snippet, crawler metadata, or model memory alone.
+
+Every `kept` or `trim` source must carry evidence fields in `working/03-evaluation.yaml`:
+
+- `fetch_status: readable | partial` — `readable` means the substantive article, transcript, PDF body, or local content was retrieved. `partial` means enough real source content was retrieved to judge, such as an abstract plus substantial excerpt. `metadata_only` and `unavailable` candidates must be `dropped`.
+- `content_quality: high | medium` — low-quality content, SEO filler, AI-generated sludge, generic listicles, homepages, galleries without rationale, or shallow transcripts must be `dropped`.
+- `evidence:` — at least two content-specific bullets from the fetched/read source. These are concrete claims, examples, sections, transcript moments, methods, or limitations seen in the content. Search snippets and titles do not count.
+
+Write decisions incrementally as section-sized fragments in `working/evaluation-decisions/`, then write or let Liner assemble `working/03-evaluation.yaml`. Do not hold all decisions in conversation memory until the end.
 
 ```yaml
 candidates:
@@ -119,6 +143,12 @@ candidates:
     title: Source title
     decision: kept            # kept | trim | dropped
     rating: 5                 # 1-5; required for kept and trim
+    fetch_status: readable    # readable | partial; metadata_only/unavailable are dropped
+    content_quality: high     # high | medium; low is dropped
+    source_role: canonical method
+    evidence:
+      - First content-specific claim, section, example, or method retrieved from the source.
+      - Second content-specific detail proving the source was read.
     section: foundations
     rationale: One-sentence reason this decision was made.
 ```
@@ -129,11 +159,11 @@ Drafted curator notes land in `tape.yaml` at Phase 7. Write them now in their fi
 
 **Read `quality-check-tests.md` before starting this phase.**
 
-Step back from the keep-pile. Run the four tests. Document findings in `working/04-quality-checks.md`.
+Step back from the keep-pile. Run the core-action test and the eight standard tests. Document findings in `working/04-quality-checks.md`.
 
-If a test fails, fix it before moving on. Don't proceed to synthesis with known coverage or framing gaps.
+If a test fails, fix it before moving on when the fix is small enough for the quality phase. If the failure points to a wider source-role gap, write `working/05-operating-fit-audit.md` with `status: improvement_recommended`, the gap, why it matters, concrete search lanes, and custom-source suggestions. Do not call the corpus "ready with limitation"; let Liner offer the user an improvement pass or a clear Skip.
 
-*Tip: this phase benefits from running with fresh attention. If the conversation has been long, consider starting a separate chat with just the JTBD, knowledge map, and the kept-source list (titles + notes only) to run the checks. Optional, not required by the methodology.*
+*Tip: this phase benefits from running with fresh attention. If the conversation has been long, consider starting a separate chat with just the JTBD, capability brief, required source roles, knowledge map, and the kept-source list (titles + notes only) to run the checks. Optional, not required by the methodology.*
 
 **At Gate 2, show the final keep-list, the curator notes, and the quality-check findings. Ask:** "Confirm to proceed to synthesis." Quick mode default: continue. Methodology mode: expect substantive edits.
 
@@ -141,7 +171,7 @@ If a test fails, fix it before moving on. Don't proceed to synthesis with known
 
 **Read `synthesis-guidance.md` before starting this phase.**
 
-Draft `synthesis.md`. The synthesis is the curator's distilled understanding of the domain expressed as continuous prose. 800–2000 words.
+Draft `synthesis.md`. The synthesis is the curator's distilled understanding of the domain expressed as continuous prose. 800–2000 words. It must include `## Generative rules` and `## Stances this corpus takes` so the consuming AI gets explicit operating rules and corpus stances before reading individual sources.
 
 Quick mode: draft, show, default to "looks good, save it." The curator lightly edits if they want.
 
@@ -157,8 +187,8 @@ Write `tape.yaml`.
 
 **Each kept source needs:**
 
-- `type` — `youtube` or `web` (v1 supports only these two; gated content, local files, and pasted content are v2)
-- `url`
+- `type` — `youtube`, `web`, `local_file`, or `skill`
+- `url` for `youtube` and `web`; `path` for `local_file` or local/installed `skill` sources; `citation` for `local_file`
 - `note` — the curator note drafted in Phase 4
 - `section` — matches a knowledge-map section
 - `priority: optional` — only for sources the user can skip with `--skip-optional`
@@ -184,10 +214,10 @@ The only real test of whether the mixtape works.
 
 1. Compile: `liner compile <project-folder>`
 2. Open a fresh AI conversation. Don't paste the mixtape. Ask a substantive question that should benefit from the JTBD. Save the response.
-3. Open another fresh AI conversation. Paste `MIXTAPE.md` plus relevant `sources/*.md` files. Ask the same question. Save the response.
+3. Open another fresh AI conversation. Paste `mixtape/MIXTAPE.md` plus relevant `mixtape/sources/*.md` files. Ask the same question. Save the response.
 4. Compare. Is the with-mixtape response meaningfully better — more specific, more accurate, more nuanced, less generic?
 
-Write findings to `working/05-empirical-test.md`: the question, the two responses (or summaries), the honest verdict. If the mixtape didn't help: what's missing? Back to Phase 2 or 5.
+Write findings to `working/06-empirical-test.md`: the question, the two responses (or summaries), the honest verdict. If the mixtape didn't help: what's missing? Back to Phase 2 or 5.
 
 If the answers are similar, the mixtape isn't earning its place. Either the sources are too generic, the synthesis isn't doing enough work, or the JTBD is too broad. Don't skip this for library contributions.
 
@@ -200,6 +230,8 @@ The skill is the AI running the methodology. The AI has systematic biases that p
 - **Generic curator notes.** AI drafts notes that say "this is a useful resource" without specifying role, location of value, or limitations. Compensate by writing each note against the three-thing template in `curator-notes.md`.
 - **Primary-document blindness.** AI gravitates to secondary commentary over primary sources. If a domain has a spec, a standard, or a foundational paper, search for it specifically. Don't accept commentary as a substitute.
 - **Framing-gap blindness.** AI can't see what it didn't search for. The framing-gap test in Phase 5 is the methodological correction for this. Run it with intent — not as a checkbox, as a genuine "what am I missing" question.
+- **Source-role blindness.** AI can fill every knowledge-map section while missing an evidence role the job depends on. Use the required source roles from Phase 1 as a contract in Phase 2 and an audit checklist in Phase 5.
+- **Pattern flattening.** AI turns specialized capabilities into generic topic packs. A reference-translation project becomes "web design"; a medical SEO project becomes "SEO"; a legal drafting project becomes "writing." When Phase 1 names a capability pattern, Phase 2 and Phase 5 must preserve that pattern-specific evidence contract.
 - **Synthesis-as-recap.** AI-drafted synthesis tends to recap source content rather than distill the curator's framing of the domain. Push toward principles, contested questions, and framework distinctions — not "Source 1 says X; Source 2 says Y."
 
 If you find yourself producing any of these patterns, stop and correct.
@@ -210,22 +242,24 @@ When all phases complete, the project folder contains:
 
 ```
 <topic-slug>/
-├── tape.yaml
-├── synthesis.md
-└── working/
-    ├── 01-jtbd-and-knowledge-map.md
-    ├── 02-candidate-longlist.md
-    ├── 03-evaluation.yaml
-    ├── 04-quality-checks.md
-    └── 05-empirical-test.md   # if empirical validation was run
+└── mixtape/
+    ├── tape.yaml
+    ├── synthesis.md
+    └── working/
+        ├── 01-jtbd-and-knowledge-map.md
+        ├── 02-candidate-longlist.md
+        ├── 03-evaluation.yaml
+        ├── 04-quality-checks.md
+        ├── 05-operating-fit-audit.md   # if an improvement pass is recommended
+        └── 06-empirical-test.md        # if empirical validation was run
 ```
 
-Tell the user the folder is ready to compile with `liner compile <topic-slug>`. The compile step produces `MIXTAPE.md` and the `sources/` folder.
+Tell the user the folder is ready to compile with `liner compile <topic-slug>`. The compile step produces `mixtape/MIXTAPE.md` and `mixtape/sources/`.
 
 ## What this skill does NOT do
 
 - **Does not run `liner compile`.** That's the user's call, with the user's tools.
-- **Does not fetch from gated or local sources.** v1 supports only public `youtube` and `web` URLs. Personal sources (book chapters, gated articles, local files) are real and often high-value, but v1 doesn't support them.
+- **Does not fetch from gated accounts or private systems.** v1 supports public `youtube` and `web` URLs plus curator-supplied `local_file` and `skill` sources. The skill may reference local files the curator supplied, but it must not invent private paths or bypass access controls.
 - **Does not maintain the shared content cache.** That's the CLI's job.
 - **Does not publish to the library.** Library contributions happen via PR to the Liner repo, in methodology mode, after passing the empirical test.
 
@@ -240,5 +274,6 @@ Patterns that produce bad mixtapes. Watch for them in your own work:
 - **The noteless mixtape.** Sources without curator notes. The curator either was lazy or didn't have a reason. Both are problems.
 - **The aspirational mixtape.** Sources the curator thinks people *should* read, not sources that help with the JTBD. Mixtapes are tools, not reading recommendations.
 - **The single-pass mixtape.** Curated without a framing-gap test. Well-covered within one narrow framing, blind to perspectives the curator didn't think to look for.
+- **The role-missing mixtape.** Sections appear covered, but a required source role from Phase 1 has no fetched, useful evidence.
 
 If the mixtape this skill produces fits any of these patterns, return to the relevant phase and fix it.

package/cli-update-docs/quality-check-tests.md

@@ -2,11 +2,25 @@
 
 Loaded by the `curating-mixtapes` skill at the start of Phase 5 (Quality checks).
 
-This file describes the four tests every mixtape should pass before moving to synthesis. Apply them deliberately, in this order. Write findings to `working/04-quality-checks.md`.
+This file describes the core-action test and the eight standard tests every
+mixtape should pass before moving to synthesis. Apply them deliberately, in
+this order. Write findings to `working/04-quality-checks.md`.
 
 Phase 5 is the methodology's correction for single-pass curation. The first four phases work forward — frame, find, fetch, evaluate. Phase 5 works backward — looking at the whole keep-pile and asking what's wrong with it. The two passes do different work. If you skip this phase, the mixtape's blind spots ship with the mixtape.
 
-The framing-gap test is the highest-leverage of the four and the one most curators skip.
+The framing-gap and source-role tests are the highest-leverage checks and the ones most curators skip.
+
+## Automated-run budget
+
+When Phase 5 is running inside the TUI or another automated Liner flow, it must stay bounded. Treat it as an audit over `working/03-evaluation.yaml`, not as a second open-ended discovery phase.
+
+- Classify existing kept/trim sources before searching. If a source is missing `kind`, infer it from title, URL/source type, section, rating, and curator note, then update `working/03-evaluation.yaml`.
+- Missing `kind` metadata is not itself a corpus gap. It becomes a source-kind gap only after every existing kept/trim source has a kind and the distribution still has a zero column.
+- Use at most one search pass for any one missing perspective.
+- Use at most one source-kind backfill search total.
+- Do not exceed four external search/fetch attempts across the whole Quality phase. If the budget is spent, stop searching, document the gap or defense, and write `working/04-quality-checks.md`.
+- On resume after a paused/cancelled Quality run, do not continue a search loop. Use the evidence already gathered, repair weak curator notes from existing evidence, and close the artifact.
+- If a material source-role gap remains after the bounded audit, write `working/05-operating-fit-audit.md` with `status: improvement_recommended` instead of declaring the corpus ready with a limitation. Liner will offer a focused improvement pass or let the user skip for now.
 
 ---
 
@@ -16,12 +30,56 @@ Before running the tests, gather the inputs in one place:
 
 - The JTBD (from `working/01-jtbd-and-knowledge-map.md`)
 - The knowledge map (same file)
+- The required source roles (same file)
 - The kept and trim sources from `working/03-evaluation.yaml` — titles, sections, ratings, rationales, and the drafted curator notes
 
 Read these together. The tests are about how the corpus *as a whole* serves the JTBD. You can't run them well by looking at sources one at a time.
 
 ---
 
+## Test 0 — The core-action fit test
+
+Name the exact action in the JTBD. Then ask whether the kept sources directly
+teach or demonstrate that action, or merely orbit it.
+
+This test exists because coverage can pass while the job still fails. A corpus
+for "turn moodboards into HTML interface concepts" can technically cover
+"visual hierarchy," "design systems," "CSS layout," and "process," yet still
+miss the action of reading visual references, extracting transferable qualities,
+and creating a new interface direction.
+
+### How to run it
+
+1. Quote or paraphrase the JTBD's core action in `working/04-quality-checks.md`.
+2. Count kept sources by `jtbd_fit`: `direct / bridge / background`.
+3. If older entries lack `jtbd_fit`, infer it from title, rationale, note, and
+   section, then update `working/03-evaluation.yaml`.
+4. List which kept sources are direct. A healthy action-oriented mixtape needs
+   at least two direct sources, and each central knowledge-map section needs
+   either one direct source or a written reason why bridge coverage is enough.
+5. For curator-named anchors, say whether you retrieved rationale/process
+   evidence or only a homepage/gallery/metadata pointer.
+
+If direct coverage is weak, take one action:
+
+- Backfill direct sources within the Phase 5 search budget, or
+- Document the gap and recommend re-running Candidate discovery with
+  action-specific search terms.
+
+### Required output
+
+```
+## Test 0 — Core-action fit
+
+Core action: [verb phrase from JTBD]
+Distribution: X direct / Y bridge / Z background
+Direct sources: [Source titles]
+Finding: [pass / weak coverage / gap]
+Action: [kept, backfilled, or documented rerun recommendation]
+```
+
+---
+
 ## Test 1 — The redundancy test
 
 Read each kept source's role in the mixtape. Are any two sources making essentially the same point?
@@ -75,7 +133,7 @@ Step back from individual sources. Is there a major perspective on this topic mi
 
 If yes, the framing was too narrow. Expand the knowledge map and return to Phase 2.
 
-**This test is the highest-leverage of the four and the one most curators skip.** Single-pass curation tends to produce mixtapes that are well-covered within one narrow framing. The framing-gap test catches what the first four phases couldn't see.
+**This test is the highest-leverage of the six and the one most curators skip.** Single-pass curation tends to produce mixtapes that are well-covered within one narrow framing. The framing-gap test catches what the first four phases couldn't see.
 
 ### How to run it (required steps, in order)
 
@@ -150,7 +208,7 @@ Imbalance is not a failure. A 7-principle / 2-prescription / 1-reference / 0-exa
 
 > *Kinds audit: 7 principle / 9 prescription / 5 example / 0 reference. Accepted: this JTBD is about voice and microcopy, not architectural conventions. No reference source is needed because the synthesis doesn't make authority claims that would require backing.*
 
-If the zero isn't defensible, run one search pass for a source of the missing kind before shipping. The same rule as Test 4(a) applies: search for the role the kind plays (an authoritative spec, an opinionated essay, a tight rule-set, a worked example), not for the topic generically.
+If the zero isn't defensible, first make sure every existing kept/trim source has been assigned a kind. Only then run one source-kind backfill search before shipping. The same rule as Test 4(a) applies: search for the role the kind plays (an authoritative spec, an opinionated essay, a tight rule-set, a worked example), not for the topic generically.
 
 ### Required output
 
@@ -166,14 +224,190 @@ Distribution: X reference / Y principle / Z prescription / W example
 
 ---
 
+## Test 6 — Note-quality smell test
+
+Read every kept/trim source note in `working/03-evaluation.yaml`. The note is the consuming AI's instruction for how to weight and use that source. A source with a vague note is a bookmark, not curation.
+
+A useful curator note must do three jobs:
+
+- **Use cue:** tell the AI how to read or apply the source.
+- **Value/bar:** name the concrete value, standard, or quality bar the source contributes.
+- **Boundary:** name one limitation, scope boundary, or reason not to over-weight it.
+
+Thin notes often look like "useful background," "good overview," or "skim for examples." They may be true, but they do not tell the AI what to do with the source. Repair them before synthesis by updating `working/03-evaluation.yaml`; do not search or fetch just to improve note prose. Use the already gathered title, rationale, source type, section, rating, and partial content.
+
+### Required output
+
+`working/04-quality-checks.md` must include a Test 6 section like this:
+
+```
+## Test 6 — Note-quality
+
+Checked: N kept/trim notes
+Repaired: M notes
+
+- Source/title/URL — repaired missing boundary; note now names [scope].
+```
+
+If no notes were repaired, write one sentence explaining why the notes already carry a use cue, value/bar, and limitation.
+
+---
+
+## Test 7 — Source-role fit
+
+This test asks whether the corpus has the evidence roles the future AI actually
+needs. It catches the failure mode where a source list technically covers every
+section and every source `kind`, but still cannot do the job well.
+
+Source roles are capability-specific evidence jobs named in the Capability
+Brief. They are not source `kind`s and not section labels. A source can be an
+`example` kind without satisfying the required "worked high-craft case study"
+role if the fetched content is only a homepage, gallery index, or shallow
+portfolio blurb. A source can be a `reference` kind without satisfying the
+required "medical authority" role if it is a secondary explainer instead of a
+primary clinical or institutional source.
+
+### How to run it
+
+1. Read `working/01-jtbd-and-knowledge-map.md` and copy the Required source
+   roles from the Capability Brief into `working/04-quality-checks.md`.
+2. If the project was framed before Required source roles existed, infer 4–7
+   roles from the core action and write them into the quality report before
+   scoring coverage.
+3. For each role, count kept/trim sources whose fetched evidence actually
+   satisfies that role. Count by content, not by title, URL, section, or generic
+   kind.
+4. Compare coverage to the minimum named in the Capability Brief. If no minimum
+   was named, use these defaults:
+   - 2 strong sources for ordinary required roles.
+   - 3 substantive worked examples/case studies when the capability depends on
+     taste, visual output, craft judgment, or recognizing quality.
+   - primary/official sources for legal, medical, financial, or safety-sensitive
+     authority roles.
+5. A material role with weak coverage must either be improved within the Phase 5
+   budget or written to `working/05-operating-fit-audit.md` with
+   `status: improvement_recommended`.
+
+"Light but not absent" is not a pass for a required source role. It is a weak
+coverage finding.
+
+### Required output
+
+`working/04-quality-checks.md` must include:
+
+```
+## Test 7 — Source-role fit
+
+Required roles:
+- Core-action method — minimum: 2; current: 3; status: pass; evidence: [Source titles]
+- Worked craft examples — minimum: 3; current: 1; status: weak; evidence: [Source title]
+
+Action: [kept / backfilled / wrote working/05-operating-fit-audit.md]
+```
+
+If a required role is missing or weak, take one of three actions:
+
+- **Backfill now.** Search for the role directly, add a verified candidate, evaluate it, and update the keep-list.
+- **Document the limitation.** If credible sources are unavailable, write a concrete limitation and what custom source the curator should add.
+- **Narrow the capability claim.** If the role is not actually needed, update the Capability Brief and Required source roles so Phase 1 tells the truth.
+
+Do not leave a missing required role as "covered by the overall corpus." That is exactly how generic-looking mixtapes pass while still failing the user's job.
+
+---
+
+## Test 8 — Capability-pattern fit
+
+Some capabilities have a specialized evidence contract beyond generic source
+roles. Phase 1 should name these as `Capability pattern: ...` in the Capability
+Brief. Test 8 asks whether the final keep-list still satisfies that pattern, or
+whether the corpus drifted into a generic topic pack.
+
+If no capability pattern was named, write:
+
+```
+## Test 8 — Capability-pattern fit
+
+Pattern: none
+Finding: pass. No specialized capability pattern was named in the Capability Brief.
+Action: none.
+```
+
+Do not invent a pattern in Phase 5 just to make the test look busy. If Phase 1
+clearly missed a pattern and the omission affects corpus quality, document that
+as a framing gap and write an operating-fit audit.
+
+### Reference-translation pattern
+
+Use this section when the Capability Brief says `Capability pattern:
+reference-translation`, or when Phase 1 should have named it because the job
+involves images, moodboards, visual references, inspiration, examples, style,
+art direction, or translating one medium/domain into another output.
+
+This pattern fails when a corpus becomes mostly about the target output medium.
+For example, an art-direction-to-web mixtape can pass ordinary "web design"
+coverage while still failing the real job: reading paintings, architecture,
+photos, posters, sports identity, or other references and translating their
+underlying qualities into product-design language.
+
+Run four checks:
+
+1. **Input/reference-domain coverage.** Count substantive kept/trim sources from
+   at least two input/reference domains outside the target output medium. Count
+   by content evidence, not by passing mention. For web/UI targets, CSS,
+   accessibility, token, component, and design-system docs do not count here.
+2. **Translation-method coverage.** Count direct kept/trim sources that teach or
+   demonstrate the move from source qualities to target decisions. Generic
+   inspiration galleries, moodboard primers without translation, and target
+   mechanics do not count.
+3. **Caller-handoff coverage.** Confirm the corpus supports a concrete runtime
+   output shape: observations, interpretation, carry-forward rules, product or
+   implementation vocabulary, constraints, avoid-list, validation checks, and
+   clarification questions.
+4. **Constraint balance.** Confirm target-medium constraints are present when
+   needed but do not outnumber and replace the direct reference-reading and
+   translation evidence in the core action.
+
+Default minimums for reference-translation:
+
+- At least 2 distinct input/reference domains outside the target output medium.
+- At least 3 substantive direct sources from those input/reference domains or
+  from cross-domain translation examples.
+- At least 2 direct translation-method sources.
+- At least 1 handoff/template/vocabulary source that shows how to make the
+  translation executable for the caller.
+
+If any minimum is weak or missing, write `working/05-operating-fit-audit.md` with
+`status: improvement_recommended`. Do not pass the corpus because general design,
+implementation, accessibility, or platform sources are strong.
+
+### Required output
+
+`working/04-quality-checks.md` must include:
+
+```
+## Test 8 — Capability-pattern fit
+
+Pattern: reference-translation
+Input/reference domains: [domain A: sources], [domain B: sources]
+Translation-method sources: [source titles]
+Caller-handoff sources: [source titles]
+Constraint balance: [pass / weak / gap]
+Finding: [pass / weak coverage / gap]
+Action: [kept / backfilled / wrote working/05-operating-fit-audit.md]
+```
+
+---
+
 ## What to do when a test fails
 
 Don't paper over failures. The point of running the tests is to find problems while they're still cheap to fix.
 
 - **Redundancy fails:** drop the weaker source, update `working/03-evaluation.yaml` to reflect the change, document the decision in `working/04-quality-checks.md`.
-- **Coverage fails:** return to Phase 2 for the missing section. Fetch new candidates. Evaluate them. Come back to Phase 5 and re-run all four tests on the new keep-list.
+- **Coverage fails:** return to Phase 2 for the missing section. Fetch new candidates. Evaluate them. Come back to Phase 5 and re-run all eight tests on the new keep-list.
 - **Disagreement fails:** find one strong dissenting source. Fetch it. Evaluate it. Add it to the keep-list with a note that names its role as counterpoint.
-- **Framing-gap fails:** this is the expensive one. Expand the knowledge map. Return to Phase 2. Find candidates for the new sections. Fetch, evaluate. Come back to Phase 5 with a substantially revised keep-list and re-run all four tests.
+- **Framing-gap fails:** this is the expensive one. Expand the knowledge map. Return to Phase 2. Find candidates for the new sections. Fetch, evaluate. Come back to Phase 5 with a substantially revised keep-list and re-run all eight tests.
+- **Note-quality fails:** rewrite weak notes in `working/03-evaluation.yaml` so each one carries a use cue, value/bar, and boundary. Do this from existing evidence; do not open a new search loop.
+- **Source-role fit fails / Operating-fit fails:** write `working/05-operating-fit-audit.md` with the missing source role, why it matters, concrete search lanes for an improvement pass, and a short list of custom sources the user could add if public research remains thin.
 
 Each backtrack is a sign the methodology is working, not failing. The first four phases produced a corpus that worked from one angle; Phase 5 found the angle that wasn't covered. Better to find it here than in the empirical test (Phase 8) or — worse — silently, when the mixtape is in use.
 
@@ -181,7 +415,21 @@ Each backtrack is a sign the methodology is working, not failing. The first four
 
 ## Output: `working/04-quality-checks.md`
 
-Document each test, the finding, and the action taken. Even tests that passed without changes should be noted — "redundancy test: no redundant sources found." The working notes are part of the methodology; they show what work was actually done.
+Document each test, the finding, and the action taken. Even tests that passed without changes should be noted — "core-action fit: 4 direct sources; no backfill" or "redundancy test: no redundant sources found." The working notes are part of the methodology; they show what work was actually done.
+
+If an improvement pass is recommended, also write `working/05-operating-fit-audit.md`:
+
+```yaml
+status: improvement_recommended
+gap: The missing source role or weak evidence role.
+why_it_matters: Why this gap would hurt a future AI agent using the corpus.
+recommended_pass:
+  - Search lane or source type Liner should look for.
+  - Search lane or source type Liner should look for.
+user_can_add:
+  - Concrete custom source the user could add if web research stays thin.
+skip_note: What remains weaker if the user skips for now.
+```
 
 > TODO: Insert a sample `working/04-quality-checks.md` from the Cowork synthesis. The full structure with each test, the finding, and the resulting action is the most useful worked example in this file.
 
@@ -191,6 +439,6 @@ Document each test, the finding, and the action taken. Even tests that passed wi
 
 Phase 5 benefits from running with fresh attention. The first four phases build up a mental model of the corpus that biases how you see it — you remember why you kept each source, which makes redundancy easier to miss; you remember the candidate searches you ran, which makes the framing-gap easier to miss.
 
-If the conversation has been long, consider starting a separate chat with just the JTBD, the knowledge map, and the kept-source list (titles + notes only, no source content). Run the four tests there. The fresh chat doesn't carry the gathering pass's biases.
+If the conversation has been long, consider starting a separate chat with just the JTBD, the knowledge map, the required source roles, and the kept-source list (titles + notes only, no source content). Run the quality tests there. The fresh chat doesn't carry the gathering pass's biases.
 
 This is optional, not required by the methodology. Mention the option to the curator. Quick mode users may prefer to continue in the same conversation for speed; methodology mode users often benefit from the reset.