linersh 1.0.2 → 1.1.0

package/README.md

@@ -26,12 +26,37 @@ liner
 ```
 
 With no arguments, `liner` launches the Go TUI. CLI subcommands such as
-`liner compile`, `liner share`, `liner import`, `liner status`, and
-`liner setup-js` pass through to the Python core. If you are using one-shot
+`liner compile`, `liner share`, `liner import`, `liner project`,
+`liner sources`, `liner adapters`, `liner status`, and `liner setup-js` pass
+through to the Python core. If you are using one-shot
 `npx` instead of a global install, pass subcommands through the package:
 `npx --yes linersh@latest setup-js` or
 `npx --yes linersh@latest uninstall --yes`.
 
+## Safe Project Maintenance
+
+The installed CLI is the authority for supported Project and Source changes.
+Inspection and planning are write-free; apply revalidates one exact versioned
+Change Set and writes a durable, redacted Change Receipt.
+
+```sh
+liner project guidance <project> --format markdown
+liner project inspect <project> --json
+liner sources add <project> --type web --url <url> --note <note>
+liner project rename <project> --name <name>
+```
+
+The Go TUI's `Maintain project` command uses the same contract. Optional Codex
+and Claude Maintenance Adapters are explicit CLI-delegating installations:
+
+```sh
+liner adapters inspect codex
+liner adapters install codex --yes
+```
+
+The Maintenance Adapter is not the Project Skill, and a `type: skill` Source is
+inert reference material rather than installed instructions.
+
 ## Try It Cleanly
 
 For a regular-user smoke test without touching your real Liner workspace:
@@ -50,12 +75,22 @@ rm -rf "$tmp"
 ```
 
 The second command opens the Go TUI. Create a test Liner Project, build the
-corpus with your configured local Claude or Codex runner, then run Create
-Operating Layer. Because `HOME`, the npm cache, and `LINER_DIR` all point inside
-`$tmp`, cleanup is just `rm -rf "$tmp"`.
+corpus with your configured OpenAI (Codex CLI) or Claude (Claude Code) runner,
+then run Create Operating Layer. Because `HOME`, the npm cache, and `LINER_DIR`
+all point inside `$tmp`, cleanup is just `rm -rf "$tmp"`.
 
 ## Run Locally
 
