gcf-aif-ext 0.2.7 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.2.7",
+  "version": "0.4.0",
   "description": "Game Context Framework for AI Factory",
   "type": "module",
   "license": "MIT",

package/profiles/game.md

@@ -0,0 +1,68 @@
+---
+name: game
+description: The CNL-P profile of gcf/game.md — the vision, the scope and the milestones the design units are planned against.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: the body is flat and the document is named by its fixed path
+
+frontmatter_fields:
+- none: the file is a singleton at a fixed path and carries no machine fields
+
+lexicon_exempt:
+- none: nothing is exempt in the document that bounds the scope
+
+sections:
+- key: logline
+  form: scalar
+  required: yes
+  note: the game in one line
+
+- key: platforms
+  form: bullet-list
+  required: yes
+  note: platform and input, one per line
+
+- key: audience
+  form: bullet-list
+  required: yes
+  note: who plays, one group per line
+
+- key: references
+  form: bullet-list
+  required: no
+  note: "like X, not like Y", one reference per line
+
+- key: scope_in
+  form: bullet-list
+  required: yes
+  note: what the game holds
+
+- key: scope_out
+  form: bullet-list
+  required: yes
+  note: what the game does not hold, or not in this version
+
+- key: milestones
+  form: record-list
+  required: yes
+  record_keys: name, goal
+  optional_record_keys: content
+  note: the closed vocabulary of a unit's milestone field; content is a volume written as a comparison
+
+- key: provenance
+  form: record-list
+  required: no
+  record_keys: slot
+  optional_record_keys: src, quote, answer, assumed
+  note: per slot, a verbatim quote with its anchor when the file came from a GDD
+
+custom_sections:
+- none: a block that is not listed above belongs to a unit or to PILLARS.md
+
+enforcement:
+- `ai-factory gcf design check` resolves every unit's milestone against this file

package/profiles/glossary.md

@@ -0,0 +1,37 @@
+---
+name: glossary
+description: The CNL-P profile of gcf/glossary.md — one word per concept, the synonyms it forbids, and the project's own units of measure.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: the body is flat and the document is named by its fixed path
+
+frontmatter_fields:
+- none: the file is a singleton at a fixed path and carries no machine fields
+
+lexicon_exempt:
+- none: the glossary is the lexicon of the project
+
+sections:
+- key: terms
+  form: record-list
+  required: yes
+  record_keys: term, means
+  optional_record_keys: not
+  note: a term the human confirmed, what it means, and the words that may not name it
+
+- key: units
+  form: bullet-list
+  required: no
+  note: units of measure the project adds to the closed list, one per line as "<unit>: <what it measures>"
+
+custom_sections:
+- none: a block that is not listed above belongs to a unit
+
+enforcement:
+- `ai-factory gcf design check` refuses a forbidden synonym in gcf/design/ and in a card (M4)
+- quoted text is data: a GDD quote keeps the designer's own word

package/profiles/pillars.md

@@ -21,11 +21,12 @@ sections:
   form: record-list
   required: yes
   record_keys: statement, invariant, review_question
-  note: pillar count <= 7 and the token budget are enforced by the gcf audit core, not the checker
+  optional_record_keys: id
+  note: pillar count <= 7 and the token budget are enforced by the gcf audit core; id is the slug a design unit cites in pillars:
 
 custom_sections:
 - none: a pillar that needs more than its three keys is not a pillar yet
 
 enforcement:
-- `npx cnlp check`, over the file a `cnlp.config.json` corpus entry maps to this profile
+- `npx --yes cnlp-kit check`, over the file a `cnlp.config.json` corpus entry maps to this profile
 - `ai-factory gcf audit` checks the count and token budget

package/profiles/system.md

@@ -52,5 +52,5 @@ custom_sections:
 - none: a fact that fits no block above belongs to code or to a card, not here
 
 enforcement:
-- `npx cnlp check`, over the files a `cnlp.config.json` corpus entry maps to this profile
+- `npx --yes cnlp-kit check`, over the files a `cnlp.config.json` corpus entry maps to this profile
 - the gcf P2 linter adds its own forbidden-content patterns on top in the pre-commit hook

