gcf-aif-ext 0.2.7 → 0.3.0

package/profiles/unit-resource.md

@@ -0,0 +1,86 @@
+---
+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: card stage only - one verdict remark per tune, read before the rebuild
+
+- 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,42 @@
+---
+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: 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/card.schema.json

@@ -4,13 +4,24 @@
   "title": "GCF card frontmatter",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schema", "id", "slug", "status", "route", "system", "depends", "source", "tune_count", "created"],
+  "required": [
+    "schema",
+    "id",
+    "type",
+    "status",
+    "system",
+    "depends",
+    "pillars",
+    "source",
+    "tune_count",
+    "created"
+  ],
   "properties": {
-    "schema": { "const": 1 },
-    "id": { "type": "string", "pattern": "^card-\\d{3}$" },
-    "slug": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+    "schema": { "const": 2 },
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+    "type": { "enum": ["mechanic", "resource"] },
+    "title": { "type": "string", "minLength": 1 },
     "status": { "enum": ["proposed", "built", "tuning"] },
-    "route": { "enum": ["soft", "hard"] },
     "system": {
       "type": "array",
       "minItems": 1,
@@ -18,9 +29,14 @@
     },
     "depends": {
       "type": "array",
-      "items": { "type": "string", "pattern": "^card-\\d{3}$" }
+      "items": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }
+    },
+    "pillars": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }
     },