+For normal repository testing, use the isolated launch so Projects and Settings
+cannot write to the production Liner library or profile:
+
+```sh
+npm --prefix packages/tui run dev:isolated
+```
+
+See [../../docs/development.md](../../docs/development.md) for explicit
+authenticated provider-home options and the offline runner-preferences smoke.
+
 From the repo root:
 
 ```sh
@@ -98,6 +133,9 @@ Notes:
 - Release packaging is verified with `npm run acceptance:go -- release-smoke`,
   which packs a local platform package plus the main `linersh` package and
   installs both into a clean consumer project.
+- `npm run release:check` is offline and verifies repository consistency.
+  `npm run release:check:publish` additionally refuses to publish the main
+  package when its canonical version already exists on npm.
 
 ## Useful Environment Variables
 

package/bin/liner.js

@@ -19,6 +19,75 @@ const here = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(here, "..");
 const argv = process.argv.slice(2);
 
+const COMMAND_GROUPS = [
+  {
+    title: "Common workflow commands:",
+    commands: [
+      { name: "init", description: "Create a Liner Project", owner: "core" },
+      { name: "compile", description: "Build MIXTAPE.md from a Liner Project", owner: "core" },
+      { name: "share", description: "Create a shareable .mixtape file", owner: "core" },
+      {
+        name: "import",
+        description: "Import a .mixtape file as a Liner Project",
+        owner: "core",
+      },
+      { name: "list", description: "List Liner Projects", owner: "core" },
+      { name: "status", description: "Show Liner Project status", owner: "core" },
+      { name: "setup-js", description: "Set up JavaScript rendering support", owner: "core" },
+      { name: "uninstall", description: "Remove local Liner state and caches", owner: "launcher" },
+      {
+        name: "--version",
+        description: "Show installed launcher and core versions (-v)",
+        owner: "launcher",
+      },
+    ],
+  },
+  {
+    title: "Advanced maintenance commands:",
+    commands: [
+      {
+        name: "replay",
+        description: "Clone project inputs with lineage for later comparison",
+        owner: "core",
+      },
+      { name: "clone", description: "Fetch or copy a project recipe", owner: "core" },
+      {
+        name: "skills",
+        description: "Find installed skills that can be used as Sources",
+        owner: "core",
+      },
+      {
+        name: "sources",
+        description: "Plan and apply Source maintenance",
+        owner: "core",
+      },
+      {
+        name: "adapters",
+        description: "Manage optional Maintenance Adapters",
+        owner: "core",
+      },
+      {
+        name: "project",
+        description: "Inspect, plan, and apply Project maintenance",
+        owner: "core",
+      },
+      { name: "cache", description: "Inspect or clear the Source cache", owner: "core" },
+      { name: "manifest", description: "Build or inspect a Source manifest", owner: "core" },
+    ],
+  },
+];
+
+const CLI_COMMANDS = new Set(
+  COMMAND_GROUPS.flatMap((group) =>
+    group.commands.filter((command) => command.owner === "core").map((command) => command.name),
+  ),
+);
+
+if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) {
+  printHelp();
+  process.exit(0);
+}
+
 // `liner --version` used to forward straight to the Python core, so it
 // reported the core version (e.g. 0.5.0) regardless of which TUI package was
 // installed — confusing when verifying an npm publish. Report the npm/TUI
@@ -34,25 +103,10 @@ if (argv[0] === "uninstall") {
   process.exit(code);
 }
 
-const CLI_COMMANDS = new Set([
-  "init",
-  "replay",
-  "compile",
-  "share",
-  "import",
-  "clone",
-  "setup-js",
-  "list",
-  "skills",
-  "cache",
-  "manifest",
-  "status",
-]);
-
 function wantsCli(args) {
   if (args.length === 0) return false;
   const first = args[0];
-  return first === "--help" || first === "--version" || first === "-h" || CLI_COMMANDS.has(first);
+  return first === "--version" || CLI_COMMANDS.has(first);
 }
 
 if (wantsCli(argv)) {
@@ -345,6 +399,33 @@ function readTuiVersion() {
   }
 }
 
+function printHelp() {
+  const lines = [
+    "Liner — build and use source-grounded Liner Projects.",
+    "",
+    "Usage:",
+    "  liner                         Open the Go TUI",
+    "  liner <command> [options]     Run a command",
+    "",
+    "liner with no arguments opens the Go TUI.",
+    "Run `liner <command> --help` for detailed command help.",
+    "",
+  ];
+  for (const group of COMMAND_GROUPS) {
+    lines.push(group.title);
+    for (const command of group.commands) {
+      lines.push(`  ${command.name.padEnd(10)} ${command.description}`);
+    }
+    lines.push("");
+  }
+  lines.push(
+    "Options:",
+    "  -h, --help     Show this help",
+    "  -v, --version  Show version information",
+  );
+  console.log(lines.join("\n"));
+}
+
 // Like resolveCliBinary() but non-fatal: returns null instead of exiting when
 // no core binary is found, so `--version` still prints the TUI version on a
 // host where the bundled core is missing (e.g. Windows pre-unblock).
@@ -355,7 +436,8 @@ function tryResolveCliCommand() {
 }
 
 function tryResolveHeadlessRunnerScript() {
-  return join(packageRoot, "dist", "agents", "headless-runner.js");
+  const candidate = join(packageRoot, "dist", "agents", "headless-runner.js");
+  return existsSync(candidate) ? candidate : null;
 }
 
 function printVersion() {

package/cli-update-docs/README.md

@@ -2,7 +2,10 @@
 
 This is the Liner methodology made executable by Claude or Codex. The bundle implements CURATION.md v2.0 as instructions to a running AI, drives the mixtape lifecycle from a task description to a project folder ready for `liner compile`, and supports both quick mode (the AI does most of the work, with lightweight gate review) and methodology mode (the curator engages substantively at every phase).
 
-It is one of Liner's surfaces, alongside the CLI, the TUI, the planned MCP server, and the planned web builder. The skill is the surface for Claude-Code-native and TUI-subprocess authoring. Methodology-mode curators can also use it directly when working in a Claude Code session.
+It is one of Liner's authoring surfaces, alongside the CLI and TUI. The skill is
+the surface for Claude-Code-native and TUI-subprocess curation. Methodology-mode
+curators can also use it directly when working in a Claude Code session. It is
+not the Project Skill or the optional Maintenance Adapter.
 
 ## Bundle contents
 
@@ -80,7 +83,22 @@ The bundle is functional and ships inside the npm TUI package so agent-backed ph
 
 The bundle still benefits from more worked examples in the companion files, but it is no longer blocked by the old "second pass before any shipping" constraint. Current product risk lives more in curation quality and fetcher edge cases than in basic skill availability.
 
-As of `linersh@1.0.0`, compilation is the corpus-ready milestone and Create Operating Layer is the project-complete milestone. A project can be "ready to use — compiled with warnings" when `MIXTAPE.md` is written but some sources are missing or soft-failed. The TUI opens the existing compile result for a completed mixtape and requires an explicit retry/re-run from that screen. Framing also has a validation contract: Phase 1 must produce a capability brief and required source roles before source discovery can proceed.
+In the local `1.1.0` release candidate, compilation is the Corpus Ready
+milestone and Create Operating Layer is the Project Complete milestone. A
+project can be usable when `MIXTAPE.md` is written but some Sources are missing
+or soft-failed after review. The TUI opens the existing compile result and
+requires an explicit retry or rerun. Phase 1 must produce a Capability Brief and
+Required source roles before discovery can proceed.
+
+## Three Skill Surfaces
+
+- The **curating-mixtapes skill** authors the initial corpus recipe, synthesis,
+  and working notes. It never performs post-creation maintenance.
+- The root **Project Skill** is created by the Operating Layer and teaches future
+  sessions how to use one completed Project.
+- The optional **Maintenance Adapter** is installed explicitly for Codex or
+  Claude and delegates supported changes to the installed CLI's current
+  guidance. A `type: skill` Source remains inert evidence and is not installed.
 
 ## Versioning
 
@@ -98,7 +116,9 @@ The skill is the methodology made executable. It sits alongside Liner's other su
 
 **CURATION.md** is the methodology described to humans. The skill bundle implements it for an AI executor. The two are paired artifacts that update together when the methodology changes substantively.
 
-**The Liner CLI** runs `liner compile` against the project folder this skill produces. The skill never compiles; the CLI never authors. Clean split.
+**The Liner CLI** runs `liner compile` against the project folder this skill
+produces and owns supported post-creation maintenance. The curation skill never
+compiles and never bypasses the Core maintenance contract.
 
 **The Liner TUI** invokes this skill internally for agent-backed authoring via the local Claude or Codex CLI. Same methodology, different UX.
 

package/cli-update-docs/SKILL.md

@@ -9,6 +9,11 @@ This skill implements the Liner curation methodology (CURATION.md v2.0). A mixta
 
 The output of this skill is a project folder ready for `liner compile`. The skill does not compile.
 
+This is an initial curation surface, not a maintenance writer. After a Liner
+Project has identity-bearing Project or Source state, supported changes must go
+through the installed CLI's current `liner project guidance` contract. Do not
+use this skill to edit canonical Project files as a maintenance shortcut.
+
 **Runtime requirement:** this skill assumes filesystem access. It reads companion files from its own directory at specific phases and writes artifacts to a project folder. Designed for execution inside Claude Code or as a subprocess driven by the Liner TUI. Not designed for pure-chat use.
 
 ## Terminology — get these right
@@ -83,6 +88,8 @@ Your job in Phase 1 is to translate that plain-language goal into a Capability B
 - source requirements and exclusions,
 - runtime behavior for the future agent, including when it should ask the user clarifying questions.
 
+Use these exact level-three headings inside the Capability Brief so the Operating Layer can promote the contract reliably: `### Reusable AI capability`, `### Exact runtime output contract`, `### Internal job-to-be-done`, `### Inferred research lanes`, `### Required source roles`, `### Source exclusions`, and `### Runtime autonomy, abstention, and escalation`.
+
 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.
