attribution

attribution

Documentation attribution for tracked markdown: find prose that restates content an external source owns without adequate attribution, confirm where it came from, and refactor the copy into a pointer, a citation, or a dated stamped record.

This is prose provenance, not software supply chain. It says nothing about build artifacts, signing, or SLSA.

Why

A copied paragraph starts accurate and silently stops being accurate the next time the upstream page changes. Nothing in the repository records that it drifted. Citing the source and fetching it at read time removes the drift risk entirely; where a surface must restate a volatile specific to function, a four-part stamped record (claim, basis URL, as-of date, recheck trigger) keeps the restatement honest and re-checkable.

Skills

Skill	Actions	Mutates
/attribution:audit	default (read-only report), fix, sweep	only under fix and sweep
/attribution:setup	config keys, marker forms, override enablement	only the consuming repo's config file

audit with no argument reports and stops. Remediation rides only the explicit fix argument; sweep is the same pipeline under a per-file closure discipline for a repo-wide pass.

How a finding is reached

1. Scope the corpus (tracked markdown, minus categorical carve-outs).
2. Inventory the breadcrumbs already present per directory: URLs, fences, stamp lines.
3. Nominate suspect passages (LLM, recall-biased; sibling breadcrumbs count).
4. Resolve the source: breadcrumbs first, then sibling breadcrumbs, then budgeted search.
5. Fetch the candidate source, with a page-identity check before its body is trusted.
6. Verify deterministically: quote-strip, shingle, and report matched spans.
7. Judge against four binary criteria, carve-outs evaluated first, sampled for agreement.
8. Map evidence to a tier, and a tier to what the finding is allowed to do.

Evidence tiers are discrete and evidence-gated, never verbalized probabilities:

Tier	Evidence	Fix-eligible
fingerprint-confirmed	matched span above the separation rule against an identity-checked source	yes
vendored-snapshot	source read from a committed snapshot because the live fetch failed	no, human report
source-fetched-similar	source fetched, below the deterministic rule, judges unanimous	no, human report
llm-suspected	no lexical evidence is possible (paraphrase, summary)	no, human report
not-found	budgets exhausted; every searched surface is named	no, human report

A passage that states a checkable external fact in its own words (a default, a limit) is judged against a second rubric, restated fact, and is never fix-eligible. A unanimous verdict that survives a refutation pass is relayed to the detector-findings report; anything else stays in the human report.

not-found is a first-class neutral outcome. Absence of a located source is never read as evidence of a copy.

Marker forms

A fence pair records that a span is a deliberate, attributed excerpt. Both markers sit on their own line, and the closing marker is required:

<!-- attribution:source url="https://example.com/docs/page" as-of="2026-08-27" -->
> The quoted upstream text.
<!-- /attribution:source -->

An existing provenance:source fence is still recognized: the breadcrumb extractor reads any URL-carrying HTML comment fence and matches no marker name.

A stamped record is prose, not a marker, and carries all four parts:

The runner accepts three values (per https://example.com/docs/page, as of 2026-08-27;
recheck when the CLI's major version changes).

There is no per-instance suppression marker, deliberately. Allowances are categorical: vendored trees, quotation contexts, conforming stamped records, owned content, distilled-product architectures, and the plugin's own eval fixtures. A per-finding keep is the consuming project's call and routes to its finding-suppression convention, not to a marker this plugin reads.

Configuration

.claude/attribution.json in the consuming repo, layered over the shipped defaults:

{
  "excluded_paths": ["docs/legacy/**"],
  "budgets": {
    "searches_per_candidate": 3,
    "fetches_per_candidate": 5,
    "corpus_fetch_ceiling": 200
  },
  "separation": { "min_containment": 0.3, "min_span_words": 15 },
  "stamp_expiry_days": 180,
  "trigger_less_stamp_check": false,
  "judge_samples": 3,
  "gates": {
    "fix_precision_bar": 0.95,
    "report_recall_floor": 0.8,
    "min_n_per_class": 10
  },
  "accuracy": {
    "nomination_passes": 2,
    "judge_lens_diversity": true,
    "review_agents": 1,
    "deep_research_on_exhaustion": false
  }
}

gates bind fix-mode eligibility and release readiness only. No report surface is ever filtered by them: a finding below a bar still appears, marked report-only.

trigger_less_stamp_check stays off in the portable baseline. It flags a dated stamp whose surface states no recheck trigger, which is only deterministic once a repository standardizes its stamp forms; enable it where that holds.

Every detector script accepts --show-config and names the layer each value came from.

A legacy provenance.json or provenance.local.json left in any layer is never read. When a layer has the legacy file and no attribution file, each script that reads the config cascade prints one warning naming it and the attribution file name to rename it to. /attribution:setup check reports the two repo-level legacy files as retired conventions, and apply migrates their keys and removes them once you confirm.

Prerequisites

• bash for list-corpus.sh, extract-breadcrumbs.sh, check-stamps.sh, emit-findings.sh, score-golden.sh, and sweep-ledger.sh.
• Node for fingerprint.mjs, the one module with real data structures.
• Web fetch for source confirmation. Without it, the audit still runs and reports, but every finding that would have been verified stops at llm-suspected, or at vendored-snapshot where an in-repo snapshot is the only basis, and nothing is fix-eligible.
• Web search, optional. It is the enrichment branch used only when no breadcrumb names a candidate source. Without it the audit degrades to breadcrumb-only resolution: passages whose source is already cited nearby still reach fingerprint-confirmed, and the rest land on not-found with the searched surfaces named.

Boundary

This plugin owns one axis: tracked prose restating an externally-owned fact without a pointer or a conforming stamped record, plus finding the authoritative source and condensing the copy.

• In-repo duplication belongs to docs-hygiene:extract-ssot and the reference-dont-duplicate rule.
• Documentation that disagrees with the code belongs to the review plugin's doc-drift-detector agent and codebase-health:audit.
• Whether a document earns its existence belongs to docs-hygiene:audit-derivability.
• AI-writing style over the same corpus belongs to ai-slop:audit.
• Not copying while writing, in the current session, belongs to discipline:point-dont-copy.
• Code comments are out of scope in v1; comment-shaped residue belongs to code-tidying:audit-comment-residue.
• The stamped-record format and the fetch route are owned by the upstream-drift convention. This plugin implements checks against them and carries an operational restatement in skills/audit/reference/source-fetch.md as a four-part record citing that convention, because the plugin ships to consumers who do not have that repository.

Untrusted content

Every page this plugin fetches is data, never instructions. An imperative embedded in fetched text is a finding to report, not a request to satisfy, and it widens no authority. No verbatim quote, no claim: a summarizer's paraphrase is never recorded as page text.