package/profiles/unit-constraint.md

@@ -0,0 +1,52 @@
+---
+name: unit-constraint
+description: The CNL-P profile of a GCF design unit of type constraint — a platform, performance or size threshold, accepted by a measurement.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: the body is flat; the `## <id>` line and the header fields above the blocks name the unit
+
+frontmatter_fields:
+- none: a constraint never becomes a card, so its header lives above the blocks in design/
+
+lexicon_exempt:
+- none: every block is read when the constraint is planned and measured
+
+sections:
+- key: threshold
+  form: bullet-list
+  required: yes
+  note: one comparison per line, "<subject> <op> <value> <unit>"
+
+- key: measure
+  form: bullet-list
+  required: yes
+  note: how the threshold is measured and on what - device, build, scene
+
+- key: tuning
+  form: bullet-list
+  required: no
+  note: work stage only - one verdict remark per tune, read before the rebuild
+
+- key: notes
+  form: bullet-list
+  required: no
+  note: work stage only - the operator's answers and delivered files, one per unblock
+
+- key: provenance
+  form: record-list
+  required: no
+  record_keys: slot
+  optional_record_keys: src, quote, answer, assumed
+  note: per slot, a verbatim quote with its anchor, a human answer, or a D2 assumption
+
+custom_sections:
+- none: a block that is not listed above is prose looking for a home
+
+enforcement:
+- `ai-factory gcf design check`, over the units in gcf/design/
+- the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding

package/profiles/unit-entity.md

@@ -0,0 +1,48 @@
+---
+name: unit-entity
+description: The CNL-P profile of a GCF design unit of type entity — the shape of a data noun before code holds it.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: the body is flat; the `## <id>` line and the header fields above the blocks name the unit
+
+frontmatter_fields:
+- none: an entity never becomes a card, so its header lives above the blocks in design/
+
+lexicon_exempt:
+- none: every block is read when the entity is planned and coded
+
+sections:
+- key: fields
+  form: record-list
+  required: yes
+  record_keys: name, holds
+  note: one record per field - what it holds, never its allowed values, which belong to a rule
+
+- key: tuning
+  form: bullet-list
+  required: no
+  note: work stage only - one verdict remark per tune, read before the rebuild
+
+- key: notes
+  form: bullet-list
+  required: no
+  note: work stage only - the operator's answers and delivered files, one per unblock
+
+- key: provenance
+  form: record-list
+  required: no
+  record_keys: slot
+  optional_record_keys: src, quote, answer, assumed
+  note: per slot, a verbatim quote with its anchor, a human answer, or a D2 assumption
+
+custom_sections:
+- none: a block that is not listed above is prose looking for a home
+
+enforcement:
+- `ai-factory gcf design check`, over the units in gcf/design/
+- the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding

package/profiles/unit-mechanic.md

