@rasensio/aidlc-content 1.10.6 → 1.11.0

package/dist/glossary.d.ts

@@ -0,0 +1,20 @@
+import type { GlossaryTerm } from './types.js';
+/**
+ * Load every canonical vocabulary definition.
+ *
+ * Read from the content package, never from a project — see `GlossaryTerm` and
+ * plain-language-vocabulary DD-2 for why the glossary is deliberately not
+ * installable. Both consumers call this: the CLI resolves `{{glossary:<term>}}`
+ * placeholders in skill bodies with it, and the website renders `/docs/glossary`
+ * from it at build. One source, two consumers, no copy.
+ */
+export declare function loadGlossary(): GlossaryTerm[];
+/**
+ * Look one term up by its canonical key.
+ *
+ * Matching is case-insensitive on the key so that a placeholder written
+ * `{{glossary:Instance}}` resolves; the returned definition is always the
+ * canonical text.
+ */
+export declare function getGlossaryTerm(term: string): GlossaryTerm | undefined;
+//# sourceMappingURL=glossary.d.ts.map

package/dist/glossary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glossary.d.ts","sourceRoot":"","sources":["../src/glossary.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAS/C;;;;;;;;GAQG;AACH,wBAAgB,YAAY,IAAI,YAAY,EAAE,CAI7C;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAGtE"}

package/dist/glossary.js

@@ -0,0 +1,32 @@
+import { fileURLToPath } from 'node:url';
+import { resolve, dirname } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+const CONTENT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const GLOSSARY_PATH = resolve(CONTENT_ROOT, 'glossary.yaml');
+/**
+ * Load every canonical vocabulary definition.
+ *
+ * Read from the content package, never from a project — see `GlossaryTerm` and
+ * plain-language-vocabulary DD-2 for why the glossary is deliberately not
+ * installable. Both consumers call this: the CLI resolves `{{glossary:<term>}}`
+ * placeholders in skill bodies with it, and the website renders `/docs/glossary`
+ * from it at build. One source, two consumers, no copy.
+ */
+export function loadGlossary() {
+    const raw = readFileSync(GLOSSARY_PATH, 'utf8');
+    const parsed = parseYaml(raw);
+    return parsed?.terms ?? [];
+}
+/**
+ * Look one term up by its canonical key.
+ *
+ * Matching is case-insensitive on the key so that a placeholder written
+ * `{{glossary:Instance}}` resolves; the returned definition is always the
+ * canonical text.
+ */
+export function getGlossaryTerm(term) {
+    const wanted = term.trim().toLowerCase();
+    return loadGlossary().find((t) => t.term.toLowerCase() === wanted);
+}
+//# sourceMappingURL=glossary.js.map

package/dist/glossary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glossary.js","sourceRoot":"","sources":["../src/glossary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAG1C,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAC5E,MAAM,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,eAAe,CAAC,CAAC;AAM7D;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,GAAG,GAAG,YAAY,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAwB,CAAC;IACrD,OAAO,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACzC,OAAO,YAAY,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,CAAC;AACrE,CAAC"}

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { loadSkills, getSkill } from './skills.js';
 export { loadTemplates, getTemplate } from './templates.js';
 export { loadGuidance } from './guidance.js';
+export { loadGlossary, getGlossaryTerm } from './glossary.js';
 export { loadCapabilities, getCapabilityMap } from './capabilities.js';
 export { loadPhases, getPhase } from './phases.js';
 export { loadTutorials, getTutorial, parseTutorialSource } from './tutorials.js';
-export type { Skill, WorkflowTemplate, GuidanceLayer, CapabilityMap, PhaseDefinition, CodeSample, ContentReference, TutorialStep, Tutorial } from './types.js';
+export type { Skill, WorkflowTemplate, GuidanceLayer, GlossaryTerm, CapabilityMap, PhaseDefinition, CodeSample, ContentReference, TutorialStep, Tutorial } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACjF,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACjF,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 export { loadSkills, getSkill } from './skills.js';
 export { loadTemplates, getTemplate } from './templates.js';
 export { loadGuidance } from './guidance.js';
+export { loadGlossary, getGlossaryTerm } from './glossary.js';
 export { loadCapabilities, getCapabilityMap } from './capabilities.js';
 export { loadPhases, getPhase } from './phases.js';
 export { loadTutorials, getTutorial, parseTutorialSource } from './tutorials.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/types.d.ts