-    "source": { "type": "string", "pattern": "^(GDD#[A-Za-z0-9_-]+|manual|inferred)$" },
+    "source": { "type": "string", "pattern": "^(GDD#[A-Za-z0-9_-]+|manual)$" },
+    "reopens": { "type": "string", "minLength": 1 },
     "tune_count": { "type": "integer", "minimum": 0 },
     "built_at": {
       "anyOf": [{ "type": "null" }, { "type": "string", "pattern": "^[0-9a-f]{7,40}$" }]

package/skills/gcf-adopt/SKILL.md

@@ -35,7 +35,7 @@ workflow:
 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`
 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

@@ -19,9 +19,10 @@ 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
+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

package/skills/gcf-card/SKILL.md

@@ -1,36 +1,45 @@
 ---
 name: gcf-card
-description: Materialize a GCF card from a backlog candidate or a fresh idea - slots, hard/soft routing, depends. Use when work starts on a feature or the user says "заведи карточку".
+description: Take a design unit into work - close its TBD with the human, then move a soft unit into its card or hand a hard unit to the AIF cycle. Also parks a fresh idea as a unit. Use when work starts on a feature or the user says "заведи карточку" / "берём в работу".
 ---
 
 mode: authoring
 
 purpose:
-- turn a backlog candidate or a fresh idea into a card file with the six slots filled
+- take one unit of `gcf/design/` into work with every slot answered
+- a soft unit (mechanic, resource) becomes `gcf/cards/<id>.md` with the same body; a hard unit (rule, constraint, entity) stays in place and goes to the AIF cycle
 
 inputs:
-- a cand-NNN id from `gcf/backlog.md`, or a free-text feature idea
+- an id from `gcf/backlog.md`, or a free-text idea
 
 preconditions:
 - `gcf/` exists; `gcf/INDEX.md` lists the current subsystems
 
 forbidden_behaviors:
 - do not invent a new subsystem name when INDEX carries a synonym: reuse or ask
-- do not write numbers outside the feel slot envelopes
+- do not answer a `TBD` yourself: ask the human, and offer your draft as the proposed answer
+- do not take a unit an open D1 blocks: `ai-factory gcf design check` names the blocking question, and the human answers it first
+- do not write a digit in prose: a number is an envelope `a..b <unit>` in `feel` or a closing comparison
 - do not put `until:` in the frontmatter: it is a line annotation inside slots
-- do not fill a slot with a guess: an unknown goes to `gcf/open-questions.md`, marked D1 or D2
+- do not move a section or edit the backlog by hand: `ai-factory gcf take`, `done` and `drop` own those moves
+
+outputs:
+- each answered slot gets a provenance record `- slot: <block>` with `answer: manual`, or `answer: q-NNN` when it closes a question
+- a card body carries every block of its type plus `contract:` (paths and entry points) and `interactions:` (`<other id>: how the two cross`, or `- none: <why>`)
 
 workflow:
-1. read `gcf/INDEX.md`; for a cand-NNN input read its backlog line, otherwise ask "into work now, or park in the backlog?" and on "park" append a line in the backlog header format and stop
-2. for an `impl?` line ask the human first whether the mechanic already ships; for a `src-changed` line rebuild the candidate from `ai-factory gcf section` over its `src:` anchor
-3. route the requirement: ask "can an autotest accept this without a human playing?"; yes = hard, no or mixed = soft; state the route in one line, start from the line's `route:` reason, and let the human veto
-4. for a pure hard route: send the requirement to the normal AIF cycle, add any lasting prohibition to the subsystem's constraints, and stop - no card
-5. copy `templates/card.md` to `gcf/cards/<card-id>-<slug>.md`: the id keeps the candidate number, or takes the next free number for a fresh idea
-6. fill the frontmatter: status proposed, route, system list from the INDEX vocabulary, depends from cards this feature builds on, source, created
-7. fill the six slots with the human: behavior, contract, feel (comparison + envelopes), interactions, constraints, miss_criterion; ask each `gaps:` lens of the line here
-8. when the card came from a candidate, delete that candidate line from `gcf/backlog.md`
-9. run `ai-factory gcf index`, then `npx cnlp check`, and fix what they report
-10. report the card path and the one question the playtest will answer
+1. for a free-text idea: ask "into work now, or park it?"; write a unit in the matching `gcf/design/<system>.md` with `source: manual` and `TBD` slots, append `- <id>` to `gcf/backlog.md`, and on "park" stop here
+2. run `ai-factory gcf where <id>`: the id must be a single unit of `gcf/design/`; read its section from the file the command names
+3. for a unit with `flags: impl?` ask the human first whether the mechanic already ships; on "yes" run `ai-factory gcf drop <id> --reason "already ships"` and stop
+4. for a unit with `flags: src-changed` re-read each changed anchor with `ai-factory gcf section`, rebuild the slots whose quote moved, and remove the flag
+5. confirm the route: ask "can an autotest accept this without a human playing?"; yes = hard, no or mixed = soft; a mixed unit splits into a soft mechanic and a hard rule before work
+6. ask the human one question per `TBD` slot, each with your proposed answer, questions per message <= 2
+7. write each answer into the unit in place, with its `answer:` provenance record
+8. run `ai-factory gcf design check` until the unit reads `ready` and the check has no blocking finding for it, then commit the answered unit: a hard unit leaves `gcf/design/` at `done`, and its answers live in git only from this commit
+9. for a soft unit: run `ai-factory gcf take <id>` - it writes `gcf/cards/<id>.md` and removes the section and the backlog line in one step
+10. in the card, write `contract:` from the code tree and `interactions:` from the units and cards that write the same state, then run `ai-factory gcf design check` again
+11. for a hard unit: send it to the AIF cycle (`/aif-plan` with the unit id); after the tests are green, run `ai-factory gcf done <id>`, adding `--constraint "<line>"` for a prohibition every future reader of the subsystem must remember
+12. report the card path and the one question the playtest will answer, or the hard unit's plan
 
 invocation:
-- run when work starts on a feature or the user names a candidate to materialize
+- run when work starts on a unit, or when a fresh idea needs a home

package/skills/gcf-debate/SKILL.md

@@ -1,33 +1,36 @@
 ---
 name: gcf-debate
-description: The debate table - expert lenses stress a GDD for gaps, contradictions and unbuildable specs before import. Use when the user asks to review a GDD, check design coherence, or says "стол дебатов".
+description: The debate table - expert lenses stress the design for gaps, contradictions and unbuildable specs, over the Design Model or a GDD file. Use when the user asks to review the design, check design coherence, or says "стол дебатов".
 ---
 
 mode: review board
 
 purpose:
-- stress a GDD through the GCF lenses and report the gaps the designer did not write down
+- stress the design through the GCF lenses after the mechanical check, and report the gaps the designer did not write down
 
 inputs:
-- a path to the GDD (markdown); optionally the names of lenses to run, default is all
+- a unit id, `--milestone <name>`, or nothing for all of `gcf/design/`
+- or a path to a GDD (markdown) that gcf-ingest has not imported yet
+- optionally the names of lenses to run, default is all
 
 preconditions:
-- the file exists and is readable markdown
+- for the Design Model: `gcf/design/` holds units; for a GDD file: the file exists and is readable markdown
 
 forbidden_behaviors:
-- do not edit the document without the human's explicit go-ahead per edit
+- do not edit a unit or the document without the human's explicit go-ahead per edit
 - do not resolve a principal fork yourself: a fork goes to the human as a D1 question with a proposed default
 - do not review style or prose quality: the table checks buildability and coherence only
+- do not repeat what the mechanical check already reports: the lenses start where `ai-factory gcf design check` stops
 
 workflow:
-1. run `ai-factory gcf anchor <file>` and use the printed anchors in every finding
-2. play each completeness lens as its own expert over each mechanic: state, input, feedback, refusal, boundaries, persistence
-3. play the coherence lenses over the whole document: interaction matrix (which mechanics write the same state), loop closure, progression pressure, economy balance, one-word-per-concept dictionary
-4. cross-examine: for each pair of findings that touch one anchor, check whether they contradict each other and merge or escalate
-5. classify each finding: D2 gets a proposed default the human can skim; D1 is a principal fork and carries the question, the anchors and a proposed answer
-6. report by lens, ordered by damage: contradictions first, then holes, then dictionary drift; cite anchors, quote lines <= 15 words
-7. when `gcf/` exists, append D1 and D2 records to `gcf/open-questions.md`; otherwise put them into the report only
-8. offer the fixes: apply agreed edits to the document one by one, each on its own go-ahead
+1. over the Design Model: run `ai-factory gcf design check --json` and read the blocking findings and the `TBD` counts first; over a GDD file: run `ai-factory gcf anchor <file>` and use the printed anchors in every finding
+2. play each completeness lens as its own expert over each mechanic: state, input, feedback, refusal, boundaries, persistence; over units, judge only the slots that hold a value
+3. play the coherence lenses over the whole set: interaction matrix (which units write the same state), loop closure (each resource has a source and a sink that fit), progression pressure, economy balance, one word per concept, pillar fit
+4. cross-examine: for each pair of findings that touch one unit or anchor, check whether they contradict each other and merge or escalate
+5. classify each finding: D2 gets a proposed default the human can skim; D1 is a principal fork and carries the question, the units in `blocks:` and a proposed answer
+6. report by lens, ordered by damage: contradictions first, then holes, then dictionary drift; cite unit ids or anchors, quote lines <= 15 words
+7. append D1 and D2 records to `gcf/open-questions.md` when `gcf/` exists; otherwise put them into the report only
+8. offer the fixes: apply each agreed edit to its unit in place, with `answer: manual` in its provenance, one go-ahead per edit, then run `ai-factory gcf design check`
 
 invocation:
-- run on a fresh GDD before ingest, after a big GDD revision, or on demand
+- run on a fresh GDD before ingest, on the Design Model after an import or a big revision, or on demand

package/skills/gcf-ingest/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: gcf-ingest
-description: Import a GDD into GCF - anchors, candidate backlog, pillar candidates, gap questions; re-import classifies the delta. Use when the user brings a GDD or says "импортируй GDD".
+description: Import a GDD into the GCF Design Model - anchors, design units with slots, game and glossary proposals, gap questions; re-import marks only the units whose quotes moved. Use when the user brings a GDD or says "импортируй GDD".
 ---
 
 mode: import
 
 purpose:
-- cut a GDD into inert backlog candidates and a short list of questions, without putting anyone "into work"
+- cut a GDD into design units in `gcf/design/<system>.md` and a short list of questions, without putting anyone "into work"
+- write into a slot only what the GDD says: a verbatim quote backs the value, and every other slot reads `TBD`
 
 inputs:
 - a path to the GDD (markdown)
@@ -16,34 +17,49 @@ preconditions:
 - the sequential pass below is the correctness reference; the parallel fan-out belongs to the harness
 
 forbidden_behaviors:
-- do not create card files: candidates are backlog lines, and a card file materializes only when `/gcf-card` pulls a candidate into work
+- do not create card files: a unit stays in `gcf/design/` until `/gcf-card` takes it into work
 - do not write a pillar into PILLARS.md: pillar candidates go to open-questions as D1
-- do not put an extracted unit into the backlog without a verbatim quote from its section: no quote means source inferred, and inferred goes to open-questions
+- do not fill a slot from your own reasoning: a value without a verbatim quote is `TBD`, and your draft answer goes into the `proposed:` field of a question
 - do not read `gcf/source/` files whole after anchoring: read a section with `ai-factory gcf section <file> <anchor>`
-- do not turn a count, a hard limit or a performance threshold into an envelope: only a tunable value gets a spread
+- do not turn a count, a hard limit or a performance threshold into an envelope: only a tunable value gets a range
+- do not write a digit in prose: a number is an envelope `a..b <unit>` in `feel` or a rate, or a closing comparison `<subject> <op> <value> [unit]`
+- do not overwrite a slot whose provenance record reads `answer:`: the human wrote it, and a conflict with the GDD is a D1 question
+- do not reuse an id the ledger reports as done, collapsed or killed: `ai-factory gcf where <id>` says, and a revival is the human's D1
 
 outputs:
-- a backlog line: `- <cand-id> | <name> | route: soft|hard (<why>) | sys: <system> | deps: <ids or -> | src: GDD#<anchor> | q: "<verbatim quote>" | <description>`
-- optional backlog fields go before the description, only when they apply: `gaps: <lenses>`, `impl?`, `src-changed`, `orphan`
-- a question record in `gcf/open-questions.md`: `- id: q-NNN`, then `lens:`, `sections:`, `sys:`, `class: D1|D2`, `question:`, `proposed:`, each on its own indented line
-- a D2 record adds `assumed:` (what the agent took as given) and `until:` (when it expires, in the `verdict(card-id)`, `retune(system)` or `manual(text)` form)
+- a unit: a `## <id>` section in `gcf/design/<system>.md`, the id a lowercase hyphen slug from the unit's name, frozen once written
+- the unit header: `type`, `title`, `route: soft|hard (<why>)`, `system: [<file system>, ...]`, `milestone`, `pillars`, `depends`, `source`, and `flags` only when one applies
+- the unit body: the blocks of `templates/design.md` for its type - mechanic, resource, rule, constraint or entity - with `TBD` for every unknown
+- a `provenance:` block per unit: one record per slot, `slot` plus `src: GDD#<anchor>` and `quote: "<verbatim>"`, or `assumed: q-NNN` for a D2 decision
+- `gcf/design/<system>.md` opens with `# <system>` and a `purpose:` block, `TBD` when the GDD names no purpose
+- `gcf/backlog.md`: one `- <id>` line per new unit, appended at the end
+- a question record in `gcf/open-questions.md`: `- id: q-NNN`, then `lens:`, `sections:`, `sys:`, `class: D1|D2`, `question:`, `proposed:`, and `blocks: <ids>` when the answer gates units
+- a D2 record adds `assumed:` (what the agent took as given) and `until:` (when it expires, in the `verdict(<id>)`, `retune(system)` or `manual(text)` form)
+- `gcf/game.md` and `gcf/glossary.md` proposals in the forms of `templates/game.md` and `templates/glossary.md`, written only after the human confirms them
 
 workflow:
 1. when `gcf/systems/` is empty and the repository already holds game code, tell the human `impl?` marks are blind without `/gcf-adopt`, and offer to run it first
-2. run `ai-factory gcf anchor <file>`: it prints each anchor with its line range; on a re-import read the printed delta and jump to step 11
-3. extract per aspect, one pass each, citing a quote and an anchor per unit: pillar candidates; subsystems (nouns); feature candidates (player verbs); numbers and progressions; platform and audience constraints
-4. treat the GDD's own open-questions section, and any TBD or TODO, as D1 records with lens `gdd-open` and the anchor in `sections:`, not as candidates
-5. copy each quote verbatim from the section `ai-factory gcf section` prints; write a unit with no such quote as a D1 record with lens `provenance`, not a candidate
-6. classify each number before an envelope: a tunable value (duration, speed, damage, cost, rate) gets value ± `envelope_default_spread` from `gcf/config.yml`
-7. round both envelope bounds of an integer to integers, at least 1 apart from the value; leave counts (50 levels), hard limits and performance thresholds exact
-8. write each envelope as a D2 record with `assumed:` and `until: manual(materialization of <cand-id>)`; an exact limit or threshold goes into the candidate description and leans the route to hard
-9. route each candidate: hard when the agent can verify acceptance alone (data format, protocol, structural invariant, numeric performance threshold), soft when acceptance is a playtest; doubt -> soft
-10. run the completeness lenses per candidate into `gaps:`, then the coherence lenses over the set; build the interaction matrix and record `deps:` between candidates from it
-11. on a re-import apply the delta: added -> new candidates; changed -> `src-changed`, D1 when an open card or collapsed system cites the anchor; removed -> `orphan`; renamed -> rewrite the anchor in place
-12. mark a candidate whose nouns match the `purpose` or the `code` paths of an existing systems doc with `impl?`: the mechanic may already ship, and the human deletes the line
-13. write candidate lines into `gcf/backlog.md` and records into `gcf/open-questions.md`; run `ai-factory gcf quotes`, move each flagged line to a D1 with lens `provenance`, then run `ai-factory gcf index`
-14. report the package, ordered: D1 questions (the main product), pillar candidates, dictionary conflicts, backlog summary with the top crossing candidates, D2 assumptions; say when `impl?` was blind
-15. state the next step: answer D1s, confirm pillars, then pull the first candidate with `/gcf-card`
+2. run `ai-factory gcf anchor <file>`: it prints each anchor with its line range; on a re-import read the printed delta and jump to step 17
+3. extract per aspect, one pass each, with a quote and an anchor per value: pillar candidates; subsystems (nouns); player verbs (mechanic); economy resources (resource)
+4. extract the hard aspects the same way: invariants (rule); platform and performance thresholds (constraint); data nouns (entity)
+5. type each unit: a mechanic or a resource is soft and becomes a card later; a rule, a constraint or an entity is hard and leaves through tests
+6. split a candidate that mixes a tunable feel with a testable rule into 2 units: a soft mechanic and a hard rule
+7. treat the GDD's own open-questions section, and any TBD or TODO, as D1 records with lens `gdd-open` and the anchor in `sections:`, and name the units each one gates in `blocks:`
+8. copy each quote verbatim from the section `ai-factory gcf section` prints; a unit with no quote at all becomes a D1 record with lens `provenance`, not a unit
+9. classify each number before an envelope: a tunable value (duration, speed, damage, cost, rate) gets value ± `envelope_default_spread` from `gcf/config.yml`, rounded outward for an integer
+10. write that envelope into the slot and a D2 record for it, and cite the record as `assumed: q-NNN` beside the quote
+11. keep counts, hard limits and performance thresholds exact as comparisons
+12. ask about a unit of measure outside the closed list (bare `px`, a currency): it becomes a question, or a `units:` entry of the glossary the human confirms
+13. run the completeness lenses per unit - input, state, feedback, refusal, boundaries, persistence - and leave each unanswered lens as `TBD` in its slot: the questions come when `/gcf-card` takes the unit
+14. run the coherence lenses over the set and send their findings to questions now: interaction matrix, loop closure, economy, progression, dictionary
+15. record `depends:` between units from the interaction matrix: units that write the same state
+16. propose the glossary from the dictionary lens: one term per concept and its forbidden synonyms; keep the GDD's own words in unit text until the human confirms a term
+17. on a re-import run `ai-factory gcf design check`: a unit whose quote is no longer verbatim gets `flags: src-changed`, a unit whose anchor the GDD removed gets `flags: orphan`; `gcf anchor` already rewrote renamed anchors
+18. on a re-import, raise a D1 for a card or a collapsed system that cites a changed anchor, and run steps 3..16 over the text no quote covers any more
+19. mark a unit whose nouns match the `purpose` or the `code` paths of an existing systems doc with `flags: impl?`: the mechanic may already ship, and the human drops it with `ai-factory gcf drop`
+20. append the new ids to `gcf/backlog.md`, run `ai-factory gcf design check`, and fix every blocking finding before you report
+21. report the package, ordered: D1 questions (the main product), pillar candidates, glossary conflicts, the design summary per subsystem, D2 assumptions; say when `impl?` was blind
+22. state the next step: answer the D1s, confirm pillars and glossary, then take the first unit with `/gcf-card <id>`
 
 invocation:
 - run when a GDD arrives or changes

package/skills/gcf-init/SKILL.md

@@ -21,13 +21,13 @@ forbidden_behaviors:
 
 workflow:
 1. when `.ai-factory/DESCRIPTION.md` is absent, tell the human to run `/aif` first: `aif-plan` reads it, and a card cannot reach a plan without it
-2. run `ai-factory gcf init` and report which files it created; it writes no `PILLARS.md`, so no example ever reads as the game's truth
+2. run `ai-factory gcf init` and report which files it created, `gcf/design/` among them; it writes no `PILLARS.md`, so no example ever reads as the game's truth
 3. when the human is about to import a GDD, leave `PILLARS.md` absent: the import proposes pillar candidates, and the interview runs after it
-4. otherwise ask the human for the game's core promise, then for 2..7 pillars: each needs a statement, a negative invariant and a review question
+4. otherwise ask the human for the game's core promise, then for 2..7 pillars: each needs an id (a lowercase hyphen slug the design units cite), a statement, a negative invariant and a review question
 5. write `gcf/PILLARS.md` with the confirmed pillars in the record-list form of `.ai-factory/extensions/gcf-aif-ext/templates/PILLARS.md`
 6. run `npx cnlp check` and fix form issues it reports
 7. ask the human to run `ai-factory gcf hooks-install`: the commit gate is theirs to arm
-8. state the next step: fill `gcf/backlog.md` with candidates by hand or import a GDD with `/gcf-ingest`
+8. state the next step: import a GDD with `/gcf-ingest`, or start the design with `/gcf-vision` when there is none
 
 invocation:
 - run when the user asks to set up gcf in a project

package/skills/gcf-verdict/SKILL.md

@@ -9,7 +9,7 @@ purpose:
 - record the human verdict and run the one operation that collapses a card into subsystem state
 
 inputs:
-- a card-NNN id and a verdict word: keep, tune or kill; or nothing, which means "print the playtest list"
+- a card id and a verdict word: keep, tune or kill; or nothing, which means "print the playtest list"
 
 preconditions:
 - the card sits in status `built`; the human has played the build
@@ -23,10 +23,11 @@ workflow:
 1. with no arguments: run `ai-factory gcf playtest` and stop - that list is the session's playtest sheet
 2. read the card; ask the human the miss_criterion question and record the answer in one line
 3. for `tune` at tune_count 3: refuse and present the fork - kill, or redesign the envelope and reset the counter with a note
-4. for `keep`: rewrite the behavior slot into 1 line per observable behavior and strip contract lines down to paths and entry points - the collapse copies lines verbatim, so compress them in the card first
-5. run `ai-factory gcf verdict <card-id> <verdict> --note "<answer or reason>"`
-6. for `keep` on a card touching 2 or more subsystems: read each updated systems doc and report a contradiction between constraints as a D1 question instead of finishing silently
-7. report the verdict commit hash: `git revert <hash>` is the undo
+4. for `keep`: compress the card first - the collapse copies lines verbatim, 1 line per behavior record, refusal and boundary; strip `contract:` down to paths and entry points
+5. for `keep`: cut `intent:` to the line the subsystem's purpose still lacks, or to `- none: <why>`
+6. run `ai-factory gcf verdict <id> <verdict> --note "<answer or reason>"`; a tune note lands in the card's `tuning:` block, where the rebuild reads it
+7. for `keep` on a card touching 2 or more subsystems: read each updated systems doc and report a contradiction between constraints as a D1 question instead of finishing silently
+8. report the verdict commit hash: `git revert <hash>` is the undo
 
 invocation:
 - run after a playtest, or with no arguments to print the playtest sheet

package/skills/gcf-vision/SKILL.md

@@ -1,33 +1,39 @@
 ---
 name: gcf-vision
-description: Project-start wizard - guided questions that turn a raw game idea into a first GDD draft ready for gcf-ingest. Use when there is no project yet or the user says "начнем игру" / "start a game".
+description: Project-start wizard - guided questions that turn a raw game idea into gcf/game.md and the first design units with TBD slots. Use when there is no design yet or the user says "начнем игру" / "start a game".
 ---
 
 mode: wizard
 
 purpose:
-- turn a raw idea into a first GDD draft through a guided interview, so the standard ingest flow has an input
+- turn a raw idea into `gcf/game.md` and skeleton units in `gcf/design/` through a guided interview, so the design has a structure from the first day
 
 inputs:
 - none: the skill discovers everything by asking the human
 
 preconditions:
 - no GDD exists yet; when one exists, route to gcf-debate or gcf-ingest instead
+- `gcf/` exists: run `ai-factory gcf init` first when it does not
 
 forbidden_behaviors:
-- do not write into `gcf/`: the draft is the designer's document, ingest brings it into gcf later
-- do not fill an answer the human skipped: write the gap into the draft as an open question
+- do not fill an answer the human skipped: the slot reads `TBD`, and an open fork becomes a D1 question
 - questions per message <= 2: a wall of questions kills the interview
+- do not write a pillar into PILLARS.md: pillar candidates go to the human, and `/gcf-init` writes the file
+
+outputs:
+- `gcf/game.md` in the form of `templates/game.md`: logline, platforms, audience, references, scope in and out, milestones
+- one `gcf/design/<system>.md` per subsystem, opening with `# <system>` and `purpose:`, with one `## <id>` unit per mechanic, resource or rule the human named, `source: manual`, every unknown slot `TBD`
+- `gcf/backlog.md` with one `- <id>` line per unit, in the order the human ranks them
 
 workflow:
 1. ask about the core: genre, the one-sentence fantasy, and the reference games with "like X, not like Y"
 2. ask about the loop: what the player does each 30 seconds, each session, each week
-3. ask about scope: platform, session length, solo or multiplayer, art constraints, team size
-4. ask what the game is NOT: negative answers seed the pillars and cost the least
-5. draft the GDD as plain markdown with one `##` heading per topic: vision, pillars-candidates, core loop, mechanics, progression, scope, open questions
-6. write every unanswered or invented point into the `## open questions` section, marked as a guess
-7. present the draft, iterate on the human's corrections, and save where the human names
-8. state the next step: `/gcf-debate <file>` to stress the draft, or `/gcf-ingest <file>` to import it
+3. ask about scope: platform, session length, solo or multiplayer, art constraints, team size, and the milestones - what the first version must prove
+4. ask what the game is NOT: negative answers seed the pillars and the scope_out list, and cost the least
+5. write `gcf/game.md` from the answers, and read it back to the human for corrections
+6. name the subsystems and the units with the human: each player verb a mechanic, each currency a resource, each invariant a rule; write each unit with the blocks of `templates/design.md` for its type
+7. write `gcf/backlog.md` in the human's ranking, then run `ai-factory gcf design check` and fix every blocking finding
+8. state the next step: `/gcf-init` for the pillars interview, `/gcf-debate` to stress the design, then `/gcf-card <id>` for the first unit
 
 invocation:
-- run at project start, before any gcf structure exists
+- run at project start, before any design exists

package/templates/PILLARS.md

@@ -2,7 +2,9 @@ pillars:
 - statement: every encounter is readable at a glance
   invariant: no effect ever hides the player character
   review_question: does this change add visual noise over the player
+  id: readable-encounters
 
 - statement: death is the player's fault, never the camera's
   invariant: no off-screen damage sources
   review_question: can this change hurt the player from outside the view
+  id: fair-camera

package/templates/backlog.md

@@ -1,5 +1,2 @@
-# Backlog — candidates, one line each. Order = priority, owned by the human.
-# Format: - <cand-id> | <name> | route: soft|hard (<why, one line>) | sys: <system> | deps: <ids or -> | src: <GDD#anchor|manual> | q: "<verbatim quote>" | [gaps: <lenses>] | [impl?] | [src-changed] | [orphan] | <one-line description>
-# q: is required with a GDD# src (`ai-factory gcf quotes` checks it); bracketed fields appear only when they apply.
-# Example (a comment, not a candidate):
-# - cand-001 | dash | route: soft (acceptance is the feel of the move) | sys: movement | deps: - | src: GDD#3f2a9c1e | q: "a short dash through enemies" | gaps: refusal, boundaries | a short invulnerable dash
+# Backlog — the order of the units in gcf/design/, one `- <id>` per line, top first. Owned by the human.
+# Every unit of gcf/design/ appears here exactly once: import appends, /gcf-card, gcf done and gcf drop remove.

package/templates/card.md

@@ -1,29 +1,46 @@
 ---
-schema: 1
-id: card-000
-slug: example
+schema: 2
+id: example
+type: mechanic
 status: proposed
-route: soft
 system: [example-system]
 depends: []
+pillars: []
 source: manual
 tune_count: 0
 built_at: null
 created: "2026-01-01"
 ---
 
+intent:
+- the player crosses short gaps without breaking the pace of a fight
+
 behavior:
-- player presses X -> the character does Y -> the screen shows Z
+- input: the player presses X
+  state: the character moves a short distance forward
+  feedback: the screen shows a short trail behind the character
+
+refusal:
+- pressing X during the cooldown does nothing and plays no sound
+
+boundaries:
+- a dash into a wall stops at the wall
+
+persistence: none: a dash leaves no state behind
+
+feel_like: like Hades, not like Celeste
+
+feel:
+- name: duration
+  envelope: 0.15..0.25 s
+
+- name: cooldown
+  envelope: 0.4..0.8 s
 
 contract:
 - new components and systems live under Assets/Scripts/Example/
 - data flows from input to simulation, never backwards
 
-feel:
-- like Hades, not like Celeste
-- duration 0.15..0.25 s
-- cooldown 0.4..0.8 s
-
 interactions:
 - none: this example crosses no existing mechanic