docs(spec): clarify claims carry one identifier in their file form#50
Conversation
There was a problem hiding this comment.
Pull request overview
This PR clarifies KP:1 claim identity semantics by stating that the bracketed [C…] token is the only identifier present in the canonical claims.md file form, and records the rationale as the first entry in the project’s decisions log.
Changes:
- Add an explicit clarification in
spec/CORE.md§6.1 thatclaims.mdcarries only one claim identifier ([C…]), and that operational index identifiers are not serialized into the pack. - Introduce
decisions/2026-06-22-claim-identity.mddocumenting the decision, options, and consequences.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| spec/CORE.md | Adds a clarifying note in §6.1 about single-identifier claim identity and links to the decision rationale. |
| decisions/2026-06-22-claim-identity.md | Adds a new decision record capturing the rationale and consequences for “one identifier per claim” in file form. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| **Claim ID:** `[C` + one or more digits + optional `-v` version suffix + `]`. Bold wrapping (`**[C001]**`) is optional syntactic sugar with no semantic meaning (AR-03). Zero-padding is conventional but not required (AR-01). IDs need not be sequential (AR-12). | ||
|
|
||
| **One identifier per claim.** The `[C…]` id is the claim's sole identifier within the pack — at once the reference target (for relations and evidence cross-references) and the human-readable display id. The file form carries no second, separate id. The globally unique `claim_id` used by operational indexes (STORAGE.md) is assigned when a pack is indexed, is derived from the pack, and is never serialized into `claims.md`. (See `decisions/2026-06-22-claim-identity.md`.) |
| (`→C002`, `⊗~C003`). There is no second id slot in the grammar. The globally unique | ||
| `claim_id` (ULID/UUIDv7) in STORAGE.md is an *operational* identifier for cross-pack | ||
| indexes — assigned at index time, derived from the pack, rebuildable — consistent with | ||
| the pack-as-master principle that no canonical knowledge lives only in an index. Carrying |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a5271d5a43
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| **Claim ID:** `[C` + one or more digits + optional `-v` version suffix + `]`. Bold wrapping (`**[C001]**`) is optional syntactic sugar with no semantic meaning (AR-03). Zero-padding is conventional but not required (AR-01). IDs need not be sequential (AR-12). | ||
|
|
||
| **One identifier per claim.** The `[C…]` id is the claim's sole identifier within the pack — at once the reference target (for relations and evidence cross-references) and the human-readable display id. The file form carries no second, separate id. The globally unique `claim_id` used by operational indexes (STORAGE.md) is assigned when a pack is indexed, is derived from the pack, and is never serialized into `claims.md`. (See `decisions/2026-06-22-claim-identity.md`.) |
There was a problem hiding this comment.
This clarification says the [C…] id is the target for “evidence cross-references,” but the format immediately below defines evidence references as E IDs in metadata position 3, and CORE §10 says evidence entries are referenced by ID from claims. As written, implementers could infer that claim IDs are valid evidence-reference targets, so this should be narrowed to claim-to-claim references/relations or explicitly define any evidence-to-claim back-reference behavior.
Useful? React with 👍 / 👎.
|
|
||
| **Claim ID:** `[C` + one or more digits + optional `-v` version suffix + `]`. Bold wrapping (`**[C001]**`) is optional syntactic sugar with no semantic meaning (AR-03). Zero-padding is conventional but not required (AR-01). IDs need not be sequential (AR-12). | ||
|
|
||
| **One identifier per claim.** The `[C…]` id is the claim's sole identifier within the pack — at once the reference target (for relations and evidence cross-references) and the human-readable display id. The file form carries no second, separate id. The globally unique `claim_id` used by operational indexes (STORAGE.md) is assigned when a pack is indexed, is derived from the pack, and is never serialized into `claims.md`. (See `decisions/2026-06-22-claim-identity.md`.) |
There was a problem hiding this comment.
This new sentence says the operational claim_id is “derived from the pack,” but the existing normative paragraph in the same section says storage-layer identifiers are non-wire and are not reconstructed from the serialized claim, and STORAGE.md’s reference schema describes claim_id as a ULID/UUIDv7. That leaves incompatible guidance for index rebuilds and round-trips, so clarify whether the operational ID is deterministic from pack contents (for example pack#C...) or an opaque out-of-band index key.
Useful? React with 👍 / 👎.
Note in CORE.md §6.1 that the [C…] id is a claim's sole identifier within the pack (both reference target and display id), and that the operational claim_id (STORAGE.md) is index-assigned, derived, and never serialized into claims.md. Record the rationale as the first decisions/ log entry. Co-Authored-By: Claude <noreply@anthropic.com>
tymofiy
force-pushed
the
spec/claim-identity-clarification
branch
from
a5271d5 to
02622d1
Compare
What
Clarify in CORE.md §6.1 that a claim carries a single identifier in its file form: the
[C…]id is the claim's sole identifier within the pack — at once the reference target (for relations and evidence cross-references) and the human-readable display id. The file form carries no second, separate id. The globally-uniqueclaim_idused by operational indexes (STORAGE.md) is assigned when a pack is indexed, is derived from the pack, and is never serialized intoclaims.md.Why
Removes ambiguity about whether claims carry a second, separate identifier in their serialized form, and records the rationale as the first entry in
decisions/.Scope
Documentation only — a clarifying note plus a decisions log entry. No normative requirement, schema, or conformance changes.