linersh 0.5.6 → 1.0.0

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.

package/cli-update-docs/source-finding-tactics.md

@@ -2,9 +2,9 @@
 
 Loaded by the `curating-mixtapes` skill at the start of Phase 2 (Candidate discovery).
 
-This file describes the six tactics that produce better candidates than generic search. When you reach Phase 2, work through these tactics — not all of them for every mixtape, but enough that the candidate pool covers the knowledge map from multiple angles.
+This file describes tactics that produce better candidates than generic search. When you reach Phase 2, work through the relevant tactics — not all of them for every mixtape, but enough that the candidate pool covers the knowledge map and required source roles from multiple angles.
 
-The goal of Phase 2 is recall, not precision. You're producing two to four times the eventual kept count. You will cut in Phase 4. Casting wide here is the methodology working as designed.
+The goal of Phase 2 is recall, not precision. You're producing roughly two to four times the eventual kept count, but the real stop condition is coverage of the required source roles and capability-pattern lanes. You will cut in Phase 4. Casting wide here is the methodology working as designed.
 
 ---
 
@@ -91,9 +91,146 @@ This tactic is structurally related to the framing-gap test in Phase 5, but earl
 
 ---
 
+## 7. Search for the core action and the curator anchors
+
+A good candidate list is not just "sources about the topic." It must contain
+sources that help the consuming AI do the job.
+
+Start by extracting the JTBD's core action. Examples:
+
+- "translate moodboards into UI"
+- "turn bug reports into reproduction steps"
+- "write grant narratives from research evidence"
+
+Then search for candidate URLs that might directly teach, demonstrate, or argue
+for that action. Bridge candidates are allowed, but they cannot carry the corpus
+by themselves. For a moodboard-to-interface mixtape, CSS layout, design tokens,
+and design systems are bridge leads: useful after a direction exists, but not
+enough to teach how to read images, extract mood, or create a new interface
+artifact. The keep/drop decision still happens only after the content is fetched
+and read.
+
+When the curator names a person, studio, product, software tool, YouTube
+channel, or site they like, deepen the anchor. Search for their case studies,
+interviews, talks, process notes, docs, essays, videos, and worked examples.
+Do not stop at the homepage, gallery index, or crawler metadata unless that is
+the only readable evidence available. If it is only a pointer, say so in the
+candidate reason.
+
+For visual-output jobs, deliberately search for visual and worked-example
+evidence: image-heavy case studies, moodboard breakdowns, design rationale,
+portfolio projects with process, talks, and videos. A source list made mostly
+of UX primers, CSS references, and design-system docs is probably under-serving
+the job even if every knowledge-map section has a source.
+
+---
+
+## 8. Fill required source roles, not just sections
+
+The Capability Brief should name **Required source roles**: the jobs the corpus
+needs sources to perform for the future AI. These are not the same as source
+`kind` (`reference / principle / prescription / example`) and not the same as
+knowledge-map sections.
+
+Examples:
+
+- "core-action method" — sources that teach the exact action the agent must do
+- "worked examples / case studies" — sources that show good output, process, or taste
+- "domain authority" — primary/official sources the agent can cite for accuracy
+- "implementation constraints" — specs, APIs, platform docs, safety limits, or production rules
+- "critique / validation" — sources that help judge whether output is good
+- "dissent / alternate stance" — sources that prevent one-frame bias
+- "domain data" — keyword data, epidemiology, market signals, legal text, or other evidence specific to the niche
+
+When you build the long-list, make sure every required role has candidates. A
+populated section is not enough if a required role is thin. For a visual-output
+mixtape, two dozen UX/design-system articles do not substitute for worked
+visual/craft examples with rationale. For a medical SEO mixtape, SEO practice
+articles do not substitute for authoritative medical sources and domain-specific
+keyword or patient-language evidence.
+
+**How to apply:** For each required source role, search until you have 3–6
+plausible candidates or until it is clear public sources are thin. In the
+candidate reason, name the role the source might satisfy. If you cannot find
+credible candidates for a required role, write a "Role gaps" note in
+`working/02-candidate-longlist.md` so Quality can recommend a focused
+improvement pass instead of quietly accepting weak coverage.
+
+Candidate count should fall out of the role plan:
+
+- Narrow, single-domain projects may need fewer than 20 candidates.
+- Ordinary projects usually land around 20–35 candidates.
+- Broad, multi-domain, or `reference-translation` projects may need 40–60
+  candidates because each source domain and translation lane needs its own
+  candidate pool.
+
+Do not pad the list to hit a number. Do not stop at a number when a material
+role is still empty. Stop when every required role has credible candidates, the
+knowledge map is covered, and any capability-pattern lanes named in Phase 1 have
+enough evidence to evaluate.
+
+Good candidate notes should say which role the source might serve:
+
+- `source role: canonical method` — teaches the process the AI should follow
+- `source role: domain authority` — grounds claims in a credible source
+- `source role: applied example` — shows what good looks like in context
+- `source role: boundary / risk` — prevents harmful or misleading output
+
+---
+
+## 9. Build a source ecology for reference-translation jobs
+
+Some mixtapes are not just about a topic. They ask a future agent to read inputs
+from one world and turn them into outputs in another. Common examples:
+
+- images, moodboards, art direction, visual references, or style examples into a
+  product/interface brief
+- screenshots, bug reports, logs, or user complaints into engineering actions
+- research evidence, interview notes, or case studies into a narrative or plan
+
+These are **reference-translation** capabilities. Their candidate pool needs a
+source ecology, not a stack of sources from the final output medium.
+
+For visual/reference work, search at least these lanes:
+
+- **Input/reference-domain interpretation:** how practitioners read the source
+  worlds themselves, such as art, photography, architecture, interiors, posters,
+  editorial design, fashion, packaging, sports/media identity, film, or product
+  imagery.
+- **Translation methods:** sources that show how observed qualities become new
+  decisions: design-language extraction, style tiles, creative direction,
+  case-study rationale, annotated redesigns, or critique.
+- **Target-output constraints:** the platform/output realities that the final
+  work must survive, such as web responsiveness, accessibility, motion safety,
+  design systems, typography, or implementation mechanics.
+- **Caller handoff language:** brief formats, vocabulary, do/don't lists,
+  validation checks, and clarification patterns that make the result executable
+  by another designer, engineer, or AI agent.
+
+For an art-direction-to-web mixtape, CSS references, design-token specs, and
+accessibility docs are valuable bridge sources. They are not substitutes for
+visual-culture sources that teach the agent how to look, compare, interpret, and
+translate. A candidate list made mostly of web-craft sources should include a
+"Role gaps" note and keep searching for the missing input/reference domains.
+
+**How to apply:** Before writing `working/02-candidate-longlist.md`, add a short
+"Reference-translation source ecology" note to your own scratchpad or the
+long-list: target output medium, input/reference domains represented, translation
+method candidates, handoff candidates, and bridge/constraint candidates. If the
+input/reference domains are thin, search those domains directly instead of doing
+another generic target-output search. Do not stop at the ordinary 20–35 candidate
+range if the ecology is still missing a source world the future agent must learn
+to interpret.
+
+---
+
 ## What not to do
 
 - **Don't rely on generic search alone.** The first page of search results is what your audience could also find. The point of curation is to surface what they couldn't.
 - **Don't accept candidates without verifying URLs.** AI hallucinates plausible-looking URLs. Web-fetch every URL before it goes on the long-list. A 404 candidate is worse than a missing one.
