Evidence Graph

Every specification becomes a compile-time obligation.

Citing the evidence and describing the reason why are mandatory, so you get:

• 100% coverage of every requirement.
• 100% compliance with every principle.

/**
 * @evidence docs/discount.md#coupon-stacking States the per-issuer stacking limit this section defines, in the buyer's words.
 * @evidence POST:/orders/{orderId}/coupons Explains the rejection this endpoint returns for an over-stacked coupon set.
 * @evidence {@link hooks.useCouponStacking} Renders the limit this hook resolves.
 * @evidence .agents/skills/principles/SKILL.md#no-hard-coding Renders limits from props instead of branching on known issuer names.
 * @evidenceExclude .agents/skills/principles/SKILL.md#fix-root-causes-not-symptoms No failure to fix.
 */
export function CouponStackingNotice(props: IProps): JSX.Element;

@evidence <target> <reason> is an explicit claim about what this code implements and why. @evidenceExclude records why an obligation does not apply.

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 obligation unanswered and the build stops.

$ npx ttsc
error TS16411: [evidence/graph] Missing acknowledgement for 'docs/discount.md#coupon-stacking'
  (Markdown H2 'Coupon Stacking' at docs/discount.md:3)
  in Claim 1 reference 1 (markdown, symbols: h2, h3).
 
...
 
Found 5 errors.

Missing obligations appear in the same build as type errors. The error list is the agent’s task list.

Benchmark

One agent built each subject twice. Same inputs, same engine, same model; only this plugin differs.

Without the graph an omission is invisible. Nobody can name what was skipped, so review reads everything again and again, and what it misses ships.

Loading the measurement.

That loop is where the tokens go, and counting the obligations ends it. The agent reads a list of errors rather than the whole codebase, and review narrows to one question, whether each citation is true, asked of the tags rather than of the repository.

The benchmark breaks each run down by phase, and samchon/evidence-benchmark-results keeps the raw sessions.

Evidence Tags

Four tags, written on the declaration that owes the answer.

• @evidence cites the evidence and describes the reason why.
• @evidenceExclude declines an obligation and describes why it does not apply.
• @evidenceReview records that a citation was verified, and expires when the cited content changes.
• @evidenceExcludeReview does the same for an exclusion.

A small model writes a false citation now and then, and a false tag removes the error rather than the problem.

Mandating @evidenceReview closes that too. The citation is not accepted until a separate tag testifies that it was checked, and the testimony expires when the cited content moves.

Spec-Driven Development

Requirements are the handoff: whether a human or an AI wrote them, a human reviews them last, and everything below is built from that reviewed layer. Each arrow above is one claim in lint.config.ts.

Hand over the requirements and the agent writes the rest. Hand over raw idea notes and it writes the requirements too. A dropped idea or a skipped requirement is a compile error, so nothing vanishes on the way down.

Configuration

// lint.config.ts
import { evidence, type ITtscEvidenceGraphConfig } from "@ttsc/evidence";
import type { ITtscLintConfig } from "@ttsc/lint";
 
const graph: ITtscEvidenceGraphConfig = {
  claims: [
    {
      type: "typescript",
      files: ["src/components/**/*.tsx"],
      symbol: "function",
      reference: {
        type: "markdown",
        files: ["docs/**/*.md"],
        symbol: ["h2", "h3"],
      },
    },
  ],
};
 
export default {
  plugins: { evidence },
  rules: {
    "evidence/graph": ["error", graph],
    "evidence/review": "error",
  },
} satisfies ITtscLintConfig;

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.

files and symbol pick who owes the answers, reference picks the questions they owe, and the policies beside it decide how strictly each obligation is judged.