linersh 0.5.7 → 1.0.1

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.