@@ -202,9 +209,12 @@ Order sources within each section by importance (most important first). Order se
 - `version: 1`
 - `mode` is `quick` or `methodology`
 - `sources` is non-empty
-- Every source has `type` and `url`
-- Every `type` is `youtube` or `web`
-- Every `url` parses
+- Every source has `type`, `note`, and `section`
+- Every `type` is `youtube`, `web`, `local_file`, or `skill`
+- Every `youtube` or `web` source has a parseable `url`
+- Every `local_file` source has `path` and `citation`
+- Every local or installed `skill` Source has `path`; a remote skill Source has
+  a parseable `url`
 
 If validation fails, fix and re-check before showing the user.
 
@@ -261,6 +271,9 @@ Tell the user the folder is ready to compile with `liner compile <topic-slug>`.
 - **Does not run `liner compile`.** That's the user's call, with the user's tools.
 - **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 maintain an existing Liner Project.** Use Liner Core directly or
+  install the optional Maintenance Adapter, which delegates to
+  `liner project guidance`.
 - **Does not publish to the library.** Library contributions happen via PR to the Liner repo, in methodology mode, after passing the empirical test.
 
 ## Common failure modes

package/cli-update-docs/curator-notes.md

@@ -72,13 +72,14 @@ In both modes, notes are required. A source without a note doesn't ship.
 
 ## Worked examples
 