@@ -0,0 +1,111 @@
+---
+name: unit-mechanic
+description: The CNL-P profile of a GCF design unit of type mechanic — one body for its section in design/<system>.md and for its card in cards/<id>.md.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: the body is flat; in design/ the `## <id>` line and the header fields above the blocks name the unit, in cards/ the frontmatter does
+
+frontmatter_fields:
+- schema
+- id
+- type
+- title
+- status
+- system
+- depends
+- pillars
+- source
+- reopens
+- tune_count
+- built_at
+- created
+
+lexicon_exempt:
+- none: every block is read when the unit is planned, built or played
+
+sections:
+- key: intent
+  form: bullet-list
+  required: yes
+  note: why the mechanic exists, in the designer's words
+
+- key: behavior
+  form: record-list
+  required: yes
+  record_keys: input, state, feedback
+  note: one record per chain - player input, the state it changes, the feedback the player sees
+
+- key: refusal
+  form: bullet-list
+  required: yes
+  note: what happens when the action is not allowed - no resource, invalid target, already active
+
+- key: boundaries
+  form: bullet-list
+  required: yes
+  note: zero, maximum, overflow, simultaneity; an exact limit is a comparison at the end of its line
+
+- key: persistence
+  form: scalar
+  required: yes
+  note: what survives a reload, a session or a match
+
+- key: feel_like
+  form: scalar
+  required: yes
+  note: the comparison "like X, not like Y"
+
+- key: feel
+  form: record-list
+  required: yes
+  record_keys: name, envelope
+  note: one record per tunable value; an envelope "a..b <unit>" is the only legal range of intent
+
+- key: contract
+  form: bullet-list
+  required: yes
+  note: card stage, absent in design/ - paths and entry points, never member lists or values; an architecture rule is a constraint
+
+- key: interactions
+  form: bullet-list
+  required: yes
+  note: card stage, absent in design/ - "<other id>: how the two cross", one line per crossing
+
+- key: constraints
+  form: bullet-list
+  required: yes
+  note: negative constraints, one prohibition per line, checkable by an analyzer or a reviewer
+
+- key: miss_criterion
+  form: scalar
+  required: yes
+  note: the one question the game in hand answers; the human answers it at the verdict
+
+- key: tuning
+  form: bullet-list
+  required: no
+  note: work stage only - one verdict remark per tune, read before the rebuild
+
+- key: notes
+  form: bullet-list
+  required: no
+  note: work stage only - the operator's answers and delivered files, one per unblock
+
+- key: provenance
+  form: record-list
+  required: no
+  record_keys: slot
+  optional_record_keys: src, quote, answer, assumed
+  note: per slot, a verbatim quote with its anchor, a human answer, or a D2 assumption
+
+custom_sections:
+- none: a block that is not listed above is prose looking for a home
+
+enforcement:
+- `ai-factory gcf design check`, over the units in gcf/design/ and the cards in gcf/cards/
+- the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding

package/profiles/unit-resource.md

@@ -0,0 +1,91 @@
+---
+name: unit-resource
+description: The CNL-P profile of a GCF design unit of type resource — an economy resource with its sources and sinks, in design/<system>.md and as a card.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: the body is flat; in design/ the `## <id>` line and the header fields above the blocks name the unit, in cards/ the frontmatter does
+
+frontmatter_fields:
+- schema
+- id
+- type
+- title
+- status
+- system
+- depends
+- pillars
+- source
+- reopens
+- tune_count
+- built_at
+- created
+
+lexicon_exempt:
+- none: every block is read when the unit is planned, built or played
+
+sections:
+- key: intent
+  form: bullet-list
+  required: yes
+  note: why the resource exists, in the designer's words
+
+- key: sources
+  form: record-list
+  required: yes
+  record_keys: name, rate
+  note: where the player gets the resource; a rate is an envelope "a..b <unit>" or a comparison
+
+- key: sinks
+  form: record-list
+  required: yes
+  record_keys: name, rate
+  note: where the player spends the resource; a rate is an envelope "a..b <unit>" or a comparison
+
+- key: contract
+  form: bullet-list
+  required: yes
+  note: card stage, absent in design/ - paths and entry points, never member lists or values
+
+- key: interactions
+  form: bullet-list
+  required: yes
+  note: card stage, absent in design/ - "<other id>: how the two cross", one line per crossing
+
+- key: constraints
+  form: bullet-list
+  required: yes
+  note: negative constraints on the economy, one prohibition per line
+
+- key: miss_criterion
+  form: scalar
+  required: yes
+  note: the one question the game in hand answers about the economy
+
+- key: tuning
+  form: bullet-list
+  required: no
+  note: work stage only - one verdict remark per tune, read before the rebuild
+
+- key: notes
+  form: bullet-list
+  required: no
+  note: work stage only - the operator's answers and delivered files, one per unblock
+
+- key: provenance
+  form: record-list
+  required: no
+  record_keys: slot
+  optional_record_keys: src, quote, answer, assumed
+  note: per slot, a verbatim quote with its anchor, a human answer, or a D2 assumption
+
+custom_sections:
+- none: a block that is not listed above is prose looking for a home
+
+enforcement:
+- `ai-factory gcf design check`, over the units in gcf/design/ and the cards in gcf/cards/
+- the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding

package/profiles/unit-rule.md