-- **Don't filter at Phase 2.** That's Phase 4's job. If a source might be useful, it goes on the long-list. Quality decisions come after fetching and reading.
+- **Don't filter at Phase 2.** That's Phase 4's job. If a source might be useful, it goes on the long-list. Quality decisions come after fetching and reading. A URL is a lead, not evidence that the content is any good.
 - **Don't over-research one section while leaving others empty.** Walk the knowledge map. Each section should have a reasonable candidate pool before you go deep on any one section.
+- **Don't let adjacency satisfy the JTBD.** A CSS reference is not an art-direction source just because the final artifact is HTML. A process article is not a writing source just because the writer needs a process. Label these as bridge candidates unless they directly teach the core action.
+- **Don't collapse reference-translation work into the output medium.** If the future agent must translate paintings, photos, architecture, sports identity, or moodboards into a product direction, the candidate pool needs sources from those source worlds and from the translation move. Output-medium craft docs are necessary constraints, not the whole corpus.
+- **Don't let "not absent" pass a required role.** If a required role is material to the future AI's job, thin coverage should trigger backfill or an improvement-pass recommendation.
+- **Don't treat source roles as decorative.** A section can look populated while a required evidence role is absent. That is still a corpus gap.

package/cli-update-docs/source-quality-hierarchy.md

@@ -6,6 +6,8 @@ This file describes how to rank sources, what to avoid, and the patterns to watc
 
 The goal of Phase 4 is honest assessment against the JTBD. Not breadth. Not completeness. Not even fairness to every source. *Does this source help the consuming AI do the JTBD better?* If yes, keep it. If partially, trim it. If no, drop it.
 