-> TODO: Insert three to five worked examples from the Cowork CLI/TUI synthesis. Each should show all three things landed. Look for notes in the Cowork material that are concrete about role, location of value, and limitations — not vague praise.
->
-> Suggested examples to pull:
-> - A "watch first" foundational note (likely on a Van Slyck talk or clig.dev)
-> - A note with specific time-coding on a video ("the section starting at 14:30")
-> - A trim note that explicitly says what to skip ("Skip the OpenStack-specific noise")
-> - A "contested counterpoint" note that names the source it disagrees with
-> - A note that names a temporal limitation ("dated on X, durable on Y")
-
-> TODO: Insert one or two examples of bad notes for contrast. Pull the original AI-drafted notes from OpenClaw if they're available — those are the canonical "this is a useful resource" generic notes that Cowork rewrote.
+Good notes:
+
+- "Watch first for the operating model: the middle section names the workflow constraint this corpus adopts. Dated on tool names, durable on the interaction principle."
+- "Use as the counterpoint to the default stance. Strong on risks and failure modes; do not treat it as the corpus's main recommendation."
+- "Skim the setup and use the worked example section. It shows the output bar, but the implementation details are platform-specific."
+
+Bad notes:
+
+- "Useful overview of the topic."
+- "Highly recommended resource."
+- "Good background reading."

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

@@ -90,8 +90,6 @@ If yes, keep the better one and cut the other. Volume is not a virtue. Five exce
 
 Redundancy is different from coverage. Two sources covering the same topic from different angles or with different evidence is coverage, not redundancy. The test is whether the AI would generate meaningfully different output with both vs. with only one. If not, redundant.
 
-> TODO: Insert a worked example from the Cowork synthesis where two sources were collapsed because of redundancy. The Van Slyck talk appearing in transcripts 02 and 03 is a known case — same talk uploaded twice. Show how the redundancy was named and resolved.
-
 ---
 
 ## Test 2 — The coverage test
@@ -107,8 +105,6 @@ A mixtape that silently omits a major area is worse than one that says explicitl
 
 If a section has sources but they're all rated 2 or 3, that's a weak-coverage signal — the section is technically populated but the sources aren't load-bearing. Either find stronger sources or note the weakness.
 
-> TODO: Insert a worked example. If the Cowork synthesis had a section that needed reinforcement after first-pass evaluation, show the coverage check that surfaced it and how the gap was addressed.
-
 ---
 
 ## Test 3 — The disagreement test
@@ -123,8 +119,6 @@ If the topic is genuinely uncontested — the W3C HTML spec, for example, isn't
 
 **The test in action:** identify the strongest claim in the corpus. Search for "[claim] critique" or "[claim] is wrong" or "alternative to [claim]." If you find a credible critique you haven't included, you've found your dissenting source. Add it.
 
