@ttsc/evidence 0.27.0 → 0.28.0

package/README.md

@@ -4,7 +4,7 @@
 
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/samchon/ttsc/blob/master/LICENSE) [![NPM Version](https://img.shields.io/npm/v/@ttsc/evidence.svg)](https://www.npmjs.com/package/@ttsc/evidence) [![NPM Downloads](https://img.shields.io/npm/dm/@ttsc/evidence.svg)](https://www.npmjs.com/package/@ttsc/evidence) [![Build Status](https://github.com/samchon/ttsc/actions/workflows/build.yml/badge.svg)](https://github.com/samchon/ttsc/actions/workflows/build.yml) [![Guide Documents](https://img.shields.io/badge/Guide-Documents-forestgreen)](https://ttsc.dev/docs/evidence) [![Discord Badge](https://img.shields.io/badge/discord-samchon-d91965?style=flat&labelColor=5866f2&logo=discord&logoColor=white&link=https://discord.gg/E94XhzrUCZ)](https://discord.gg/E94XhzrUCZ)
 
-Evidence Graph, your spec as a compile error no coding agent can skip.
+Evidence Graph turns every specification your agent skips into a compile error.
 
 ```tsx
 /**
@@ -19,7 +19,16 @@ Evidence Graph, your spec as a compile error no coding agent can skip.
 export function CouponStackingNotice(props: IProps): JSX.Element;
 ```
 
-`@evidence <target> <reason>` names one unit of the spec and why this declaration answers for it. A target is a document section, an API operation, a database schema model, or a TypeScript symbol as an inline link.
+`@evidence <target> <reason>`: what this code implements, and why.
+
+A target is one of four kinds:
+
+- **Markdown**: a file, or a section of one.
+- **Prisma**: a model, a column, or a relation.
+- **Swagger**: an operation, method and path together.
+- **TypeScript**: a type, a function, or a property, written as an inline link.
+
+Leave one uncited and the build stops.
 
 ```bash
 $ npx ttsc
@@ -27,41 +36,30 @@ error TS16411: [evidence/graph] Missing acknowledgement for 'docs/discount.md#co
   (Markdown H2 'Coupon Stacking' at docs/discount.md:3)
   in Claim 1 reference 1 (markdown, symbols: h2, h3).
 
-  Cite the artifact that answers for this unit with @evidence on a selected
-  typescript host, building that artifact first when none does, or write
-  @evidenceExclude on an eligible carrier when nothing here owes it. Never
-  leave an untrue tag standing just to pass this check; it removes the error,
-  not the problem.
-
-error TS16411: [evidence/graph] Missing acknowledgement for 'POST:/orders/{orderId}/coupons'
-  (Swagger operation 'POST /orders/{orderId}/coupons' at api/openapi.json)
-  in Claim 1 reference 2 (swagger operations).
-
-  Cite the artifact that answers for this unit with @evidence on a selected
-  typescript host, building that artifact first when none does, or write
-  @evidenceExclude on an eligible carrier when nothing here owes it. Never
-  leave an untrue tag standing just to pass this check; it removes the error,
-  not the problem.
-
-error TS16411: [evidence/graph] Missing acknowledgement for 'useCouponStacking'
-  (TypeScript function 'useCouponStacking' at src/lib/coupons/hooks.ts:12)
-  in Claim 1 reference 3 (typescript, symbols: function).
-
-  Cite the artifact that answers for this unit with @evidence on a selected
-  typescript host, building that artifact first when none does, or write
-  @evidenceExclude on an eligible carrier when nothing here owes it. Never
-  leave an untrue tag standing just to pass this check; it removes the error,
-  not the problem.
+...
 
 Found 3 errors.
 ```
 
-Without those tags, the build fails once per obligation, because one reference never covers another.
+One error per specification, in the same build as the type errors. The error list is the task list.
 
-An AI coding agent has to clear them to finish, and clearing them means citing each target and writing down why its code answers for it. Coverage reaches 100% on its own, as the residue of the errors it closed.
+## Benchmark
 
 ![Coverage and token spend across all four subjects](https://raw.githubusercontent.com/samchon/ttsc/gh-pages/benchmark/png/evidence-summary.png)
 
+One agent built each subject twice. Same inputs, same engine, same model; only this plugin differs.
+
+- **Plain**: omissions are invisible, so review hunts them.
+  - Read everything, fix every finding, restart until a round finds nothing.
+  - The loop until dry eats 90–95% of all tokens.
+  - Coverage still lands at 51.6–85.5%, falling as the subject grows.
+- **Evidence**: omissions are compile errors, so review reads the tag list.
+  - One pass, judging whether each reason is true.
+  - Review takes 15–41% of the tokens.
+  - Coverage lands at 100% on every subject.
+
+[The benchmark guide](https://ttsc.dev/docs/benchmark/evidence) breaks each run down by phase, and [`samchon/evidence-benchmark-results`](https://github.com/samchon/evidence-benchmark-results) keeps the raw sessions.
+
 ## Setup
 
 ### Install
@@ -71,7 +69,7 @@ npm install -D typescript ttsc @ttsc/lint
 npm install -D @ttsc/evidence
 ```
 
-This is a rule contributor to [`@ttsc/lint`](https://github.com/samchon/ttsc/tree/master/packages/lint) 0.22 or newer, so it runs on [`ttsc`](https://github.com/samchon/ttsc) rather than on stock `tsc` with ESLint.
+This is a rule contributor to [`@ttsc/lint`](https://github.com/samchon/ttsc/tree/master/packages/lint), so it runs on [`ttsc`](https://github.com/samchon/ttsc) rather than on stock `tsc` with ESLint.
 
 ### Configure
 
@@ -97,188 +95,103 @@ const graph: ITtscEvidenceGraphConfig = {
 
 export default {
   plugins: { evidence },
-  rules: { "evidence/graph": ["error", graph] },
+  rules: {
+    "evidence/graph": ["error", graph],
+    "evidence/review": "error",
+  },
 } satisfies ITtscLintConfig;
 ```
 
-One sentence: the components under `src` implement the docs, so every H2 and H3 under `docs` must be cited by a component. Violations arrive in the same stream as type errors, so there is no CI job to add.
-
-### Rules
-
-| Rule | Takes | What it does |
-| --- | --- | --- |
-| `evidence/graph` | [`ITtscEvidenceGraphConfig`](https://github.com/samchon/ttsc/blob/master/packages/evidence/src/structures/ITtscEvidenceGraphConfig.ts) | The graph itself. Project-scoped, so its entry declares no `files`. |
-| `evidence/documented` | [`ITtscEvidenceDocumentedConfig`](https://github.com/samchon/ttsc/blob/master/packages/evidence/src/structures/ITtscEvidenceDocumentedConfig.ts) | Requires a JSDoc block on every selected export, since a block is the only place a citation can live. Members count, so a class field, a method, a parameter property, and an interface member each need their own. `symbol` narrows the kinds; it defaults to all three. |
-| `evidence/singular` | nothing | Keeps one public identity per file, named after the file. |
-| `evidence/todo` | nothing | Fails on every remaining JSDoc `@todo`, with its own text. |
-| `evidence/review` | nothing | Requires an `@evidenceReview` beside every `@evidence` and an `@evidenceExcludeReview` beside every `@evidenceExclude`, naming the same target and stating what was checked. |
-
-Each takes `"error"`, `"warning"`, or `"off"`.
+One claim: the components under `src` implement the docs, so every H2 and H3 under `docs` must be cited by a component. Run `npx ttsc` and the error count is the backlog.
 
-## Claims and references
+[The rule reference](https://ttsc.dev/docs/evidence/rules) has four more rules beside `evidence/graph`, and [the claim reference](https://ttsc.dev/docs/evidence/claims) has every claim option.
 
-A claim is the population that owes a citation, a reference is what it owes, and every claim and reference pair is its own 100% obligation. Listing two references means both must be satisfied, and a citation toward one never counts toward the other. They all join the same `claims` array.
+### Checklists
 
-| Kind | Units | Claim | Reference | Cites in |
-| --- | --- | --- | --- | --- |
-| Markdown | file, H1 to H4 sections | yes | yes | an HTML comment |
-| Prisma | model, column, relation | yes | yes | a `///` comment |
-| TypeScript | types, functions, properties | yes | yes | JSDoc |
-| Swagger / OpenAPI | each operation under `paths` | no | yes | nothing, it cannot host a tag |
-
-Every population takes glob patterns in `files`, resolved against the `ttsc` project root. Add `root` to resolve against another directory instead, inside the project, above it, or absolute, which is how several packages in a monorepo share one requirements set and write the same citation.
-
-### Documents
+Coverage asks its question once per unit: has anyone cited this. Where a document is read down a column, such as development rules or a release gate, the question is whether each file answered each item.
 
 ```ts
-{
-  type: "markdown",
-  files: ["docs/requirements/**/*.md"],
-  reference: {
-    type: "markdown",
-    files: ["docs/meetings/**/*.md"],
-    symbol: ["h2", "h3"],
-  },
-}
+{ type: "markdown", files: ["docs/rules.md"], symbol: "h2", checklist: true }
 ```
 
-Markdown grounds Markdown, so a decision taken in a meeting and never written into the requirements fails the build. Deleting a requirement breaks every document that leaned on it, which is what stops a ghost spec from outliving its own source.
-
-```md
-## Coupon Stacking {#coupon-stacking}
+Every selected host then owes every item, and a file carrying no tag owes the whole list.
 
-<!-- @evidence docs/meetings/2026-01-12.md#discount-policy Carries the limit agreed in that meeting. -->
-```
+### Tags
 
-A citation sits in an HTML comment, so rendered prose stays clean, and a heading declares its own anchor with the `{#id}` suffix. A section citation sits under its heading; a whole-file citation sits at the top.
+The configuration is written once. The tags are written forever: `@evidence` cites, `@evidenceReview` verifies, and `@evidenceExclude` declines. [The tag reference](https://ttsc.dev/docs/evidence/tags) has the full grammar.
 
-### Database schema
+A false tag removes the error, not the problem. `@evidenceReview` resolves it:
 
 ```ts
-{
-  type: "prisma",
-  files: ["prisma/schema/**/*.prisma"],
-  symbol: "model",
-  reference: {
-    type: "markdown",
-    files: ["docs/requirements/**/*.md"],
-    symbol: "h2",
-  },
-}
-```
-
-Every model justifies itself against a requirement, so a table nobody asked for has nothing to cite. Reverse the pair to make a provider owe the model it reads.
-
-```prisma
-/// @evidence docs/requirements/pricing.md#discount-policy Discount columns exist for this policy.
-model Sale {
-  /// @evidence docs/requirements/pricing.md#coupon-stacking The stacking limit is stored here.
-  coupon_limit Int
-}
+/**
+ * @evidence docs/discount.md#coupon-stacking States the per-issuer limit.
+ * @evidenceReview docs/discount.md#coupon-stacking #a1b2c3d4e5f6
+ *                 Verified against policy section 3.
+ */
 ```
 
-A model is addressed as `prisma:Sale` and a member as `prisma:Sale.price`, never through the file it sits in, so moving a model between files cannot break a citation. Every matched file is parsed as one schema.
+- Reviews match the same declaration and target.
+- The fingerprint expires when the cited content changes.
 
-### API operations
+The compiler handles omissions. Humans handle falsehoods.
 
-```ts
-{
-  type: "typescript",
-  files: ["src/controllers/**/*.ts"],
-  reference: {
-    type: "swagger",
-    file: "https://raw.githubusercontent.com/samchon/shopping/refs/heads/master/packages/api/swagger.json",
-  },
-}
-```
+## Spec-Driven Development
 
-Each operation under `paths` is one obligation, so an operation the spec adds and nobody implemented is a compile error on the next build. The singular `file` names one local path or one `http:` URL, never a glob; use a `reference` array for several documents.
+Requirements are the handoff: whether a human or an AI wrote them, a human must review them last. That reviewed layer is the source of truth, the evidence the AI builds everything else from.
 
-An operation is cited as `POST:/orders`, one whitespace-free token, so the method and the path stay one target. Swagger grounds a claim and never makes one, because an operation has nowhere to host a tag.
+Each arrow is one claim from `lint.config.ts`, pointing at the evidence it cites.
 
-### Symbols
+<picture><source media="(prefers-color-scheme: dark)" srcset="https://ttsc.dev/evidence/documents-dark.svg"><img alt="Idea notes grounding Requirements and Specifications, which ground Implementation and Test" src="https://ttsc.dev/evidence/documents-light.svg" width="100%"></picture>
 
-```ts
-{
-  type: "typescript",
-  files: ["src/lib/*/hooks.ts"],
-  symbol: "function",
-  reference: {
-    type: "typescript",
-    package: "@ORGANIZATION/PROJECT-api",
-    files: ["src/functional/**/*.ts"],
-    symbol: ["function"],
-  },
-}
-```
+- Hand over the requirements, and the agent writes the rest.
+- Hand over raw idea notes, and it writes the requirements too.
 
-`files` selects modules and the population is what those modules publish, so a barrel carries in the surface it forwards. A `package` population is read from disk rather than from the program, because a symbol nothing imports is absent from the program and is exactly the one an obligation needs to name.
+The compiler checks everything below: a dropped idea or a skipped requirement is a compile error, so nothing vanishes on the way down.
 
-A unit is addressed the way a consumer reaches it, so `export * as functional` nests a segment and `export { A as B }` answers to `B`. Only TypeScript may cite TypeScript: `{@link}` resolves through the citing module's own imports, and no document has an import scope to resolve in.
+Even requirements cite their evidence, in comments, so the rendered document stays clean.
 
-### Symbol selectors
+Backend, frontend, and even novels below are this same shape, drawn in detail.
 
-`symbol` picks which units a reference materializes, and on a claim it restricts which declarations may host a tag.
+### Backend
 
-| Kind | Values | Default on a claim | Default on a reference |
-| --- | --- | --- | --- |
-| Markdown | `file`, `h1`, `h2`, `h3`, `h4` | all five | all five |
-| Prisma | `model`, `column`, `relation` | all three | `model` |
-| TypeScript | `type`, `function`, `property` | all three | `type` |
-| Swagger | none, every operation is selected | not applicable | every operation |
+<picture><source media="(prefers-color-scheme: dark)" srcset="https://ttsc.dev/evidence/backend-dark.svg"><img alt="Requirements and Specifications grounding DB schema, API operation, API schema and Test" src="https://ttsc.dev/evidence/backend-light.svg" width="100%"></picture>
 
-Units keep their hierarchy, so a target acknowledges itself and every selected descendant: citing a heading covers its subsections, an interface or a class covers the members it declares, and `prisma:Sale` covers the columns beneath it. An ancestor stays addressable even when its own kind is not selected.
+> Real config: [`api/lint.config.ts`](https://github.com/samchon/ttsc/blob/master/benchmarks/evidence/template/evidence/packages/api/lint.config.ts) and [`backend/test/lint.config.ts`](https://github.com/samchon/ttsc/blob/master/benchmarks/evidence/template/evidence/packages/backend/test/lint.config.ts)
 
-A class is a `type`, its methods are `function`, and its fields are `property`. A member written as a callable joins the methods instead: `handler = () => {}` and `charge: () => void` are both `function`. An interface and an object-shaped type alias are classified by the same rule, so `run(): void` on either is a `function` just as a class method is, and an overload run is one unit. The test is on how the member is written, not on what its type resolves to, because this rule reads no type checker, so `charge: Handler` stays a `property` even where `Handler` is an alias of `() => void`.
+The DB schema is Prisma, the rest is TypeScript, and one graph spans both:
 
-A class member that is `private` or `protected` materializes no unit, whichever syntax declared it. A constructor parameter carrying any property modifier declares a field, and it classifies exactly as the same field written in the class body would, so a `private` or `protected` one materializes nothing just as the body form does not. The property modifiers are TypeScript's own five: `public`, `protected`, `private`, `readonly`, and `override`. The last is the one to know about, because its meaning is about the base class rather than about the field, so it does not read as a field declaration. On a class extending one that declares `rate`, `constructor(override rate: number)` is a public instance field and a selected `property` unit.
+- The DB schema cites the documents; no table without a documented reason.
+- Operations and API schemas cite the DB layer and the documents behind it.
+- Tests cite the operations; an untested operation is an open obligation.
 
-A declaration whose documentation carries `@internal`, `@hidden`, or `@ignore` leaves the population entirely. It owes nothing and can carry nothing, and citing one is reported rather than silently ignored.
+### Frontend
 
-### Exclusions
+<picture><source media="(prefers-color-scheme: dark)" srcset="https://ttsc.dev/evidence/frontend-dark.svg"><img alt="Requirements and Specifications grounding Swagger, Hooks, Screens and Journeys" src="https://ttsc.dev/evidence/frontend-light.svg" width="100%"></picture>
 
-```md
-<!-- @evidenceExclude docs/requirements/pricing.md#coupon-stacking
-     This release ships a single coupon. Stacking waits for the settlement policy. -->
-```
+> Real config: [`frontend/lint.config.ts`](https://github.com/samchon/ttsc/blob/master/benchmarks/evidence/template/evidence/packages/frontend/lint.config.ts)
 
-`@evidenceExclude <target> <reason>` records that a claim intentionally does not use a scope. It follows the same hierarchy as `@evidence`, affects only the claim it is written in, and one obligation may exclude a scope only once.
+The source layer is the backend's own Swagger output: a graph can start from what another project publishes.
 
-It is the only acknowledgement that settles an obligation without anything being built, so it exists to be vetoed. "Not applicable" is a conclusion rather than a reason.
+- Hooks cite the operations they call.
+- Screens cite the hooks they render.
+- Journeys cite the screens they walk through.
 
-```ts
-{
-  type: "typescript",
-  files: ["src/components/**/*.tsx", "src/components/EXCLUSIONS.ts"],
-  evidenceExcludeCarriers: ["src/components/EXCLUSIONS.ts"],
-  symbol: "function",
-  reference: { type: "markdown", files: ["docs/**/*.md"], symbol: "h2" },
-}
-```
+Screens and journeys also cite the documents, so every screen traces back to a requirement.
 
-`evidenceExcludeCarriers` confines them to a named ledger. Scattered through the population, reading every exclusion means reading the population; gathered in one file it means opening one file. An exclusion written anywhere else is reported where it sits and discharges nothing.
+### Novels
 
-### Strict references
+<picture><source media="(prefers-color-scheme: dark)" srcset="https://ttsc.dev/evidence/novel-dark.svg"><img alt="Principles and Settings grounding Storylines, Scenarios and Manuscripts" src="https://ttsc.dev/evidence/novel-light.svg" width="100%"></picture>
 
-Ordinary coverage is permissive, which is right for a document several modules honor and too weak for a proof obligation, where one exclusion or one host citing everything discharges the whole population. Four properties tighten a single reference, and they never pool across references.
+> Real config: [`napoleon-imperator/lint.config.ts`](https://github.com/samchon/novels/blob/master/packages/napoleon-imperator/lint.config.ts)
 
-```ts
-{
-  type: "typescript",
-  package: "@ORGANIZATION/PROJECT-api",
-  files: ["src/functional/**/*.ts"],
-  symbol: ["function"],
-  noEvidenceExclude: true,
-  singleEvidencePerSymbol: true,
-}
-```
+The graph reads no meaning, only obligations and citations, so it works on any text. Humans review only the settings (characters, world rules, history), and the novel follows. The principles are universal literary fundamentals, not something written per work.
 
-- `noEvidenceExclude` refuses exclusions, so the target still owes positive evidence. A published accessor no hook consumes is an omission rather than a decision.
-- `uniqueEvidence` allows at most one host per unit, so one host is answerable for it rather than several.
-- `singleEvidencePerSymbol` requires exactly one unit from every selected host, so a host citing nothing and a host citing everything both fail.
-- `requireReview` makes every acknowledgement owe a matching review carrying a fingerprint of the cited content, so the review fails again once that content changes. A citation is answered by `@evidenceReview` and an exclusion by `@evidenceExcludeReview`; neither answers the other. Every reference kind accepts it, because each bridge digests a unit's content where that content is understood.
+- Every layer cites the principles for its literary purpose.
+- Every layer cites the settings for facts, rules, and knowledge.
+- Scenarios and manuscripts cite storylines for cause and consequence.
+- A manuscript cites the scenario it executes, exactly.
 
-Counting is by identity rather than by text. Repeated tags for one unit count once, an overload set stays one host, and citing a parent of two selected units counts as two.
+Editing a setting expires every review on it, so a revision leaves no stale scene behind. [`samchon/novels`](https://github.com/samchon/novels) runs this graph on 25 principles, 350 setting commitments, and 742 scenes.
 
 ## Sponsors
 

package/lib/structures/ITtscEvidenceGraphClaimBase.d.ts

@@ -38,12 +38,16 @@ export interface ITtscEvidenceGraphClaimBase<Type extends string> {
      * is where every population resolved before this property existed.
      *
      * The value names one directory, never a glob. It may sit inside the project,
-     * above it (`../../docs`), or on an absolute path. A drive-relative Windows
-     * path such as `C:docs` is refused, because it resolves against whatever
-     * directory that drive currently sits on rather than against a stable base.
+     * above it (`../../docs`), or on an absolute path, and it may be a symbolic
+     * link or a Windows junction to a directory, or sit inside one, which is read
+     * through. A drive-relative Windows path such as `C:docs` is refused, because
+     * it resolves against whatever directory that drive currently sits on rather
+     * than against a stable base.
      *
-     * Diagnostics name the resolved base, and the resolved patterns are published
-     * to the `ttsc` host as watched inputs.
+     * A diagnostic that asks you to correct this property quotes the spelling you
+     * declared, while a file location beside it is spelled the way you would open
+     * the file. The resolved patterns are published to the `ttsc` host as watched
+     * inputs.
      */
     root?: string;
     /**
@@ -86,6 +90,12 @@ export interface ITtscEvidenceGraphClaimBase<Type extends string> {
      * This is independent of `noEvidenceExclude`, which decides whether one
      * reference accepts an exclusion at all. A claim whose every reference
      * refuses them gains nothing here.
+     *
+     * A `checklist` reference is refused beside these globs. That option makes
+     * every acknowledgement one host's own answer, so confining exclusions to
+     * other files would leave every host outside them unable to record that an
+     * item does not apply. A checklist reference that also declares
+     * `noEvidenceExclude` accepts no exclusion to gather and is allowed.
      */
     evidenceExcludeCarriers?: string[];
     /**

package/lib/structures/ITtscEvidenceGraphMarkdownReference.d.ts

@@ -19,9 +19,11 @@ export interface ITtscEvidenceGraphMarkdownReference extends ITtscEvidenceGraphR
      *
      * The value names one directory, never a glob. It may sit inside the project
      * (`docs`), above it (`../../docs`), or on an absolute path
-     * (`/srv/contracts`, `C:/contracts`). A drive-relative Windows path such as
-     * `C:docs` is refused, because it resolves against whatever directory that
-     * drive currently sits on rather than against a stable base.
+     * (`/srv/contracts`, `C:/contracts`), and it may be a symbolic link or a
+     * Windows junction to a directory, or sit inside one, which is read through.
+     * A drive-relative Windows path such as `C:docs` is refused, because it
+     * resolves against whatever directory that drive currently sits on rather
+     * than against a stable base.
      *
      * Moving the root moves the addresses with it. With `root: "../../docs"` and
      * `files: ["requirements/**"]`, a section is cited as
@@ -30,9 +32,11 @@ export interface ITtscEvidenceGraphMarkdownReference extends ITtscEvidenceGraphR
      * requirements set write the same citation, and why a shared population
      * declares its root once instead of spelling `..` inside every pattern.
      *
-     * Diagnostics name the resolved base, and the resolved patterns are published
-     * to the `ttsc` host as watched inputs, so editing a document above the
-     * project still invalidates the graph.
+     * A diagnostic that asks you to correct this property quotes the spelling you
+     * declared, while a file location beside it is spelled the way you would open
+     * the file. The resolved patterns are published to the `ttsc` host as watched
+     * inputs, so editing a document above the project still invalidates the
+     * graph.
      */
     root?: string;
     /**
@@ -73,4 +77,64 @@ export interface ITtscEvidenceGraphMarkdownReference extends ITtscEvidenceGraphR
      * @default ["file", "h1", "h2", "h3", "h4"]
      */
     symbol?: TtscEvidenceGraphMarkdownSymbol | TtscEvidenceGraphMarkdownSymbol[];
+    /**
+     * Whether this document is a checklist every selected claim host answers item
+     * by item.
+     *
+     * Ordinary coverage asks its question once for the whole claim: has some
+     * declaration, anywhere, acknowledged this unit. One host citing the document
+     * therefore discharges it on behalf of every other host, which is right for a
+     * requirement a single module implements and wrong for a document meant to be
+     * read down a column — development principles, review rules, a release gate.
+     * Set this where the question is whether _each_ host answered _each_ item.
+     *
+     * The denominator is the claim's complete selected host population, so a host
+     * carrying no tag owes every item rather than being absent from the count.
+     * Either tag answers an item: `@evidenceExclude` is how a host records that
+     * an item does not apply to it, and pairing this with `noEvidenceExclude`
+     * refuses that answer and demands positive evidence from every host.
+     *
+     * Two consequences follow and both are deliberate.
+     *
+     * A positive citation answers the item it names and nothing beneath it, and a
+     * target naming no item at all is refused as an aggregate. Both halves are
+     * needed. Under the default selector the document itself is an item, so
+     * refusing only the unnamed scope would let one `@evidence docs/rules.md`
+     * cascade through every heading and tick every box, which is the state this
+     * option exists to end. `@evidenceExclude` keeps the cascade, because "none
+     * of this applies here" is one reviewed decision however many items it
+     * covers, and a host that does not participate at all should not owe one tag
+     * per item to say so.
+     *
+     * Duplicate and conflict detection moves to the host. Two hosts excluding one
+     * item, and one host citing an item another host excludes, are the expected
+     * state of a checklist rather than a duplicate and a contradiction.
+     *
+     * Every acknowledgement is one host's answer, so a tag standing on no
+     * selected host of this claim answers nothing here, and is reported where it
+     * sits once nothing else consumes it. Carrier eligibility is wider than the
+     * host gate, so the same tag may be an ordinary sibling reference's gathered
+     * exclusion or an overlapping claim's own answer, and only a tag that
+     * discharges no obligation anywhere is refused. The report covers a
+     * declaration whose kind the claim does not select and one whose position
+     * materialized no unit at all. `evidenceExcludeCarriers` is refused beside
+     * this option for the same reason: gathering exclusions into another file
+     * leaves every host outside it unable to record that an item does not apply.
+     * Declaring `noEvidenceExclude` here lifts that refusal, since a reference
+     * accepting no exclusion has none to gather.
+     *
+     * `uniqueEvidence` and `singleEvidencePerSymbol` are refused alongside this
+     * one, at configuration time rather than as coverage failures. They are not
+     * merely redundant here: a checklist requires every host to cite every unit,
+     * which the first forbids the moment a claim has two hosts and the second
+     * forbids the moment the population has two units.
+     *
+     * Pair it with `requireReview` to get the property a checklist is usually
+     * wanted for. Each host's acknowledgement then carries the fingerprint of
+     * that item alone, so editing one item expires every host's answer to it and
+     * nothing else.
+     *
+     * @default false
+     */
+    checklist?: boolean;
 }

package/lib/structures/ITtscEvidenceGraphPrismaClaim.d.ts

@@ -45,6 +45,11 @@ export interface ITtscEvidenceGraphPrismaClaim extends ITtscEvidenceGraphClaimBa
      * evidence. Every matching regular file is parsed as part of one schema
      * regardless of extension, which is what lets a lint-only `.schema` ledger
      * join the population Prisma generation never reads.
+     *
+     * That schema is composed of files rather than of paths. One file reached by
+     * two populations, as a package installed under `node_modules` and rooted
+     * again at its workspace source is, joins it once and is answered for by
+     * both.
      */
     files: string[];
     /**

package/lib/structures/ITtscEvidenceGraphPrismaReference.d.ts

@@ -22,14 +22,25 @@ export interface ITtscEvidenceGraphPrismaReference extends ITtscEvidenceGraphRef
      *
      * The value names one directory, never a glob. It may sit inside the project
      * (`prisma`), above it (`../../prisma`), or on an absolute path
-     * (`/srv/schema`, `C:/schema`). A drive-relative Windows path such as
-     * `C:prisma` is refused, because it resolves against whatever directory that
-     * drive currently sits on rather than against a stable base.
+     * (`/srv/schema`, `C:/schema`), and it may be a symbolic link or a Windows
+     * junction to a directory, or sit inside one, which is read through. A
+     * drive-relative Windows path such as `C:prisma` is refused, because it
+     * resolves against whatever directory that drive currently sits on rather
+     * than against a stable base.
      *
      * A Prisma target carries no path, so a declared root changes which files
      * belong to the schema set and where a diagnostic points, never how a model
-     * is cited. Diagnostics name the resolved base, and the resolved patterns are
-     * published to the `ttsc` host as watched inputs.
+     * is cited. A diagnostic that asks you to correct this property quotes the
+     * spelling you declared, while a file location beside it is spelled the way
+     * you would open the file. The resolved patterns are published to the `ttsc`
+     * host as watched inputs.
+     *
+     * One schema file reached through two roots is one file, parsed once, and
+     * both populations are served by that one result — which is the layout a
+     * package manager produces when a package is installed and also rooted at its
+     * workspace source. A location printed for such a file is one of the two
+     * spellings rather than each population's own, and it opens the same file
+     * either way.
      */
     root?: string;
     /**

package/lib/structures/ITtscEvidenceGraphReferenceBase.d.ts

@@ -16,6 +16,11 @@
  * Every constraint is opt-in and its zero value is the historical behavior, so
  * a reference that declares none of them is the reference that existed before
  * they did.
+ *
+ * A Markdown reference declares one more, `checklist`, which is not a peer of
+ * these. They tighten a count inside the per-reference obligation; that one
+ * gives the obligation a host dimension, and it is documented on the Markdown
+ * reference because no other artifact kind is read item by item.
  */
 export interface ITtscEvidenceGraphReferenceBase<Type extends string> {
     /** Identifies the artifact kind this population materializes. */
@@ -63,6 +68,9 @@ export interface ITtscEvidenceGraphReferenceBase<Type extends string> {
      * aggregate target contributes every selected descendant in its scope: citing
      * a parent of two selected units counts as two.
      *
+     * A reference whose population came back empty is reported as empty and
+     * judges no host, because there is no unit any host could have cited.
+     *
      * Set it where one host answers for one thing. A test function that proves
      * one operation stays reviewable; the same function citing eight operations
      * proves only that eight names appear in its JSDoc.