+A URL is only a lead. The source is the readable content. Do not keep or trim a candidate from its URL, title, search snippet, crawler metadata, or your memory of the source. Keep/trim decisions require source evidence.
+
 ---
 
 ## Source-quality hierarchy
@@ -75,6 +77,76 @@ For each fetched source, decide one of: kept, trim, dropped. Rate kept and trim
 
 If you find yourself rating most sources 4–5, you're under-discriminating. The point of evaluation is to discriminate.
 
+## Evidence fields
+
+Every kept or trimmed source must include these 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.
+- `content_quality: high | medium` — `high` means dense, distinctive, and directly useful; `medium` means useful but selective. If the content is shallow, generic, AI-generated, SEO filler, a homepage/gallery without rationale, or a low-density transcript, drop it.
+- `evidence:` — at least two bullets naming source-specific claims, examples, sections, methods, transcript moments, or limitations actually seen in the content.
+
+`metadata_only` and `unavailable` candidates must be dropped. They can remain in the evaluation file as evaluated candidates, but they must not enter `tape.yaml` as normal corpus sources.
+
+---
+
+## JTBD-fit labels
+
+Every kept or trimmed source must also get a `jtbd_fit` label. This prevents
+topic adjacency from passing as source quality.
+
+- **direct** — the source teaches, demonstrates, or argues for the core action
+  in the JTBD.
+- **bridge** — the source helps execute the result after the core decision is
+  made: implementation mechanics, tokens, layout, process, API references, or
+  operational constraints.
+- **background** — broad vocabulary, primer, historical context, or generic
+  orientation.
+
+Bridge sources are valuable, but they are not the same as direct fit. If the job
+is "turn moodboards into HTML interface concepts," then a moodboard analysis
+method, a studio case study with rationale, or a talk on translating visual
+references can be direct. A CSS layout guide, token spec, or design critique
+process is a bridge unless it specifically teaches the translation move.
+
+For a `reference-translation` capability, use an even stricter direct-fit test:
+the source must help the future agent interpret the input/reference domain or
+demonstrate the translation from reference qualities into target-output
+decisions. Target-medium mechanics, accessibility standards, design-token
+formats, style-guide infrastructure, and implementation docs are usually bridge
+sources. They are important, but they cannot carry the core action alone.
+
+Background sources should rarely be marked required. A kept background source
+needs a narrow note explaining why its vocabulary or context is worth carrying.
+
+If a knowledge-map section contains only `bridge` or `background` sources, mark
+that as weak coverage in the rationale or quality report and backfill a direct
+source if the section is central to the JTBD.
+
+Quality also checks source roles at the corpus level. `reference / principle /
+prescription / example` is only the generic kind distribution; some projects
+need more specific roles. A visual art-director corpus may need high-craft case
+studies and worked image-to-interface translations. A medical SEO corpus may
+need clinical authority, search-intent evidence, and Google guidance. If those
+role-specific sources are missing, write an operating-fit audit and recommend a
+focused improvement pass instead of calling the corpus ready with a limitation.
+
+---
+
+## Bounded fetch fallback
+
+Phase 4 should read enough to make honest decisions, but it must not stall on
+unavailable content. For each candidate, try one direct fetch/read. If that
+fails, make at most one recovery attempt: alternate transcript source, search
+result, mirror, metadata page, or equivalent.
+
+After two failed retrieval attempts total, stop searching for that candidate and
+evaluate from verified metadata, the Phase 2 reason, and any partial content you
+have. Usually that means `dropped`. If you have enough partial content to judge,
+set `fetch_status: partial` and write the evidence bullets. If you only have
+metadata, set the decision to `dropped`; the rationale can say the candidate
+looked promising but was metadata-only. Every candidate still gets a decision in
+`working/03-evaluation.yaml`; no source may keep the phase open indefinitely.
+
 ---
 
 ## Patterns to watch for
@@ -115,14 +187,25 @@ Recent does not mean better. A 2024 article that summarizes well-known points is
 
 Write every candidate's decision, regardless of whether it was kept or dropped. The dropped decisions matter — they're how the working notes show that evaluation actually happened.
 
+For large candidate sets, write decisions incrementally under `working/evaluation-decisions/` as section-sized YAML fragments. Use names like `01-foundations.yaml` and keep each fragment small enough to inspect. Liner assembles those fragments into `working/03-evaluation.yaml` in the original longlist order, so the fragment files are the durable work surface and `03-evaluation.yaml` is the canonical assembled artifact.
+
 ```yaml
 candidates:
   - url: https://example.com/source
     title: Source title
     decision: kept            # kept | trim | dropped
     rating: 5                 # 1-5; required for kept and trim
+    jtbd_fit: direct          # direct | bridge | background
+    fetch_status: readable    # readable | partial; metadata_only/unavailable are dropped
+    content_quality: high     # high | medium; low is dropped
+    evidence:
+      - Specific claim or example found in the readable source content.
+      - Specific method, constraint, result, or limitation found in the content.
     section: foundations
     rationale: One-sentence reason this decision was made.
+    note: >
+      Role: Why this source belongs in the corpus. Value: What it contributes
+      to the job-to-be-done. Limitations: What the source cannot prove.
 ```
 
 For dropped sources, the rationale should name *why* dropped — "duplicates Source 4," "shallow listicle," "AI-generated," "off-topic relative to JTBD." Generic "low quality" is not useful. Be specific.

package/cli-update-docs/synthesis-guidance.md

@@ -20,12 +20,24 @@ Length: **800–2000 words.** Shorter for narrow topics; longer for broader ones
 
 ## What goes in
 
-Four kinds of content earn their place in the synthesis.
+Six kinds of content earn their place in the synthesis.
 
 ### Principles or framework
 
 The conceptual structure the curator sees in the domain. Not a definition list — a framework. "Good CLI design rests on four pillars: predictable command shape, humane errors, useful defaults, and machine-readable output." That framework, once articulated, shapes how the AI reads every source in the corpus.
 
+### Generative rules
+
+The rules the consuming AI should apply when it is making decisions with the mixtape. Include a `## Generative rules` section with about five imperatives. These are not summaries of sources; they are portable constraints the AI can carry into new work.
+
+Example: "Channel discipline: stdout is for data, stderr is for humans, and exit codes mean what they say." A rule like this resolves dozens of downstream questions without the AI needing to re-open every source.
+
+### Stances this corpus takes
+
+The opinionated positions the mixtape wants to preserve. Include a `## Stances this corpus takes` section that names what the corpus leans toward, what it resists, and where a dissenting source should temper the rule.
+
+This is different from the contested-questions section. Contested questions name the debate; stances state the operating answer this mixtape chooses for its JTBD.
+
 ### Contested questions
 
 Where credible practitioners disagree, name the disagreement and where the curator stands. "There's an ongoing argument about whether CLIs should mirror existing tool conventions or break them deliberately when the underlying behaviour differs. This mixtape leans toward mirroring; sources 7 and 12 represent the dissenting view."
@@ -74,9 +86,11 @@ A typical synthesis runs:
 
 1. **Opening framing** (1–2 paragraphs). What this domain is fundamentally about. The frame the curator uses to organize their understanding. Not a definition — a stance.
 2. **The framework or principles** (2–4 paragraphs). The structure the curator sees. Named, not just described.
-3. **Contested questions** (1–3 paragraphs). Where credible practitioners disagree. Where the curator stands.
-4. **Important distinctions** (1–2 paragraphs). Concepts the AI is likely to conflate without correction.
-5. **Scope and limits** (1 short paragraph). What this mixtape covers and what it doesn't.
+3. **Generative rules** (`## Generative rules`, about five imperatives). The small set of rules the consuming AI should remember and apply.
+4. **Stances this corpus takes** (`## Stances this corpus takes`, 1–3 paragraphs or bullets). The opinionated positions and trade-offs this mixtape adopts.
+5. **Contested questions** (1–3 paragraphs). Where credible practitioners disagree. Where the curator stands.
+6. **Important distinctions** (1–2 paragraphs). Concepts the AI is likely to conflate without correction.
+7. **Scope and limits** (1 short paragraph). What this mixtape covers and what it doesn't.
 
 This is a default. Vary it when the topic warrants — some domains lead with contested questions, some with distinctions, some with a different opening move. The structure serves the content.
 
@@ -130,4 +144,4 @@ If the synthesis names source numbers ("Source 1 argues..."), it's probably synt
 
 Plain markdown. No front matter. Begins with a top-level heading that matches the mixtape title (e.g., `# Mobile Design Foundations — Synthesis`). The full file gets included verbatim at the top of `MIXTAPE.md` by `liner compile`.
 
-Write the synthesis to `synthesis.md` in the project folder. Show the curator the result before declaring Phase 6 complete.
+Write the synthesis to `synthesis.md` in the corpus folder (`mixtape/synthesis.md` in v2 projects). Show the curator the result before declaring Phase 6 complete.