@@ -19,6 +19,32 @@ export interface GuidanceLayer {
     filename: string;
     body: string;
 }
+/**
+ * One canonical vocabulary definition.
+ *
+ * The glossary is the single source of every term's definition text
+ * (plain-language-vocabulary/AC-7). It is read from the content package and is
+ * deliberately never copied into a project's `.aidlc/` the way guidance layers
+ * are: guidance is project guidance users edit, framework vocabulary is not
+ * theirs to fork, and a copy is a thing that can drift
+ * (plain-language-vocabulary DD-2).
+ */
+export interface GlossaryTerm {
+    /** Canonical lowercase key, e.g. `instance`. Unique across the glossary. */
+    term: string;
+    /** One plain sentence. The only definition text that exists for this term. */
+    definition: string;
+    /**
+     * What a reader wrongly expects the word to mean.
+     *
+     * Presence of this field *is* the collision flag — there is no separate
+     * boolean, because two fields that must agree eventually disagree
+     * (plain-language-vocabulary DD-5). A term that already means something else
+     * in software needs its prior meaning contradicted, not merely supplemented:
+     * the reader does not experience confusion, they experience false confidence.
+     */
+    not?: string;
+}
 export interface CapabilityMap {
     platform: string;
     capabilities: Record<string, unknown>;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB"}

package/glossary.yaml

@@ -0,0 +1,96 @@
+# AIDLC canonical vocabulary.
+#
+# The single source of every term's definition text. Read from this package by
+# both consumers — the CLI resolves `{{glossary:<term>}}` placeholders in skill
+# bodies with it, and the website renders /docs/glossary from it at build. It is
+# deliberately NOT installed into a project's .aidlc/ the way guidance layers
+# are: guidance is project guidance users edit, framework vocabulary is not
+# theirs to fork, and a second copy is a thing that can drift.
+#
+# Schema (packages/content/src/types.ts, GlossaryTerm):
+#   term       canonical lowercase key, unique
+#   definition ONE plain sentence — this is the only definition text that exists
+#   not        optional; what a reader wrongly expects the word to mean
+#
+# `not` is present if and only if the term collides with an existing software
+# meaning. There is no separate boolean flag, because two fields that must agree
+# eventually disagree. A colliding term needs its prior meaning CONTRADICTED,
+# not merely supplemented — the reader does not experience confusion, they
+# experience false confidence, and discover the mismatch much later.
+#
+# Audience is a working developer comfortable with a terminal and git. Terms that
+# a developer picks up without help do not need an entry; terms that mislead one
+# do.
+
+terms:
+  # --- Colliding terms. These are why this glossary exists. ---
+
+  # Definitions avoid internal em-dashes on purpose: the rendered gloss already
+  # opens with `**term** — `, so a second dash inside the sentence reads as a
+  # stutter. Colons and commas carry the same structure without it.
+
+  - term: instance
+    definition: >-
+      one unit of work, such as a single feature or fix, with its own folder of
+      files under `.aidlc/state/` tracking how far it has got
+    not: >-
+      an instantiated object, a running server, or a copy of the application
+
+  - term: scope
+    definition: >-
+      which phases of the lifecycle apply to a piece of work: micro runs
+      implementation and testing only, standard starts at requirements, full
+      starts at ideation
+    not: >-
+      how large or how ambitious the change is
+
+  - term: claim
+    definition: >-
+      a lock saying which session is currently working on an instance, so two
+      sessions in one repository cannot tread on each other
+    not: >-
+      an assertion, a support ticket, or an expense claim
+
+  # --- Non-colliding terms. One sentence is enough; no correction needed. ---
+  #
+  # Ordered by measured traffic across the shipped skills (2026-08-27):
+  # template 46, artifact 44, retrospective 20, gate 19, entry criteria 8.
+  #
+  # `retrospective` is the borderline case. Outside this framework it usually
+  # names a meeting, which is arguably a collision — but the source idea
+  # classifies it as needing only a definition, on the grounds that a developer
+  # meets no *wrong* mental model, just an unfamiliar one. Followed deliberately;
+  # revisit if the term turns out to mislead.
+
+  - term: template
+    definition: >-
+      a named workflow that fixes which phases a piece of work runs through:
+      micro-task, bugfix, quick-feature, full-feature, or spike
+
+  - term: artifact
+    definition: >-
+      a document a phase is required to produce, such as requirements.md or
+      test-results.md, committed alongside the code it describes
+
+  - term: retrospective
+    definition: >-
+      a short written review captured when an instance finishes, which appends
+      durable lessons to the guidance layer for the next instance to read
+
+  - term: gate
+    definition: >-
+      a check that must pass before work moves to the next phase, run by
+      `aidlc gate` in CI or by `aidlc transition` locally
+
+  - term: phase
+    definition: >-
+      one named step of the lifecycle, such as requirements or implementation,
+      each with its own conditions for starting and for being finished
+
+  - term: entry criteria
+    definition: >-
+      what must already be true before a phase is allowed to start
+
+  - term: exit criteria
+    definition: >-
+      what must be true before a phase can be called finished

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.10.6",
+  "version": "1.11.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,7 +18,8 @@
     "guidance/",
     "capabilities/",
     "phases/",
-    "tutorials/"
+    "tutorials/",
+    "glossary.yaml"
   ],
   "engines": {
     "node": ">=18.0.0"

package/skills/00-overview.md

@@ -8,6 +8,19 @@ priority: 100
 
 You are operating within the AI Development Lifecycle (AIDLC) framework. This skill defines how you interact with lifecycle state and follow phase-driven development.
 
+## The words this framework uses
+
+Three of these already mean something else in software, so read those definitions even if the word looks familiar — that is where the expensive misunderstandings come from.
+
+- {{glossary:instance}}
+- {{glossary:scope}}
+- {{glossary:claim}}
+- {{glossary:phase}}
+- {{glossary:artifact}}
+- {{glossary:gate}}
+- {{glossary:template}}
+- {{glossary:retrospective}}
+
 ## Lifecycle Phases
 
 The AIDLC defines seven ordered phases. Not all apply to every task:
@@ -78,7 +91,7 @@ All state lives in `.aidlc/state/<instance-name>/`. Read and write state as foll
 
 ### Writing State
 
-1. **Before mutating state**, check for an existing Instance_Claim. Claims live in `<git-common-dir>/aidlc/claims/<instance>.yaml` (resolve via `git rev-parse --git-common-dir`) so every worktree of the repo sees the same claims; outside a git repo (or on instances not yet migrated) the claim is the `claim:` field in `instance.yaml`. If another session holds a non-stale claim, warn and request override confirmation.
+1. **Before mutating state**, check whether another session already holds a claim on the instance. Claims live in `<git-common-dir>/aidlc/claims/<instance>.yaml` (resolve via `git rev-parse --git-common-dir`) so every worktree of the repo sees the same claims; outside a git repo (or on instances not yet migrated) the claim is the `claim:` field in `instance.yaml`. If another session holds a non-stale claim, warn and request override confirmation.
 2. Claim with `aidlc claim <instance>` (release with `aidlc release <instance>`) — it writes the claim file and appends the claim event to `sessions.ndjson` in one step. Without the CLI, do both writes yourself: write the claim file (fields: `session`, `claimed_at`, `id_source`, optional `renewed_at`/`worktree_path`), then append `{"event":"claim|release","session_id":"...","id_source":"agent","agent":"<platform>","timestamp":"<ISO 8601 UTC>"}` to `.aidlc/state/<instance>/sessions.ndjson`. Never rewrite that file — append only. If the CLI warns your claim is near timeout, run `aidlc claim --renew <instance>`. Renew at every phase transition and before long-running operations — a claim older than `claim_timeout_minutes` counts as stale.
 3. Update phase state files as you produce artifacts.
 4. Append a transition record to `transitions.log` only on successful phase transitions. When completing a phase, set `metrics.elapsed_seconds` in its `phase-<name>.yaml` from `entered_at` → `completed_at` — cost and time reports read it.
@@ -143,7 +156,7 @@ On each lifecycle event — `on-instance-start`, `on-phase-enter`, `on-phase-exi
 
 ## User Input Protocol (Inbox)
 
-When a phase needs substantial input from the user — open decisions, structured requirements, extensive details — write an Input_File to `.aidlc/inbox/` instead of asking many sequential chat questions or scattering files in ad-hoc locations (`temp/`, project root):
+When a phase needs substantial input from the user — open decisions, structured requirements, extensive details — write an input file to `.aidlc/inbox/` instead of asking many sequential chat questions or scattering files in ad-hoc locations (`temp/`, project root):
 
 1. Name the file `<instance>-<topic>.md` (e.g. `local-knowledge-graph-open-decisions.md`).
 2. Give each question its own section: plain-language background first (assume the user has not read the underlying spec), then the options as `- [ ]` checkboxes with trade-offs spelled out. Mark your recommendation.
@@ -177,5 +190,5 @@ Never store credentials, tokens, or secrets in state files or artifacts.
 ## Token Efficiency
 
 - Read compact state files, not full artifacts, to determine progress
-- Use Artifact_Summaries (`<artifact>.summary.md`) when available
+- Use artifact summaries (`<artifact>.summary.md`) when available
 - Load only the skill for the current phase, not all skills at once

package/skills/01-getting-started.md

@@ -13,6 +13,8 @@ Before responding with this skill, check whether `.aidlc/context/` exists and co
 
 ## When to Activate
 
+> {{glossary:template}}
+
 Respond using this skill when the user asks any of the following:
 - "How do I get started?"
 - "How do I fix a bug?"
@@ -30,6 +32,8 @@ All lifecycle work runs on instances — YAML state under `.aidlc/state/<name>/`
 
 ### "How do I fix a bug?"
 
+> {{glossary:instance}}
+
 1. Create a lifecycle instance from the `bugfix` template (see "Creating an Instance" in **aidlc-overview**).
 2. This gives a focused workflow: reproduce the bug → fix it → test it → deploy. The bugfix template skips the design phase and requires a `reproduction.md` artifact first.
 3. Follow **aidlc-continue** at any point to pick up the next step.
@@ -95,6 +99,8 @@ If not installed yet, run `npx @rasensio/aidlc init` in a terminal. Installation
 
 ## Choosing the Right Template
 
+> {{glossary:scope}}
+
 | You want to... | Use this template | Scope |
 |---------------|-------------------|-------|
 | Fix a bug | `bugfix` | Standard (no design) |

package/skills/03-entry-point.md

@@ -20,6 +20,10 @@ If `.aidlc/context/` does not exist or contains no `.md` files, defer to the **a
 
 ## Step 1 — Read State
 
+> {{glossary:instance}}
+> {{glossary:claim}}
+> {{glossary:template}}
+
 1. List the directories under `.aidlc/state/`. Each directory is a lifecycle instance.
 2. For each instance, read `instance.yaml` (current phase, template, scope, claim) and the `phase-<name>.yaml` files to compute completion (complete artifacts ÷ total required artifacts).
 3. Read `.aidlc/config.yaml` for project defaults (scope, template) if present.

package/skills/04-idea-capture.md

@@ -12,6 +12,8 @@ native_mode_hint:
 ---
 # Idea Capture and Backlog
 
+> {{glossary:instance}}
+
 `.aidlc/ideas/` is a first-class inbox, independent of every lifecycle phase. Ideas are captured cheaply now and converted into instances later. Capture is legal at any moment: mid-implementation on another instance, from a second session, or with no instance at all.
 
 ## Idea File Format
@@ -50,6 +52,8 @@ List `.aidlc/ideas/*.md` reading only frontmatter and the `# Idea:` title line
 
 Promotion is where the backlog meets the lifecycle:
 
+> {{glossary:scope}}
+
 1. If the idea's `depends_on` names ideas that are still `raw`, say so and confirm before proceeding — promoting out of order is allowed but should be deliberate.
 2. Choose a template and scope as usual (defaults from `.aidlc/config.yaml`; see **aidlc-getting-started**).
 3. Create the instance per "Creating an Instance" in **aidlc-overview** — including firing `on-instance-start` lifecycle actions.

package/skills/10-ideation.md

@@ -12,6 +12,8 @@ Explore the problem space before committing to a solution. Define what we are bu
 
 ## Entry Criteria
 
+> {{glossary:scope}}
+
 - A lifecycle instance has been created with a Full scope
 - The instance is claimed by this session
 
@@ -26,7 +28,9 @@ and open questions.
 
 ## Instructions
 
-1. **Consult the knowledge graph first.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase ideation` before exploring the codebase — the graph is the first source of understanding; re-explore only what it doesn't cover. Also read all active Guidance_Layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
+> {{glossary:artifact}}
+
+1. **Consult the knowledge graph first.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase ideation` before exploring the codebase — the graph is the first source of understanding; re-explore only what it doesn't cover. Also read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
 2. **Clarify the problem.** Ask the user what they want to build and why. Identify the core need vs. nice-to-haves.
 3. **Explore constraints.** Document: timeline, technical constraints, platform limitations, team size, budget considerations.
 4. **Generate options.** Propose 2-3 approaches. For each, note trade-offs (complexity, time, risk).

package/skills/20-requirements.md

@@ -12,6 +12,8 @@ Translate the ideation output (or the user's direct request) into precise, testa
 
 ## Entry Criteria
 
+> {{glossary:scope}}
+
 - Ideation phase complete (Full scope) OR instance created with Standard scope
 - The instance is claimed by this session
 
@@ -21,7 +23,9 @@ Translate the ideation output (or the user's direct request) into precise, testa
 
 ## Instructions
 
-1. **Gather requirements.** If a Full scope, read the ideation phase's artifact for context (`idea.md` for the feature templates, `research-question.md` for `spike`; `phase-ideation.yaml` names it). Otherwise, ask the user to describe desired behavior. Read all active Guidance_Layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
+> {{glossary:artifact}}
+
+1. **Gather requirements.** If a Full scope, read the ideation phase's artifact for context (`idea.md` for the feature templates, `research-question.md` for `spike`; `phase-ideation.yaml` names it). Otherwise, ask the user to describe desired behavior. Read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
 2. **Write user stories.** Use the format: "As a [role], I want [capability], so that [benefit]."
 3. **Define acceptance criteria.** Each criterion must be:
    - Specific and unambiguous
@@ -30,7 +34,7 @@ Translate the ideation output (or the user's direct request) into precise, testa
    - **Identified**: write every criterion as a list item `- AC-<n>: <text>` (bold variants `- **AC-<n>**: ...` and `- **AC-<n>:** ...` are also valid). Assign `AC-1`, `AC-2`, ... sequentially. IDs are never renumbered or reused — an amended criterion keeps its meaning or is retired: mark it `- AC-<n> (retired YYYY-MM-DD, superseded by AC-<m>): <text>` and issue a new ID. The testing-phase gate parses these IDs and fails on any active criterion without a referencing test.
 4. **Set scope boundaries.** Explicitly state what is NOT included.
 5. **Non-functional requirements.** Address performance, security, accessibility, and compatibility where relevant.
-6. **For complex input or open decisions**: If requirements are extensive, or unresolved decisions block the draft, create an Input_File in `.aidlc/inbox/` following the User Input Protocol in **aidlc-overview**, rather than asking many sequential questions. Prefer drafting `requirements.md` early with unresolved points marked as explicit decision blocks — users decide better reacting to a concrete draft than answering abstract questions.
+6. **For complex input or open decisions**: If requirements are extensive, or unresolved decisions block the draft, create an input file in `.aidlc/inbox/` following the User Input Protocol in **aidlc-overview**, rather than asking many sequential questions. Prefer drafting `requirements.md` early with unresolved points marked as explicit decision blocks — users decide better reacting to a concrete draft than answering abstract questions.
 
 ## Bugfix Reproduction (bugfix template)
 

package/skills/30-design.md

@@ -12,6 +12,8 @@ Produce a technical design that satisfies the requirements. Define architecture,
 
 ## Entry Criteria
 
+> {{glossary:instance}}
+
 - Requirements phase complete
 - The instance is claimed by this session
 
@@ -21,8 +23,10 @@ Produce a technical design that satisfies the requirements. Define architecture,
 
 ## Instructions
 
+> {{glossary:gate}}
+
 1. **Review requirements.** Read `requirements.md` (or its summary if one exists). Identify the key technical challenges. When requirements carry `AC-n` IDs, note in each design section which criteria it addresses — that linkage is what reviewers and the testing phase trace against.
-2. **Consult the knowledge graph.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase design` for existing architecture, decisions, and conventions before re-deriving them from code. Also read all active Guidance_Layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
+2. **Consult the knowledge graph.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase design` for existing architecture, decisions, and conventions before re-deriving them from code. Also read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
 3. **Define architecture.** Describe the high-level structure: components, their responsibilities, and how they communicate.
 4. **Specify interfaces.** For each component boundary, define the contract (function signatures, API shapes, data types).
 5. **Data flow.** Document how data moves through the system — inputs, transformations, storage, outputs.

package/skills/40-implementation.md

@@ -12,6 +12,8 @@ Produce working code that satisfies the design and requirements. Follow project
 
 ## Entry Criteria
 
+> {{glossary:scope}}
+
 - Design phase complete (Full/Standard scope) OR instance created with Micro scope (task description + criteria exist)
 - The instance is claimed by this session
 
@@ -22,8 +24,10 @@ Produce working code that satisfies the design and requirements. Follow project
 
 ## Instructions
 
+> {{glossary:gate}}
+
 1. **Load context.** Read `.aidlc/context/style-guide.md` and `.aidlc/context/architecture.md` if they exist. Match the project's established patterns. If the project has a knowledge graph (`.aidlc/knowledge/` exists), also run `aidlc knowledge context --scope phase --phase implementation` and query it (`aidlc knowledge query <term>`) before re-exploring code it already describes.
-2. **Load guidance.** Read all active Guidance_Layers from `.aidlc/guidance/index.yaml`. Apply their rules during implementation.
+2. **Load guidance.** Read all active guidance layers from `.aidlc/guidance/index.yaml`. Apply their rules during implementation.
 3. **Execute the task breakdown.** When the instance has a `tasks.md` (produced in Design for full/quick-feature scope), read it and execute tasks in order: complete a task, then mark its checkbox `[x]` as part of the same work unit — never batch checkbox updates for later. A task that should not be done is deferred in place (`- [>] T<n>: <title> (deferred YYYY-MM-DD: <reason>)`) with a dated reason, never skipped silently or deleted; the implementation→testing gate blocks on open tasks. For bugfix scope, create the optional `tasks.md` at implementation start when the fix spans more than one commit-sized unit. For Micro scope, reference the task description and acceptance criteria directly — no task file.
 4. **Write code.** Follow the design interfaces. Match existing code style (naming, formatting, error handling patterns).
 5. **Handle sensitive operations.** Before executing any of the following, describe the action and wait for explicit user confirmation:

package/skills/50-testing.md

@@ -24,7 +24,10 @@ Verify that the implementation satisfies all acceptance criteria. Produce eviden
 
 ## Instructions
 
-1. **Review acceptance criteria.** Read `requirements.md` (or task description for Micro scope). Each criterion needs at least one test. Read all active Guidance_Layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
+> {{glossary:gate}}
+> {{glossary:artifact}}
+
+1. **Review acceptance criteria.** Read `requirements.md` (or task description for Micro scope). Each criterion needs at least one test. Read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
 2. **Write automated tests.** Follow the project's existing test patterns:
    - Unit tests for pure logic and edge cases
    - Integration tests for component interactions

package/skills/60-deployment.md

@@ -12,7 +12,7 @@ Prepare and execute the release. Ensure all preceding phases are complete, all g
 
 ## Entry Criteria
 
-- All preceding required phases have status `complete` in the State_Store
+- All preceding required phases have status `complete` in `.aidlc/state/<instance>/`
 - Testing phase complete with all tests passing
 - Security sign-off recorded (if a security review phase is configured)
 - The instance is claimed by this session
@@ -26,6 +26,9 @@ deployment checklist.
 
 ## Instructions
 
+> {{glossary:gate}}
+> {{glossary:artifact}}
+
 1. **Validate readiness.** Check the phase state files: every preceding required phase must be complete (all required artifacts `complete`). If any gate fails, address the gap before proceeding. (CLI shortcut: `aidlc gate <instance> deployment` — the phase name is the second argument, not the first.)
 2. **Write release plan.** Document in the phase's required artifact (see Required Artifacts above):
    - What is being deployed (version, changes summary)

package/skills/70-maintenance.md

@@ -12,6 +12,8 @@ Ensure the deployed feature remains healthy. Update documentation, address feedb
 
 ## Entry Criteria
 
+> {{glossary:instance}}
+
 - Deployment phase complete
 - The instance is claimed by this session
 
@@ -56,6 +58,8 @@ You MUST describe the change, confirm the target environment, and wait for expli
 
 ## Completion
 
+> {{glossary:retrospective}}
+
 For maintenance-terminal instances the completion moment already fired on maintenance *entry* (see **aidlc-deployment**) — entering this phase means the instance is complete and its retrospective has run or is pending. Do not fire `on-instance-complete` again when closing the phase.
 
 When exit criteria are met, update `phase-maintenance.yaml` status to `complete` and append a transition record to `transitions.log`. If no retrospective exists for the instance (legacy completion paths), offer to run the **aidlc-retrospective** skill.

package/skills/80-review.md

@@ -11,6 +11,8 @@ priority: 60
 
 Provide a structured, critical review of a lifecycle artifact from fresh context. Surface ambiguities, contradictions, missing edge cases, and risks before the artifact drives downstream work.
 
+> {{glossary:artifact}}
+
 ## Important
 
 You MUST perform this review with fresh eyes. If you authored the artifact being reviewed, delegate to a separate session or subagent. Self-review defeats the purpose.
@@ -70,7 +72,9 @@ reviewer: <session-id>
 
 ## Review Gate
 
-When a Workflow_Template configures an adversarial review gate for a phase, the phase transition is blocked until:
+> {{glossary:gate}}
+
+When a workflow template configures an adversarial review gate for a phase, the phase transition is blocked until:
 - A findings file exists for the phase's required artifacts
 - No finding with severity `critical` has status `open`
 

package/skills/81-continue.md

@@ -10,8 +10,12 @@ priority: 70
 
 Resume an in-progress lifecycle instance efficiently. Determine where work left off and continue from that exact point without re-reading full artifacts or re-explaining context.
 
+> {{glossary:instance}}
+
 ## Instructions
 
+> {{glossary:claim}}
+
 1. **Load state.** Read `.aidlc/state/<instance>/instance.yaml` to get:
    - Current phase
    - Template name
@@ -57,4 +61,4 @@ If continuation leads to a phase that involves sensitive operations (Deployment,
 
 - Do NOT re-read unchanged files from prior sessions
 - Use state fields to determine progress, not artifact content
-- Load Artifact_Summaries in place of full documents when summaries exist
+- Load artifact summaries in place of full documents when summaries exist

package/skills/82-add-action.md

@@ -1,6 +1,6 @@
 ---
 name: aidlc-add-action
-description: Translates natural language automation descriptions into Lifecycle_Action declarations
+description: Translates natural language automation descriptions into lifecycle action declarations
 phase: implementation
 priority: 55
 ---
@@ -8,7 +8,7 @@ priority: 55
 
 ## Purpose
 
-Help the user create Lifecycle_Actions from natural language descriptions. Translate intent into a concrete, validated `.aidlc/actions.yaml` entry.
+Help the user create lifecycle actions from natural language descriptions. Translate intent into a concrete, validated `.aidlc/actions.yaml` entry.
 
 ## Instructions
 

package/skills/83-add-skill.md

@@ -31,6 +31,8 @@ system; skills for repeatable operations of the system.*
 If the description is really a new capability — the system cannot do this yet, and doing it once requires
 building something — say so plainly and offer the alternative:
 
+> {{glossary:instance}}
+
 > "This sounds like a change to the system rather than a repeatable operation of it: <reason>. That
 > usually belongs in the lifecycle. I can capture it as an idea (`aidlc-idea`) or start an instance
 > instead. Or if you would rather have the skill anyway, say so and I will generate it."

package/skills/90-retrospective.md

@@ -11,6 +11,8 @@ trigger: When an instance reaches its completion moment, a retro-pending marker
 
 Close the feedback loop: when an instance completes, capture what the work taught us while it is fresh, and write durable lessons where the next instance will read them. This is the system-level quality mechanism — gates and reviews protect one instance; retrospectives make the next one start smarter.
 
+> {{glossary:instance}}
+
 ## When to Run
 
 - **At every instance's completion moment**, regardless of scope or template. The completion moment is the last applicable phase (template × scope) reaching complete — except when that phase is maintenance, where **entering** maintenance is the moment (maintenance is open-ended).
@@ -21,6 +23,8 @@ Run the retro **before** any completion cleanup (worktree removal, claim release
 
 ## Retro Flow
 
+> {{glossary:retrospective}}
+
 1. **Idempotency check.** If `retrospective.md` already exists in the instance state dir, offer to update or skip — never duplicate. A skip still removes the retro-pending marker.
 2. **Gather state.** Read `instance.yaml`, `phase-*.yaml`, and `transitions.log`. For the cost summary, prefer `aidlc cost <instance>` (it applies fidelity precedence); only read `costs.ndjson` raw when the CLI is unavailable, and mark that summary approximate. No cost data → omit the cost section entirely, never write zeros.
 3. **Ask — one round-trip.** Three questions in a single message: what surprised us? what would we do differently? what took longer than expected? For **Micro scope**, compress to one question: "anything surprising, worth doing differently, or slower than expected?" Declining the retro is fine: remove the marker, write nothing.