-> TODO: Insert a worked example from CLI/TUI research. The corpus probably had a contested-question moment — possibly around whether CLIs should follow Unix conventions strictly vs. break them deliberately, or around accessibility being assumed-by-default vs. explicitly designed-for. Surface the actual disagreement and how it was handled.
-
 ---
 
 ## Test 4 — The framing-gap test
@@ -189,8 +183,6 @@ The earlier loose version of this test failed quietly in practice. A real sessio
 
 If the framing gap is real, accept the cost of going back. Phase 2 is cheap relative to shipping a mixtape with a hole in it.
 
-> TODO: Insert the canonical worked example from the Cowork synthesis. OpenClaw's initial 50-source list was anchored in "CLI/TUI implementation" framing and missed "the entire wizard/form-design tradition (Form Design Patterns, NN/g articles, Tidwell, Cooper)." Cowork ran the framing-gap test, named the missing tradition, added 43 net-new sources, and reframed the corpus. This is the textbook framing-gap-test rescue. Pull the specific moment the gap was identified and the specific sources added.
-
 ---
 
 ## Test 5 — Source-kind balance
@@ -407,7 +399,7 @@ Don't paper over failures. The point of running the tests is to find problems wh
 - **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 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.
+- **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 user-provided Sources that could fill the gap 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.
 
@@ -431,8 +423,6 @@ user_can_add:
 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.
-
 ---
 
 ## A note on fresh attention

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

@@ -16,8 +16,6 @@ This tactic is the single highest-leverage move for discovering primary document
 
 **How to apply:** Open the most credible source you have. Scan the references, footnotes, or "further reading" section. Note every source that's cited *and* recurs in another credible source's references. Recurrence across multiple credible sources is the signal — it's how you find the references nobody links anymore.
 
-> TODO: Insert worked example from the Cowork CLI/TUI synthesis. Look for a moment in the research where citation-chasing surfaced a canonical source that didn't show up in any initial keyword search. Form Design Patterns by Adam Silver is a candidate — it's cited across multiple Phase 1 sources but didn't surface from "CLI wizard design" searches.
-
 ---
 
 ## 2. Reverse-engineer experts' reading lists
@@ -30,8 +28,6 @@ Are.na deserves a specific note: it's a network designed for visual and textual
 
 **How to apply:** Find three to five experts in the domain. Search each one's name plus "reading list" or "syllabus" or "references." Catalog what they recommend. Cross-reference with the candidates already on your long-list — overlaps are strong signal; uniques are leads.
 
-> TODO: Insert worked example from the Cowork CLI/TUI synthesis. Look for a tactical mention of an expert reading list that surfaced relevant work. If none exists, this section can use an example from a different domain — the methodology generalizes.
-
 ---
 
 ## 3. Mine course syllabi
@@ -49,8 +45,6 @@ University courses, bootcamp curricula, and serious online courses have already
 
 Course syllabi skew toward foundations. They're best for the early-section knowledge-map buckets. Recent practitioner work is rarely on them.
 
-> TODO: Insert worked example. If no syllabus surfaced in the CLI/TUI research, note this and use a hypothetical that's specific enough to be useful.
-
 ---
 
 ## 4. Find who experts cite