@@ -0,0 +1,52 @@
+---
+name: unit-rule
+description: The CNL-P profile of a GCF design unit of type rule — an invariant of the rules or the structure, accepted by a test.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: the body is flat; the `## <id>` line and the header fields above the blocks name the unit
+
+frontmatter_fields:
+- none: a rule never becomes a card, so its header lives above the blocks in design/
+
+lexicon_exempt:
+- none: every block is read when the rule is planned and tested
+
+sections:
+- key: statement
+  form: bullet-list
+  required: yes
+  note: the invariant, one per line; an exact value is a comparison at the end of its line
+
+- key: check
+  form: bullet-list
+  required: yes
+  note: what accepts the rule without a human playing - a test, an analyzer, a device run
+
+- key: tuning
+  form: bullet-list
+  required: no
+  note: work stage only - one verdict remark per tune, read before the rebuild
+
+- key: notes
+  form: bullet-list
+  required: no
+  note: work stage only - the operator's answers and delivered files, one per unblock
+
+- key: provenance
+  form: record-list
+  required: no
+  record_keys: slot
+  optional_record_keys: src, quote, answer, assumed
+  note: per slot, a verbatim quote with its anchor, a human answer, or a D2 assumption
+
+custom_sections:
+- none: a block that is not listed above is prose looking for a home
+
+enforcement:
+- `ai-factory gcf design check`, over the units in gcf/design/
+- the gcf pre-commit hook runs the same check and refuses a commit with a blocking finding

package/schemas/item.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/VirtualMaestro/GCF/schemas/item.schema.json",
+  "title": "GCF work item frontmatter (schema 3)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "id", "type", "gate", "status", "created"],
+  "definitions": {
+    "slug": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+    "slugOrNull": {
+      "anyOf": [{ "type": "null" }, { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }]
+    },
+    "textOrNull": {
+      "anyOf": [{ "type": "null" }, { "type": "string", "pattern": "\\S" }]
+    },
+    "slugList": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }
+    },
+    "summary": { "type": "string", "pattern": "\\S", "maxLength": 250 }
+  },
+  "properties": {
+    "schema": { "const": 3 },
+    "id": { "$ref": "#/definitions/slug" },
+    "type": {
+      "enum": [
+        "feature",
+        "mechanic",
+        "resource",
+        "rule",
+        "constraint",
+        "entity",
+        "tech",
+        "bug",
+        "spike",
+        "asset",
+        "content",
+        "perf",
+        "release"
+      ]
+    },
+    "gate": { "enum": ["verdict", "auto", "decision"] },
+    "title": { "type": "string", "pattern": "\\S" },
+    "status": {
+      "enum": ["ready", "awaiting-verdict", "awaiting-decision", "blocked", "parked", "unplayed"]
+    },
+    "parent": { "$ref": "#/definitions/slugOrNull" },
+    "children": { "$ref": "#/definitions/slugList" },
+    "system": { "$ref": "#/definitions/slugList" },
+    "depends": { "$ref": "#/definitions/slugList" },
+    "pillars": { "$ref": "#/definitions/slugList" },
+    "source": { "type": "string", "pattern": "^(GDD#[A-Za-z0-9_-]+|manual)$" },
+    "reopens": { "$ref": "#/definitions/slugOrNull" },
+    "milestone": { "$ref": "#/definitions/slugOrNull" },
+    "parallel": { "enum": ["ok", "serial"] },
+    "plan": { "$ref": "#/definitions/textOrNull" },
+    "tune_count": { "type": "integer", "minimum": 0 },
+    "severity": {
+      "anyOf": [{ "type": "null" }, { "enum": ["critical", "high", "medium", "low"] }]
+    },
+    "blocked": { "$ref": "#/definitions/textOrNull" },
+    "since": {
+      "anyOf": [{ "type": "null" }, { "type": "string", "pattern": "^[0-9a-f]{7,64}$" }]
+    },
+    "frozen": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "live": {
+      "anyOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["none"],
+          "properties": { "none": { "type": "string", "pattern": "\\S" } }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["changes"],
+          "properties": {
+            "changes": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["id", "change"],
+                "properties": {
+                  "id": { "$ref": "#/definitions/slug" },
+                  "change": { "enum": ["added", "modified", "removed"] },
+                  "summary": { "$ref": "#/definitions/summary" },
+                  "refs": { "type": "string", "pattern": "\\S" }
+                },
+                "if": { "properties": { "change": { "enum": ["added", "modified"] } } },
+                "then": { "required": ["summary"] }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "model": { "$ref": "#/definitions/textOrNull" },
+    "effort": { "$ref": "#/definitions/textOrNull" },
+    "created": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }
+  }
+}

