Skip to content

notations: add IDs and cross-references appendix#8

Merged
transitrix merged 1 commit into
mainfrom
task/13-ids-appendix
May 21, 2026
Merged

notations: add IDs and cross-references appendix#8
transitrix merged 1 commit into
mainfrom
task/13-ids-appendix

Conversation

@transitrix
Copy link
Copy Markdown
Owner

Summary

  • New notations/IDS_AND_REFERENCES.md defines the canonical ID grammar <TYPE>-[<middle segment(s)>-]<INTEGER>, documents the CAPABILITY V/H exception, enumerates the complete TYPE registry (element types + document-level prefixes), states uniqueness scope per TYPE, the cross-reference pattern, and a migration checklist for files still using old forms.
  • Eight specs (03, 04, 05, 06, 07, 09, 10, 11) gain a one-line link to the appendix in their References section.

Closes vkgeorgia/strategy#13.

Scope guard

Per the issue refinement, this PR produces only the new appendix file and adds a cross-link from each spec that references IDs. No other spec content changes; no example rewrites; no audit items.

Which specs are linked vs not

  • Linked (8): 03-fga, 04-goals, 05-capability-map, 06-process-map, 07-activities, 09-products, 10-applications, 11-scenarios.
  • Not linked, by design (3):
    • 01-bpmn uses only file-local labels (POOL, TASK, GW…), explicitly noted as out of scope in the appendix §3.3.
    • 02-fgca on main has no schema and therefore no IDs yet; it will gain the link as part of transitrix/methodology#7 which introduces its schema.
    • 08-blocks uses ASCII art with no element IDs.

Migration

The appendix carries a migration checklist documenting which existing files still use old ID forms (ACT-, CHG-, FAC-, CAP-, SCN-, integer-only IDs, zero-padded sequences). The migration itself is out of scope — per-notation follow-ups will do it gradually. The integer-IDs row in the FGCA example is already in flight via #7.

Test plan

  • notations/IDS_AND_REFERENCES.md exists with all seven sections (Grammar, Capability exception, TYPE registry, Uniqueness scope, Cross-references, Migration checklist, References).
  • Every listed spec contains exactly one new link to the appendix in its References section.
  • No links to the private vkgeorgia/strategy repo in any shipped file.
  • Existing References-section content untouched apart from the inserted line.

🤖 Generated with Claude Code

`notations/IDS_AND_REFERENCES.md` is the canonical place for the ID
grammar and TYPE registry used across all eleven notations. Before
this PR the rules were scattered: each spec invented its own style,
examples mixed integer IDs, abbreviated prefixes (ACT, CHG, FAC, CAP,
SCN), and zero-padded sequences; the same TYPE was sometimes written
several ways across files.

The appendix carries:

- The canonical grammar `<TYPE>-[<middle segment(s)>-]<INTEGER>`, with
  the rule that the terminal integer is positive, no leading zeros,
  and sorted numerically.
- The `CAPABILITY` exception (V/H diagram address replacing the
  terminal integer, depth capped at three levels).
- The complete TYPE registry — element types (FACTOR, GOAL, CHANGE,
  ACTIVITY, CAPABILITY, PROCESS, PRODUCT, APPLICATION, INTEGRATION,
  ROLE, UNIT, EMPLOYEE, SCENARIO) and document-level prefixes (FGCA,
  FGA, GOALS_TREE, …). BPMN file-local labels (POOL, TASK, GW, …) are
  explicitly out of scope.
- Uniqueness scope per TYPE.
- The cross-reference pattern (plural field → array of typed IDs).
- A migration checklist documenting which existing files still use old
  forms (ACT-, CHG-, FAC-, CAP-, SCN-, integer-only, zero-padded).
  Migration itself is out of scope per the issue refinement; per-
  notation follow-ups will do it gradually.

Eight specs (03, 04, 05, 06, 07, 09, 10, 11) gain a one-line link to
the appendix in their References section. 01-bpmn (file-local labels
only) and 08-blocks (no IDs) intentionally do not link. 02-fgca will
gain the link when its schema lands (#7 in flight).

Refs: vkgeorgia/strategy#13

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@transitrix transitrix merged commit 41584de into main May 21, 2026
2 checks passed
@transitrix transitrix deleted the task/13-ids-appendix branch May 21, 2026 09:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant