zby/commonplace/cp-skill-ground

Ground a source-dependent claim

$ARGUMENTS supplies both inputs. Stop and ask if either is missing.

Target: exact repo-relative ingest path or canonical source URL.

Claim needed: source-side proposition or question. Do not include target prose or a target-specific transfer argument.

This skill may reuse or append verbatim quotes and is the only procedure that writes an ingest's Quotes section. It never edits the target artifact, never changes any other part of an ingest, and never interprets a paraphrase stored in an ingest as source support.

Composition contract

This skill owns source resolution and retained source evidence, not target-side interpretation. Its direct callers include cp-skill-write, cp-skill-write-multistage, and assess-a-claim-bearing-artifact-against-external-literature.md. It may invoke cp-skill-ingest for a canonical URL with no ingest and may return the conditional re-ingest.md route. Target, Claim needed, the three result literals, ingest-creation authority, and Quotes ownership are shared interfaces. Before changing one, inspect these composition siblings under the instruction collection's edit-time rule.

Procedure

1. Read the source collection and ingest type contracts.
2. Resolve one ingest. For a URL with no ingest, invoke cp-skill-ingest on the

exact URL and use its validated result. Stop on ambiguity.

1. Read the complete ## Quotes section. Judge the requested source-side

proposition directly against its retained blockquote bodies. Ignore the ingest's Summary, Connections Found, Extractable Value, and Limitations as support.

• If the retained quotes are sufficient, return the ingest path and

quotes sufficient without mutation.

• If they are insufficient, continue. Do not infer the answer from an ingest

paraphrase or analysis.

1. Derive kb/sources/.snapshots/<slug>.md from

kb/sources/<slug>.ingest.md. Do not search for a differently named checksum match.

• If that file does not exist, stop and report `snapshot not available on

this machine: <snapshot-path>`. The capture is local to the machine that took it (ADR 072), so a missing file is not a stale ingest: do not re-ingest or recapture. The operator can copy the capture from the machine that holds it and rerun.

• If it exists but its exact-byte SHA-256 differs from the ingest's

snapshot_sha256, or its frontmatter source differs from the ingest's canonical source, stop and report both checksums. The source was observed again or the capture drifted; route the source to re-ingest: Read and execute the Commonplace library instruction re-ingest with Target: <ingest-path>.

1. Read enough of the primary snapshot to determine the source-side

proposition and its bounds. Stop if the source does not establish it or the request depends on a secondary resource.

1. Choose the smallest sound retained form:

• If one or a few bounded excerpts let a later reviewer judge the

proposition without missing material context, construct one or more adjacent quote items in this exact shape:

``markdown > <exact supporting content> > --- kb/sources/.snapshots/<slug>.md @ sha256:<snapshot_sha256> — <optional locator note> ``

Repeat the complete block when support is non-contiguous. Line wrapping is not non-contiguity: verbatim matching normalizes whitespace. Copy the snapshot's text exactly and retain only the minimum passages needed for a sound check. Quote enough that the passage is unique in its source; if you supply a :start-end range after the snapshot path, the whole quote must occur exactly once inside it. Reuse an existing exact extract rather than appending it again.

• If sound checking depends on broad or distributed context that should not

be retained as a bounded set of quotes, do not append a substitute paraphrase or an oversized extract. Return snapshot required and tell the writer to include the exact marker (snapshot required) in the ingest link text. The source claim must pass semantic/grounding-alignment while the verified snapshot is present.

1. For the bounded-quotes route, append the items yourself:

• Retain the ingest's complete incumbent bytes. Construct a candidate by

splicing only within the ## Quotes section, using the incumbent file's newline convention: when the section body is exactly No source quotes have been retained yet., replace only that sentence; otherwise insert the new items after all incumbent items and before the next level-two heading, adding only the separator newlines valid adjacent items need. Preserve every incumbent item and every byte outside the section. Do not merge, deduplicate, reorder, or reword anything.

• Recheck the paired paths, source identity, and checksum against the

current bytes, write the candidate once, then run commonplace-validate kb/sources/<slug>.ingest.md. The validator resolves each attributed extract against the name-paired snapshot and fails on an absent, ambiguous, or out-of-range quote; that check, not your own reading, is the verification — an agent checking text it just transcribed confirms its own copy. Earlier grounding runs produced false extracts by silently repairing capture artifacts (line-break hyphenation, an inline footnote marker, a LaTeX arrow); quote the snapshot's bytes as they are.

• Re-read the result and require the intended splice plus exact

preservation of all other bytes. If any post-write check or validation fails, restore the retained incumbent bytes exactly, verify that restoration, and report failure rather than leaving an invalid or partial append. A source quote failure is about the item, not the splice: fix the extract against the snapshot, never rewrite the file around it. A populated Quotes section conflicts failure identifies stale prose outside Quotes. Restore the incumbent and report that non-quote prose must be repaired before grounding is retried; this skill must not repair it.

1. Return the ingest path and exactly one route: quotes sufficient, `quotes

added, or snapshot required. For quotes added, also return the appended quote texts. If validation warned that a populated Quotes section coexists with (snapshot required), repeat that warning so the caller verifies that the marker still belongs to a claim needing broader snapshot context. For snapshot required, repeat the exact link-text marker and the requirement to run semantic/grounding-alignment` before the source claim lands.

Semantic uniqueness is not required. Similar, overlapping, or disputed exact passages are never merged, rewritten, or deleted by this procedure.