package/skills/gcf-adopt/SKILL.md

@@ -18,7 +18,7 @@ preconditions:
 
 forbidden_behaviors:
 - do not write `behavior`, `feel` or `constraints` out of reading code: a line derivable from code stays in code (П2)
-- do not open cards or backlog lines for what is already implemented: adoption puts nobody into work
+- do not open work items or backlog lines for what is already implemented: adoption puts nobody into work
 - do not schedule a retro playtest for a mechanic that already ships
 - do not write a pillar or a subsystem name the human did not confirm: both are human authorship
 - do not read code files whole: names, paths and entry points are the whole input
@@ -33,9 +33,9 @@ workflow:
 7. fill `behavior:` and `constraints:` with 1 placeholder each, annotated `[until: manual(first verdict touching <name>)]`: the profile requires both blocks, and a `manual(...)` trigger is not an audit finding
 8. write a constraint the human states out loud into `constraints:`, and do not interview subsystem by subsystem for more: unanswered questions on adoption day are the staleness this framework exists to remove
 9. draft `PILLARS.md` by the interview in the `gcf-init` skill, steps 4..6, and do not restate that interview here
-10. run `npx cnlp check`, then `ai-factory gcf lint` over each new systems doc, then `ai-factory gcf index`
+10. run `npx --yes cnlp-kit check`, then `ai-factory gcf lint` over each new systems doc, then `ai-factory gcf index`
 11. ask the human to run `ai-factory gcf hooks-install`; when it refuses over a foreign pre-commit, hand them the chain line it prints
-12. state the next step: an old design document goes through `/gcf-ingest`, new work starts at `/gcf-card`
+12. state the next step: an old design document goes through `/gcf-ingest` into `gcf/design/`, new work starts at `/gcf-card`
 
 invocation:
 - run once, when a project that already has code adopts GCF

package/skills/gcf-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gcf-audit
-description: Run the GCF consistency audit - stale until records, idle built cards, tune limits, P2 linter findings, plus a semantic contradiction pass. Use at session start or when the user says "аудит gcf".
+description: Run the GCF consistency audit - stale until records, items waiting on the human too long, tune limits, unplayed items, P2 linter findings, plus a semantic contradiction pass. Use at session start or when the user says "аудит gcf".
 ---
 
 mode: inspection
@@ -17,11 +17,12 @@ forbidden_behaviors:
 
 workflow:
 1. run `ai-factory gcf audit --json` and read the report
-2. state the first line verbatim: stale built cards block dependent work, so they lead
-3. for each stale until record: name the file, the trigger that fired and the line to re-check
-4. semantic pass, only when the mechanical report is clean or the human asks: read the systems docs of ONE subsystem the human names and report pairs of lines that contradict each other as D1 questions
-5. list the pragmas: each `gcf:allow` is a standing exception, and a growing list is the linter rotting
-6. propose the next actions, ranked, proposed actions <= 3: playtest, answer a D1, or collapse a stale record
+2. state the first line verbatim: items waiting too long block dependent work, so they lead
+3. for each stale until record: name the file, the trigger that fired and the line to re-check; for each entry of `stale_questions`: name the question id and ask the human for the answer
+4. read the `design` summary: blocking findings first (run `ai-factory gcf design check` for the list), then the count of ready units
+5. semantic pass, only when the mechanical report is clean or the human asks: read the systems docs of ONE subsystem the human names and report pairs of lines that contradict each other as D1 questions
+6. list the pragmas: each `gcf:allow` is a standing exception, and a growing list is the linter rotting
+7. propose the next actions, ranked, proposed actions <= 3: playtest, answer a D1, take a ready unit, or collapse a stale record
 
 invocation:
 - run at session start, after a long break, or on demand