@@ -61,8 +55,6 @@ This tactic is structurally similar to citation-chasing (#1), but starts from pe
 
 **How to apply:** Identify three to five practitioners credible in the domain. Open their most recent significant work. Note the sources they cite. Open the sources cited by two or more practitioners. Those are your high-priority candidates.
 
-> TODO: Insert worked example from CLI/TUI research. Carolyn Van Slyck, Aanand Prasad (clig.dev), Will McGugan (Textualize), and Amanda Pinsker (GitHub CLI) are candidates whose citation patterns could be traced.
-
 ---
 
 ## 5. Conference proceedings
@@ -73,8 +65,6 @@ Going through three years of a specific conference is more efficient than topic-
 
 Conference talks vary widely in density. The same talk reposted across multiple conferences is one signal of substance. Talks from speakers who are also cited by other practitioners (tactic #4) are another.
 
-> TODO: Insert worked example. The CLI/TUI corpus has multiple Van Slyck talks across GopherCon and other venues — a real example of how conference-proceeding mining surfaced both her work and what to keep when the same talk appears at multiple conferences.
-
 ---
 
 ## 6. Ask the AI to find gaps, not sources
@@ -87,8 +77,6 @@ AI is bad at recall — at remembering and surfacing sources you don't know abou
 
 This tactic is structurally related to the framing-gap test in Phase 5, but earlier and lower-stakes. Doing it in Phase 2 is cheaper than discovering the gap in Phase 5 and having to backtrack.
 
-> TODO: Insert worked example from the Cowork synthesis. The Cowork run discovered that OpenClaw's initial 50-source list missed "the entire wizard/form-design tradition (Form Design Patterns, NN/g articles, Tidwell, Cooper)" — this is the canonical example of gap-finding working. Pull the specific moment where the gap was named and how it changed the candidate pool.
-
 ---
 
 ## 7. Search for the core action and the curator anchors

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

@@ -171,8 +171,6 @@ Drop unless the source encodes a genuinely transferable pattern. A Ratatui tutor
 
 A source flagged as "low-value" during candidate discovery (Phase 2) sometimes turns out to be the only one that addresses a specific gap once you've actually read every candidate. If a low-priority source uniquely covers a knowledge-map section that would otherwise be empty or thin, rescue it. Mark the decision and the rationale clearly.
 
-> TODO: Insert worked example from the Cowork CLI/TUI synthesis. The canonical example is the Caligula segment inside transcript #34 "some cool Linux programs you've never seen" — OpenClaw flagged it as lower-value, Cowork rescued it as "the closest direct precedent in your whole corpus." This is the textbook rescue move. Pull the specific decision and the rationale used.
-
 ### Author overrepresentation
 
 Three of five sources in a section are by the same author. This narrows perspective and reduces the AI's ability to synthesize across views. Keep the single strongest piece by that author; replace the others with sources by different practitioners. The exception: if the author has genuinely written the canonical work in multiple sub-areas, and no other practitioner has equivalent work, keeping multiple pieces is justified — but you should be able to defend it.
@@ -209,5 +207,3 @@ candidates:
 ```
 
 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.
-
-> TODO: Insert two or three worked evaluation entries pulled from the Cowork synthesis — one keep with rating 5, one trim with rating 3, one drop with a specific rationale. These are the highest-leverage examples in the file.

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

@@ -134,9 +134,13 @@ If the synthesis names source numbers ("Source 1 argues..."), it's probably synt
 
 ## Worked examples
 
-> TODO: Insert two worked synthesis excerpts from the Cowork CLI/TUI synthesis. The full Cowork document is the longest worked example available — pull the opening framing paragraphs as one example, and a contested-question or distinction paragraph as another.
+Good synthesis shape:
 
-> TODO: Insert one example of synthesis-as-recap (bad) for contrast. Either invent one against the CLI/TUI material or pull an earlier draft if one exists. The bad example should make the difference between "describing sources" and "framing a domain" obvious at a glance.
+> This corpus treats onboarding as a trust-building sequence, not as a checklist. The useful question is not "which screens does the user see?" but "what does each step prove before asking for the next commitment?" Sources disagree on how much explanation belongs up front, but they converge on one rule: every prompt should reduce uncertainty before it increases work.
+
+Bad synthesis-as-recap shape:
+
+> Source 1 explains onboarding screens. Source 2 covers empty states. Source 3 discusses progressive disclosure. Together, these sources show that onboarding is important.
 
 ---
 

package/dist/agents/artifact-validation.js

@@ -16,11 +16,20 @@ export function validatePhaseArtifact(project, phaseId) {
         case "candidates":
             return validateCandidateLonglist(join(project, "working/02-candidate-longlist.md"));
         case "evaluation":
-            return validateEvaluation(join(project, "working/03-evaluation.yaml"), {
-                expectedCandidateCount: countCandidateUrlsFromLonglist(join(project, "working/02-candidate-longlist.md")),
-            });
-        case "quality":
-            return validateQualityChecks(join(project, "working/04-quality-checks.md"));
+            return validateProjectEvaluation(project);
+        case "quality": {
+            const quality = validateQualityChecks(join(project, "working/04-quality-checks.md"));
+            if (!quality.ok)
+                return quality;
+            const evaluation = validateProjectEvaluation(project);
+            if (!evaluation.ok) {
+                return {
+                    ok: false,
+                    message: `working/03-evaluation.yaml is invalid after quality checks: ${evaluation.message}`,
+                };
+            }
+            return quality;
+        }
         case "synthesis":
             return validateSynthesis(join(project, "synthesis.md"));
         case "assembly":
@@ -29,10 +38,65 @@ export function validatePhaseArtifact(project, phaseId) {
                 evaluationPath: join(project, "working/03-evaluation.yaml"),
                 sourceManifestPath: join(project, "local-sources/sources-manifest.yaml"),
             });
+        case "improvement":
+            return validateImprovementDelta(join(project, ".liner-runs/improvement/delta.yaml"));
         default:
             return { ok: true };
     }
 }
+function validateProjectEvaluation(project) {
+    return validateEvaluation(join(project, "working/03-evaluation.yaml"), {
+        expectedCandidateCount: countCandidateUrlsFromLonglist(join(project, "working/02-candidate-longlist.md")),
+    });
+}
+export function validateImprovementDelta(path) {
+    const parsed = parseYaml(path, "improvement delta");
+    if (!parsed.ok)
+        return parsed;
+    if (!isRecord(parsed.value)) {
+        return { ok: false, message: ".liner-runs/improvement/delta.yaml is not a YAML mapping" };
+    }
+    if (stringField(parsed.value, "contract") !== "liner.improvement_delta" || parsed.value["version"] !== 1) {
+        return { ok: false, message: ".liner-runs/improvement/delta.yaml has an unsupported contract or version" };
+    }
+    if (!stringField(parsed.value, "summary")) {
+        return { ok: false, message: ".liner-runs/improvement/delta.yaml summary is required" };
+    }
+    const removals = parsed.value["removals"];
+    const replacements = parsed.value["replacements"];
+    if (!Array.isArray(removals) || removals.length !== 0 || !Array.isArray(replacements) || replacements.length !== 0) {
+        return { ok: false, message: "Improve Corpus requires separate explicit curator intent for removals or replacements" };
+    }
+    const additions = parsed.value["additions"];
+    if (!Array.isArray(additions) || additions.length === 0) {
+        return { ok: false, message: ".liner-runs/improvement/delta.yaml must contain at least one focused addition" };
+    }
+    for (let i = 0; i < additions.length; i++) {
+        const source = additions[i];
+        if (!isRecord(source)) {
+            return { ok: false, message: `.liner-runs/improvement/delta.yaml additions[${i}] is not a mapping` };
+        }
+        const type = stringField(source, "type");
+        if (!SOURCE_TYPES.has(type)) {
+            return { ok: false, message: `.liner-runs/improvement/delta.yaml additions[${i}].type is invalid: ${type || "(empty)"}` };
+        }
+        if ((type === "web" || type === "youtube") && !stringField(source, "url")) {
+            return { ok: false, message: `.liner-runs/improvement/delta.yaml additions[${i}].url is required` };
+        }
+        if (type === "local_file" && !stringField(source, "path")) {
+            return { ok: false, message: `.liner-runs/improvement/delta.yaml additions[${i}].path is required` };
+        }
+        if (type === "skill" && !stringField(source, "path") && !stringField(source, "url")) {
+            return { ok: false, message: `.liner-runs/improvement/delta.yaml additions[${i}] needs path or url` };
+        }
+        const priority = stringField(source, "priority");
+        const kind = stringField(source, "kind");
+        if (!PRIORITIES.has(priority) || !KINDS.has(kind)) {
+            return { ok: false, message: `.liner-runs/improvement/delta.yaml additions[${i}] needs valid priority and kind` };
+        }
+    }
+    return { ok: true };
+}
 export function validateCandidateLonglist(path) {
     if (!existsSync(path)) {
         return { ok: false, message: `${path} is missing` };