Skip to content

Intentset Core Specification v0.2

Draft intentset/core/0.2 · revision 2026-11-15 · implemented by 0.16.0 · Rendered from spec/core-0.2.md in the repository.

1. Purpose and scope

Intentset is an open framework for keeping product intent, observable behavior, implementation, verification, and published knowledge connected. Repository files are authoritative; the graph, Atlas, reports, and customer knowledge are derived views. A graph database is not required.

This specification defines product semantics and interchange. The VSA specification adds implementation ownership and architecture constraints. The reference profile maps those constraints to TypeScript and Amplify Gen 2. Core adoption does not require either architecture or platform.

MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY express requirements in this draft. SHOULD departures require a recorded reason. Examples are informative unless a rule explicitly makes them normative. The CLI, Atlas, publisher, and MCP server named here ship in the TypeScript reference implementation (@intentset/* on npm), whose conformance suite is published for other implementations; this specification, not that implementation, is normative.

Change policy. The six Intentset specifications are drafts. Each opens with its id, status, revision (the date its text last changed) and implementation (the reference release that implements that revision), and every change is recorded in the repository's CHANGELOG. The conformance suite decides what kind of change a revision is, in every section of it (core, vsa, evidence, publication, export and list), whichever specification the case belongs to: one that invalidates an existing case, changing its valid or diagnostics so that a repository which conformed before no longer does, is breaking; one that leaves every existing case as it was, such as a new optional field, a new check with cases of its own, or a clarification, is not, and neither is one that only relaxes a case so that nothing which conformed stops conforming, as 0.2.0 did when VSA §3 made two errors warnings for draft slices. intentset.spec is the one version a record declares, so it answers for all of them: while the specifications are drafts, the next breaking change to any specification, VSA, the reference profile and the publication profile as much as Core, moves intentset.spec to the next value, and documents declare it. The first move was on 2026-10-14, from 0.1 to 0.2; until 2026-10-05 breaking changes stayed inside 0.1, and two did before the move. The export envelope versions separately (export contract §7).

What a move means for a record. spec is the string 0.2 and profile equals intentset/<type>/0.2 (§4). A reader of one value rejects a record that declares another, as an error that makes the record unusable, so a repository moves all of its records together, and the move rewrites those two fields and no other.

Revisions that changed what a reader who conformed earlier sees, recorded so that they know why (the breaking ones, and one that changed a default without invalidating any case):

Revision Change
2026-10-04 (0.1) An active outcome MUST have a measure (§5, CORE003; ADR 0012). A repository with an outcome past draft and no measure validated on 2026-10-03 and fails from this revision; while the outcome is draft it is a CORE009 warning.
2026-10-14 (0.1) Run evidence is judged by subject binding by default wherever slices claim files (§8, ADR 0013); the commit rule is binding: commit. A repository with slices whose records are bound to a commit, as every record written before this revision is, reads stale until its runs are imported again or it sets evidence.binding: commit. The evidence cases that test the commit rule now say so in their configuration, so none of them changed its valid or diagnostics.
2026-10-14 (0.2) intentset.spec moves from 0.1 to 0.2 (ADR 0013, ADR 0014). The row above changes what an existing run record means, because evidence is judged by the subject it checked unless a repository asks for commit binding, so the specifications move rather than a record of 0.1 meaning two things. A document declares spec: '0.2' and profile: intentset/<type>/0.2, and one that declares 0.1 is rejected (§4). The reference implementation's intentset migrate --to 0.2 rewrites those two values and nothing else.
2026-10-15 (0.2, no move) A resource's files are in a subject only where a verification exercises it (§8, ADR 0013 amended 2026-10-15). Release 0.7.0 hashed the files of every resource an included slice lists in usesResources, so one backend change made stale every verification of every slice that talks to it. The default is now evidence.resources: exercised, and the earlier rule is evidence.resources: used. No case changed its valid or diagnostics (the cases that test the earlier rule now say used in their configuration, as the commit-rule cases said binding: commit), so this does not move intentset.spec; a subject-bound record made under the earlier rule carries a hash the default no longer computes for a verification whose slices list resources, and reads stale until it is imported again, or until the repository sets evidence.resources: used, which reproduces the earlier hashes exactly.
2026-10-15 (0.2, no move, second) A dependency slice can count through its contract (§8, ADR 0013 amended 2026-10-15, second). A slice reached only through dependsOn contributes every file its claims resolve to, so a change to a central slice moves nearly every subject: SLICE-PLATFORM-ORGANIZATION moved 227 of the 237 records of Streamlane's store. evidence.dependencies: entrypoint makes such a slice contribute its binding fields, its entrypoint files and the records of its contracts and their decisions, and files, the default, is the earlier rule; the back-test did not justify making entrypoint the default (ADR 0013). A new warning, EVID007, says what entrypoint could not see. Nothing changes for a repository that does not set the key, and no existing case changed its valid or diagnostics, so intentset.spec does not move.
2026-10-21 (0.2, no move) VSA006 judges a name by the layer of the file that defines it (VSA §5, profile §3). A name an import takes through an entrypoint, a barrel or another slice's contract was judged by the file the import named, and an entrypoint is in no layer, so a hook could take a client function through one and pass. A repository whose layers took names that way sees VSA006 errors it did not see before. No existing case changed its valid or diagnostics (the cases for the bypass are new), so intentset.spec does not move.
2026-10-21 (0.2, no move, second) Policies, models and the client seam do not import UI frameworks or render JSX by default (profile §3, TS007, TS008). The profile's sentence that policies and models MUST NOT import UI was enforced for the slice's own UI files and not for packages, and nothing kept UI out of the client seam. The new default forbiddenPackages names the UI frameworks for the policy, model and external layers, so a repository whose files in those layers import one, or render JSX, sees TS007 or TS008 errors it did not see before; setting forbiddenPackages replaces the default. No existing case changed its valid or diagnostics, so intentset.spec does not move.
2026-10-21 (0.2, no move, third) A baseline entry that matches nothing is an error (VSA §9, VSA014). A stale entry was counted in the summary and failed nothing, so a violation that was fixed could come back under it. In migration mode each is now VSA014, an error until the baseline is written without it, which --write-baseline does. A repository whose baseline holds entries its code no longer has sees VSA014 errors it did not see before; strict mode ignores the baseline as before. The new cases carry their baseline in a new optional case field, architecture, and no existing case changed its valid or diagnostics, so intentset.spec does not move.
2026-11-14 (0.2, no move) A published document no longer carries the snapshot it was published from (§9, publication §2, ADR 0019). Every document's intentset-publication block, and so its HTML <meta> and its retrieval chunks, carried snapshot, whose graph hash moves with any record in the model, so every published file changed whenever any record did. The publication names its snapshot once, in its help file (publication §5). A reader that took the snapshot from a document reads it from the help file instead. No case checked the per-document snapshot, so none changed its valid or diagnostics, and neither intentset.spec nor the profile intentset/publication/0.2 moves.
2026-11-14 (0.2, no move, second) A record can say on what basis it was approved, and which outside requirement it formalizes (§5, §7, ADR 0020). approval and formalizes are new optional fields, and §8 says that a verification's status carries no approval meaning. Unknown keys under intentset are errors (§3), so a reader of an earlier revision rejects a record that carries either field: a repository moves its tools before it writes them. No existing case changed its valid or diagnostics, so intentset.spec does not move; the export moves to intentset/export/0.6 (export contract §7).
2026-11-15 (0.2, no move) A publication names its snapshot in a file of its own, and nowhere else (§9, publication §5, §6, ADR 0021, amending ADR 0019). The help file and the publisher's index carried snapshot, the commit and graph hash, which move with every commit that changes a record, so a repository that commits its published output had both files of every projection rewritten by each publication, and two branches that each published conflicted on all of them. snapshot.json now names the commit and graph hash, and the help file and the index do not, so publishing the same knowledge at two commits writes the same bytes in every other file. A reader that took the snapshot from the help file or the index reads it from snapshot.json; a reader of the help file accepts one with or without snapshot. One publication case's published expectation moved with it, from the help file naming the snapshot to the snapshot file naming it; no case changed its valid or diagnostics, so neither intentset.spec nor the profiles intentset/publication/0.2 and intentset/help/0.2 move.

2. Semantic model and granularity

Type Meaning Review question
product Product identity and scope What system are we describing?
intent Strategic purpose Why should this product exist or change?
outcome Desired measurable change What improvement will show success?
measure How one outcome is judged: metric, baseline, target, window, source What reading will tell us the outcome was achieved?
capability Stable product ability What can a user accomplish?
behavior Observable action or response under stated conditions What exactly does the system do?
rule Constraint governing behavior What must remain true?
scenario Concrete conditions, action, and expected result What example would demonstrate the promise?
slice Implementation owner of a cohesive set of behaviors Where is the behavior delivered?
contract Maintained interface between implementation owners What may another component rely on?
verification Definition of an executable check or review procedure How is a claim assessed?
knowledge Audience-specific explanation grounded in product artifacts What may we tell this audience?
decision Architecture/product decision and rationale Why was this design selected?

A capability MAY contain many behaviors and map to several slices. A behavior SHOULD contain one recognizable promise, including its failure response. Split it when release, ownership, availability, or independent review differ. A rule MAY govern many behaviors; it MUST NOT be duplicated solely to appear in multiple capability pages. A scenario is an example, not proof that all cases work.

Recommended human decomposition is product → intent → outcome → capability → behavior, with each outcome's measures beside it. This is a navigation spine in a typed graph, not a demand that reality form one tree. Technical detail belongs in rules, scenarios, decisions, and implementation views; strategic reviewers should start at capabilities and drill down.

3. Authoritative representation

Each artifact MUST have exactly one authoritative UTF-8 Markdown document with YAML frontmatter in the declared repository scope. Slice documents are named slice.md in this profile; other filenames are not identity. Markdown with frontmatter is the one v0.2 carrier, so records and their explanation travel together. A later standalone YAML binding MAY be specified; v0.2 tools MUST NOT silently merge duplicate records.

Frontmatter MUST be the first block between --- delimiters. It MUST decode to a JSON-compatible object. Reject duplicate keys, custom YAML tags, merge keys, aliases, and non-finite numbers. Quote dates and version strings. Implementations MUST limit file size, nesting, and parser resource use. Document bodies MUST NOT execute code or templates. Ordinary code fences remain inert text.

---
markset: 0
intentset:
  spec: "0.2"
  profile: intentset/behavior/0.2
  id: BEH-ASMT-SCHEDULE
  type: behavior
  title: Schedule a student assessment
  status: approved
  owner: team-assessment
  visibility: internal
  audiences: [engineering, product]
  parent: CAP-ASMT-ASSIGN
  links:
    governedBy: [RULE-ASMT-FUTURE]
  availability:
    products: [PRD-LANTERN]
    releases: ["pilot-1"]
    roles: [teacher]
    editions: [standard]
    flags: []
---

markset is required by the Intentset Markset binding, not by language-neutral graph interchange. intentset.profile is an Intentset-owned semantic profile identifier; it is not a claim that Markset has registered a profile API. Unknown top-level frontmatter is preserved, but cannot alter Intentset semantics. Unknown keys inside intentset are errors except under extensions.

4. Common fields and identity

Required common fields are spec, profile, id, type, title, status, owner, visibility, and audiences. spec is the string 0.2. profile MUST equal intentset/<type>/0.2. id MUST match ^[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+$ and be unique within the product graph. IDs are case-sensitive, immutable, independent of title/path, and MUST never be reused. Recommended prefixes are PRD, INT, OUT, MEAS, CAP, BEH, RULE, SCN, SLICE, CONTRACT, TEST, KB, ADR. Prefixes aid humans; type determines semantics.

owner is one accountable team/role identifier from the repository's owner registry. audiences is a nonempty array from its audience registry. These are documentation audiences, not runtime authorization. visibility is public, customer, internal, or restricted. Missing access information MUST fail closed for publication.

Optional common fields: parent, links, availability, revision, reviewedAt, reviewedBy, delivery (§7), approval (§7), formalizes (§5, on a behavior, rule or scenario), extensions. revision is a positive integer incremented for semantic changes. Review fields identify a review record, not automated proof. Extensions MUST be namespaced (for example org.example/change) and cannot redefine core fields. Source hashes and commit IDs are computed externally, not manually maintained in every document.

Moving a file or correcting wording does not change identity. Splitting a behavior creates new IDs and preserves the old artifact as retired with replacedBy links. Merging works similarly. Historical release snapshots keep the earlier meaning.

5. Relationships and cardinality

Relationships are authored once, in the direction below. Reverse edges are derived and MUST NOT be separately maintained. References MUST resolve in the same graph snapshot. A requirement outside the model that a record formalizes is named in formalizes, below; other external issue/PR URLs belong in extensions; neither is ever written as a dangling internal ID.

Field / relationship Source → target Cardinality and meaning
parent intent → product; outcome → intent; measure → outcome; capability → outcome or capability; behavior → capability Exactly one except product; navigation parent
governedBy behavior → rule Zero or more constraints
illustrates scenario → behavior One or more behaviors exemplified
implements slice → behavior One or more for product slices; authoritative ownership
dependsOn slice → slice Zero or more implementation dependencies
exposes slice → contract Zero or more public contracts
consumes slice → contract Zero or more consumed contracts
verifies verification → behavior, rule, or scenario One or more assessed claims
explains knowledge → behavior, rule, or capability One or more sources of knowledge
informedBy slice, contract, or behavior → decision Zero or more supporting decisions
requires behavior → behavior Zero or more functional prerequisites
supports outcome → intent; capability → outcome Additional associations beyond the navigation parent
replacedBy retired artifact → same type One or more successors when applicable

All arrays contain unique IDs. Self-edges, duplicate edges, invalid endpoint types, cycles in parent, cycles in replacedBy, and cycles in requires are errors. Other cycles are evaluated by the relevant profile; dependsOn is governed by VSA. Each non-root navigation chain MUST reach a product. An artifact without a navigation parent is reached through its typed relationships. Active rules MUST have an incoming governedBy; active scenarios, verifications, and knowledge MUST have their corresponding outgoing links. An active outcome MUST have at least one measure whose parent it is: an outcome past draft says how it will be judged, and the capabilities under it do not say that. Draft unattached artifacts, and a draft outcome with no measure, produce warnings.

At VSA adoption, an approved, implemented, released, or deprecated behavior MUST have exactly one accountable product slice through implements. Other collaborating slices appear through slice dependencies and contracts. Exactly one owner keeps accountability unambiguous while still allowing multi-slice implementations. A slice MUST NOT implement a behavior already owned elsewhere.

Outside requirements. Every relationship above points at another record. A behavior, rule or scenario MAY also name the requirements outside the model that it formalizes, such as a work tracker's item or one acceptance criterion of it, in formalizes (ADR 0020): a list of at least one entry, each with source, a URL or a tool's key for the item, and optionally anchor, which identifies the part of the source that is meant, such as criterion-3. Both are non-empty strings, an entry has no other key, and no two entries have the same source and anchor.

  formalizes:
    - source: https://tracker.example/LAN-12
      anchor: criterion-3

formalizes is not a relationship: it makes no edge, it has no inverse, and nothing is derived from it. A validator checks that it is well formed, CORE001, as it is on any other type, and MUST NOT resolve it: it never fetches a source, and never judges whether the source exists or still says what it said (§11). It says where a promise came from, not what the promise is, so a record's content hash leaves it out (publication §3): adding the reference to a record, or a tool renumbering its criteria, does not send the knowledge that explains the record back to review.

6. Required narrative by artifact type

Every document MUST contain a level-one heading matching its title and substantive prose. Validators can check section presence; reviewers determine semantic adequacy.

Type Required level-two headings
product Scope
intent Rationale
outcome Measure
measure Method
capability Overview
behavior Behavior; Preconditions; Outcomes
rule Constraint
scenario Given; When; Then
slice Responsibility; Public contract; Verification
contract Interface; Compatibility
verification Procedure; Expected result
knowledge Guidance
decision Context; Decision; Consequences

A behavior MUST identify actor, trigger, observable success response, and meaningful failure response in these sections. An intent's Rationale MUST name the problem or opportunity the change answers: the reason a reader would start the work at all, not a restatement of the title. An outcome's Measure summarizes how the outcome will be judged and which measures judge it; the metric, baseline, target, window and source live in the outcome's measure records, below. A measure's Method MUST say how the reading is taken, by whom or by what, and what would make it untrustworthy. A verification's Procedure MUST identify automation or a reproducible manual review; neither a filename nor a test count is sufficient.

A measure judges one outcome, its parent, and carries a measure metadata block: metric, an identifier in lower case with words joined by _ or -, named the way the evidence source names it; baseline, the value before the change or the literal unknown when none has been taken, never omitted; target, the value or threshold that would show the outcome was achieved; window, when the reading is taken, relative to a release or a date; source, an entry in the repository's evidenceSources registry naming where the evidence is expected to come from (an analytics product, a study, a survey); and optionally direction, increase or decrease, which way the metric moves when the outcome is achieved. Values other than metric and direction are prose, not parsed: a target of under 2 days and a window of 90 days after pilot-1 are complete. A measure block on any other type is an error, as a verification block is (§8). Intentset defines what success means; it does not collect telemetry, run queries or compute a metric, which belong to the systems the registry names.

Verification (§8) and measurement answer different questions and neither stands in for the other. Verification asks whether the behavior was built as described; a measure asks whether building it produced the outcome. A behavior can be implemented correctly, pass every check and ship, and the outcome above it can still fail; the model MUST be able to say so, which is why an outcome's measures are records of their own rather than a sentence in the outcome.

7. Lifecycle, release, and version semantics

status is draft, approved, implemented, released, deprecated, or retired. Default progression follows that order. Drafts may be retired without release. Returning to draft requires a review note and MUST NOT rewrite immutable release snapshots. Released artifacts are changed through a new snapshot; their ID remains stable only when meaning remains recognizably continuous.

Status is an editorial claim, not a test result. approved records intent; implemented records an implementation claim; released requires inclusion in a reviewed release snapshot. deprecated remains available until the stated removal; retired is excluded from current publication and retained for history.

Delivery states whether the work a record describes exists, apart from its approval (ADR 0017). delivery is planned, the work does not exist yet, or built, the code the record describes exists. It is optional, and is written only on a capability, behavior, rule, scenario, slice or contract; on any other type it is CORE001. A record's effective delivery is its delivery when present; otherwise built when its status is implemented, released or deprecated, since each claims an implementation; otherwise not stated. approved claims nothing about the code, so an approved record without the field is not stated. Delivery is a statement of fact, not a review: whoever writes a record sets it when it is true, an agent included, as built on a record written from existing code and planned on a proposal, and the change that builds planned work changes it to built. A draft that says built is still a draft, and nothing in delivery approves, implements or publishes a record.

Delivery and status contradict each other, CORE005, when a record says delivery: planned while its status is implemented, released or deprecated, and when a behavior whose effective delivery is built is implemented by a slice that says delivery: planned. At L2, a draft behavior that says built and that no product slice implements is a CORE006 warning, so built code without an owner shows before anyone approves the record, and a draft slice that says built, or implements a behavior whose effective delivery is built, has no planned paths (VSA §3). Release labels are opaque, so a validator cannot tell whether a planned record's release has shipped. Knowledge that explains a record whose delivery is planned is not published as current (publication profile §4).

Approval basis states how a record came to be approved (ADR 0020). status: approved reads the same whether a person read the record or it was derived from something a person approved, so a record of any type MAY carry approval, with at, when it was approved, a date or a date and time written as a quoted string as reviewedAt is, and basis, one of:

basis Meaning by source attestedBy
direct A person read this record and approved it required: the person not written not written
derived The record is approved because a named source that a person approved covers it required: the person who approved the source required optional: the agent that attested the record matches the source
attested An agent attested the record; no person approved it or a source of it not written not written required: the agent

by always names a person and attestedBy always names an agent, each by a name or an identifier the repository chooses. source names what was approved: ref, a URL or a tool's key for the item, and at least one of revision and digest (such as sha256:…), which say which state of it. Every value is a non-empty string, and neither block has any other key.

  approval:
    by: ana.reyes
    at: "2026-11-14"
    basis: derived
    source:
      ref: https://tracker.example/LAN-12
      revision: "7"
    attestedBy: drafting-agent

A validator checks this shape, CORE001, and nothing else. It never resolves ref; it never decides who may approve, whether a basis is acceptable or whether a person is required, which are the adopting organization's workflow and not Intentset's; and it does not compare approval with status. approval is not required on an approved record, and a record without it says nothing about how it was approved. It concerns the record's own promise, which makes it a different statement from reviewedBy, reviewedAt and the intentset.org/review extension: those record that a knowledge article was reviewed against the sources it pins (§9). Like status, approval is left out of a record's content hash (publication §3), so writing or changing it never makes knowledge need review.

A release snapshot records product ID, exact release label, source commit, graph hash, specification/profile versions, and build time. Release labels are opaque strings: v0.2 performs exact matching, not inferred SemVer ordering. availability, required on behaviors and knowledge, contains nonempty products, releases, roles, and editions arrays plus a flags array. All named flags are required; empty means no flags. No implicit wildcard is allowed. Applicability is AND across dimensions and OR within an array. The repository registries define valid dimension values.

A release may include deprecated behavior; prospective documentation MAY describe future work only in a separately labeled roadmap projection. A status of “released” alone MUST NOT make a feature available to all customers.

8. Verification definitions and run evidence

Verification nodes identify checks. Evidence is a separate run record, since runs change more frequently than product semantics. verification metadata contains method (automated or manual), locator (repository-relative path), selector (stable test or review case identifier) and optionally exercises: unique IDs of slices or registry resources the check drives beyond what the slices implementing its behaviors reach, as an end-to-end test drives code its behavior's slices do not import. Each MUST name a slice in the graph or a resource in the registries (CORE003).

A run record MUST include evidence ID, verification ID, source commit, graph hash, environment, exact product/release scope, tool/version or reviewer identity, start/end UTC timestamps, result (pass, fail, skip, error), and an evidence URI. A manual record also MUST identify reviewer and review rationale. A record MAY carry binding (subject or commit) and subjectHash, a SHA-256 in lowercase hex; a record with binding: subject MUST carry subjectHash, and one without binding is a commit-binding record, so every record written before the field existed means what it meant. URI presence is not proof of trustworthy execution; evidence producers and stores must be controlled by the adopting organization. A run record with a problem is EVID001 and never counts; the evidence codes are in §11.

A verification's status says where the definition stands in its own lifecycle, and nothing in this specification reads an approval from it (ADR 0020). The runs of a verification that is not retired count whatever its status, a draft's included; whether evidence is required follows the status of the claim, not of the verification (§11, CORE007); and the only checks that read a verification's status are the ones every type shares: a retired one is set aside, and one that verifies nothing is CORE003 once it is past draft and a CORE009 warning while it is a draft (§5). A tool MAY therefore treat a verification's standing as that of the behaviors, rules and scenarios it verifies, and need not ask for an approval of the verification itself. A validator derives no such standing: a verification of several claims whose statuses differ has no single one, and choosing among them would be a workflow rule.

Only a pass whose binding holds counts as current passing evidence. There are two bindings:

The binding in force is the one the repository asks for, as evidence.binding in .intentset/config.yaml (§11) or as a gate requires; otherwise subject wherever a slice that is not retired has claims, and commit where none does. A repository with no slice claims has no subject to hash, so it is judged by commit even when it asks for subject, and every report says so (EVID004): it never falls back silently. Under subject binding a commit-binding record is stale, with a note that it is bound to a commit and can be imported again; under commit binding a subject-binding record is stale, with a note that it is bound to a subject. The status vocabulary does not change. A report says which binding judged each verification and, for a stale subject-binding record, which parts of the subject changed since the record's commit when that can be known.

The subject is a SHA-256, over the canonical JSON (ADR 0005) of a list of entries {kind, id, hash, why, owner} sorted by kind, then id, then owner (why and owner are omitted where they do not apply), of:

A file's hash is the SHA-256 of its bytes, and absent when the file does not exist, so a deleted file moves a subject and is told apart from an empty one. What no file holds, such as a deployed environment or a service's version, stays outside the binding; a record's environment says which it ran in.

Claims and what a verification exercises therefore decide whether evidence is current. A file that changed between the commit of a subject-bound current record and the assessed commit and that no slice claims, no exercised resource names, no global input lists and no record or test names cannot move any subject; when that commit is an ancestor of the assessed one a report lists such files, the first twenty and a count (EVID005), and otherwise says it could not. Run records under .intentset/evidence/, the directory a tool reads them from by default, are the assessment's own input and are never listed. A file of a resource that a current record's slices list and its verification does not exercise cannot move that record's subject either: when the file changed since the record's commit the report says how many verifications are current though a resource they use changed, and names the resource, its changed files and those verifications (EVID006), so a repository can add exercises where a check does depend on the resource. Under evidence.dependencies: entrypoint a file of a dependency slice that is not one of its entrypoints cannot move the subject either: when such a file changed since the record's commit the report says how many verifications are current though a slice they depend on changed outside its entrypoints and contracts, and names the slice, its changed files and those verifications (EVID007), so a repository can name the slice in exercises where a check does depend on its internals. None of the three is an error, and none makes a record stale. Skip, error, absence, and stale runs MUST NOT count as pass. Link coverage and current passing coverage MUST be displayed separately. A failing current run MUST remain visible even if a prior run passed.

Informative: where run records live. Under commit binding a run record committed to the repository it assesses describes a commit that is no longer the latest the moment it lands, and reads as stale; under subject binding it still goes stale whenever the commit it lands in changes the subject, so the advice is the same. Keep run records in CI artifacts or another store the adopting organization controls, never in the commit under assessment. (Found by the Streamlane pilot, 2026-10-02.)

Outcome evidence. A measure's reading is evidence of a different kind from a run record, and no v0.2 tool reads one. When a later version or an external system such as a usage product supplies it, an outcome evidence record names the measure ID, the window it was read in, the observed value, the source it came from, the time of the reading and an evidence URI, and it says whether the target was met. It is never current in the sense a run record is: a reading is bound to a window, not to a commit and graph hash, and an outcome met in one window may be missed in the next. Until that record is specified, such evidence travels in namespaced extensions, which every tool preserves and none interprets.

A claim is “verified in snapshot” only if every applicable required verification linked to it passes. Scenarios and governing rules require their own coverage; a parent behavior pass does not silently satisfy them. Manual and automated coverage MUST be separately countable. Structural validation cannot prove that tests adequately assert the documented behavior.

9. Markset profiles and document publication

Intentset owns metadata, required sections, semantic validation, graph resolution, and publication policy. Markset owns document syntax and rendering. The reference implementation MUST accept Markdown + YAML frontmatter and support Markset validation/rendering through a version-pinned adapter. Plain Markdown fallback MUST remain readable. Profiles MUST NOT introduce :::behavior, :::rule, or any other new Markset directive.

The profiles are intentset/<type>/0.2, plus generated intentset/atlas/0.2 and intentset/publication/0.2. Generated profiles are publication outputs, not canonical graph nodes. Metadata validation and Markset validation MUST produce separately identifiable diagnostics. A successful render MUST NOT imply semantic conformance.

Use ordinary Markdown links with repository-relative paths for authored cross-references. ID resolution is an Intentset graph function. Symbolic-reference syntax and a Markset-native profile registry are deferred; no new syntax is assumed in v0.2. Bodies MAY use any construct in Markset's closed vocabulary, which Markset validates; the records in the worked example are plain Markdown. The reference implementation pins Markset's parser and renderer to one exact version, named by its adapter, and moves the pin deliberately, so two packages never read one document with two parsers. Markset's own guide for writing its syntax is markset.org/guide.md.

Publication pipeline:

Canonical files → validated graph → exact release snapshot
                → authorized audience projection → reviewed knowledge
                → generated Markset → HTML / portable text / retrieval chunks

A publisher MUST select authorized artifacts before sending text to a renderer or language model. It MUST deny by default, intersect product/release/role/edition/flag availability, restrict visibility and audience, and exclude draft/retired material. Public projection allows public records only. Customer projection allows public and customer records, with authenticated entitlements; internal/restricted data require separate explicit authorization. Knowledge bodies are curated audience-safe text, not automatically copied engineering prose.

A knowledge record MAY carry tips: a mapping from an ID in its links.explains to one sentence of plain text, on one line and at most 160 characters, for a product to show beside the control that delivers that behavior or enforces that rule. A tip is the knowledge at its shortest, so it is written on the knowledge record and reviewed, projected and published with it; it is never copied from the explained record, whose prose is written for another audience. A key that is not in links.explains is CORE003. A tip that is not a string, is empty, begins or ends with whitespace, breaks a line or exceeds the limit is CORE001, as is tips on any other type. The publication profile says how tips reach a product.

Each published knowledge document MUST retain source IDs, source revisions/hashes, audience, availability, reviewer, and publication timestamp. The snapshot ID is the same for every document in a publication, so the publication names it once, in a file of its own beside its documents, and neither a document nor any other file of the publication carries it (publication §2, §6; ADR 0019, ADR 0021). A publication committed to the repository it was published from may leave that file out. If a source changes, dependent knowledge becomes needs-review and MUST NOT be republished as current until reviewed. What counts as a change is what the review pinned (publication §3): a review that pins content hashes is not disturbed by a source's approval, implementation or delivery, and is by any edit to what the source promises and by its deprecation or retirement. Generated files MUST be marked derived and MUST NOT be edited as canonical truth. A reference to an excluded source MUST fail publication or be replaced with an explicitly reviewed safe explanation; it MUST NOT leak the source title or internal path.

Retrieval chunks MUST inherit the same access filters and provenance. Authorization must occur before retrieval and again before response assembly; filtering only the final answer is insufficient. Answers MUST cite eligible knowledge, disclose unavailable evidence, and abstain when the requested version is unknown. Documentation metadata MUST NOT be used to grant runtime product access. Generated prose needs review; graph connectivity alone cannot establish that it is accurate.

10. Human review, impact, and agent context

An Atlas SHOULD provide: product/capability overview; behavior detail; engineering ownership; verification status; publication readiness. Summary counts MUST disclose snapshot, denominator, scope, and whether they measure links or current pass evidence. The UI MUST expose missing/stale evidence rather than replace it with a generic green status.

Impact reports MUST show direct changes separately from candidate downstream effects. Starting at an ID, traverse reverse relationships to dependent behaviors, owners, verifications, and knowledge; include outgoing rules, contracts, and decisions as review context. Traverse reverse slice dependencies transitively, with a visited set. Include parent ancestors for navigation. Record each path/reason; do not label reachability as proof that runtime behavior changed.

Before an agent edits implementation it SHOULD load the owning slice, behaviors, rules, scenarios, contracts, and decisions. Afterward it SHOULD update affected semantics and checks in the same review. Agents MUST NOT self-approve release/publication simply because validation passes. MCP and CLI context results MUST identify snapshot and source paths; customer tools MUST use the restricted publication index, never raw engineering context.

A review of a change SHOULD list each slice whose implementation changed while none of the records describing it did. A slice's implementation is what its source, backend, and contract claims match, record files excepted. The records describing it are the slice, the behaviors it implements, the rules governing them, the scenarios illustrating them, the verifications of any of those, the contracts it exposes, and the decisions informing the slice, its behaviors, or its contracts. The list is a prompt for review, not a failure: a change that alters no behavior MAY say so for named slices where its reviewer reads it, such as a commit trailer, and a tool MAY then treat those slices as acknowledged, but MUST still list them.

11. Conformance and diagnostics

Conformance is a claim about a declared repository scope and snapshot, not a universal product certification. Publish the spec/profile versions, scope, exclusions, waiver count, checker version, and report hash.

Level Required conditions
L1 Product model Parse, identity, fields, typed links, hierarchy, lifecycle, narrative checks pass
L2 Traceable implementation L1 + VSA ownership and path attribution for adopted behavior scope
L3 Verified product L2 + applicable behavior/rule/scenario verification definitions and current passing evidence
L4 Published knowledge L3 + reviewed audience projections with availability and provenance checks
L5 Continuous product truth L4 + required CI checks, architecture enforcement, impact reports, release snapshot automation and versioned agent context

A partial adoption MUST name included capabilities/IDs and show out-of-scope counts; it MUST NOT advertise repository-wide L3 when only a pilot passed. A waiver does not erase a failed MUST: report “with exceptions,” not unqualified conformance. Recommended checks:

Code Condition Default
CORE001 Invalid carrier, schema, or required section Error
CORE002 Duplicate/reused ID Error
CORE003 Unresolved, wrong-type or missing required relationship Error
CORE004 Invalid/cyclic decomposition or replacement Error
CORE005 Lifecycle/release claim inconsistent, delivery and status included (§7) Error
CORE006 Missing applicable ownership (L2+) Error; a warning for a draft behavior that says delivery: built (§7)
CORE007 Missing/failing/stale required evidence (L3+) Error; a warning for a draft behavior, rule or scenario that no verification definition names
CORE008 Unauthorized/stale publication (L4+) Error
CORE009 Draft unattached artifact, or draft outcome with no measure Warning

Configuration and run records have codes of their own, reported before or beside the checks above. A configuration error stops the run it configures; a run record with a problem is never evidence.

Code Condition Default
CFG001 .intentset/config.yaml (origin profile) or .intentset/architecture.yaml (origin architecture) does not parse, names an unknown key, or gives a key the wrong shape or an invalid pattern; in config.yaml, evidence takes binding (subject or commit), globalInputs (paths or patterns), resources (exercised, the default, or used: which resource files a subject hashes, §8) and dependencies (files, the default, or entrypoint: what a dependency slice contributes to a subject, §8), each optional Error
CFG002 The registries file does not parse, names an unknown registry, or a registry is not a list of unique non-empty strings (resources: a list of resource records with known keys and unique IDs) Error
EVID001 A run record is malformed (§8: a required field missing or of the wrong type, the file not an array of records, an evidence ID repeated, a binding other than subject or commit, a subjectHash that is not 64 lowercase hex, binding: subject with no subjectHash), or a manual run names no reviewer or rationale Error
EVID002 A run record names an ID that is not a verification in the graph, so it is evidence for nothing Warning
EVID003 A verification's locator is not a file in the repository tree Warning
EVID004 The repository has no slice claims and did not choose commit binding, so evidence is judged by commit binding for want of a subject (§8) Warning
EVID005 Files changed since the commit of a subject-bound current record that no slice claims, no exercised resource names, no global input lists and no record or test names, so they cannot make evidence stale, other than run records under .intentset/evidence/; the first twenty are listed, with a count (§8) Warning
EVID006 Verifications whose subject-bound record is current though a resource their slices list and they do not exercise has a file changed since the record's commit, so the subject cannot see it; the resource, its first five changed files and the first twenty verifications are listed, with a count (§8) Warning
EVID007 Under evidence.dependencies: entrypoint, verifications whose subject-bound record is current though a file of a slice they depend on, outside its entrypoints, changed since the record's commit, so the subject cannot see it; the slice, its first five changed files and the first twenty verifications are listed, with a count (§8) Warning

Diagnostics MUST identify code, severity, origin, artifact, path, field/location, explanation, and remediation. origin names the stage that reported it, and keeps Markset's diagnostics apart from Intentset's: syntax (Markset, §9), profile (the carrier, frontmatter, required sections, configuration and registries), graph (identity, relationships and lifecycle across records), architecture (VSA and its profiles), evidence (run records, §8), publication (the publication profile), and render (a renderer, reserved: no v0.2 check reports it). No other value is valid. Intentset codes are AREA###, Markset's are AREA_NAME; a host never renames the other's. A diagnostic with origin syntax is Markset's (§9) and keeps Markset's own code, such as DIRECTIVE_UNKNOWN_NAME; every other origin carries an Intentset code from the tables here and in the profiles. Sort by path, artifact ID, code. Validation MUST be deterministic for identical inputs and MUST NOT silently rewrite files. CLI exits are 0 pass, 1 validation failure, 2 invocation/tool failure (ADR 0004). JSON reports MUST preserve warnings separately.

12. Portability and exclusions

A normalized JSON graph MUST retain metadata, body, source path, source hash, and explicit edges; serialization MUST preserve unknown namespaced extensions. The interchange form is the export contract: its envelope, its optional evidence, knowledge, impact and ownership reports, what it withholds, and what a consumer checks before importing it. Round trips MUST preserve semantics, not YAML formatting. Generated inverses MUST be marked derived. Importers for issue trackers/ReqIF/OSLC are later adapters and MUST report lossy mappings. Tickets describe changes; product artifacts describe ongoing behavior.

v0.2 does not mandate a database, hosted service, test framework, cloud, commercial product, or universal AI correctness score. It does not assert that documented intent and production reality can be equated by static validation.