gcf-aif-ext 0.2.7 → 0.4.0

package/skills/gcf-card/SKILL.md

@@ -1,36 +1,50 @@
 ---
 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: Put work into gcf/work/ - take a design unit with every TBD answered, group units under a feature, or create a tech, bug, spike, asset, content, perf or release item. Also parks a fresh idea as a unit. Use when work starts or the user says "заведи карточку" / "берём в работу" / "заведи задачу".
 ---
 
 mode: authoring
 
 purpose:
-- turn a backlog candidate or a fresh idea into a card file with the six slots filled
+- every piece of work in the project is one work item `gcf/work/<id>.md` with a type and a gate: who closes it - the human after play (`verdict`), a check (`auto`), the human without a build (`decision`)
+- a design unit enters work with every slot answered and its section moved, not copied
 
 inputs:
-- a cand-NNN id from `gcf/backlog.md`, or a free-text feature idea
+- an id from `gcf/backlog.md`, several ids to group under a feature, a free-text idea, or a request for non-design work
 
 preconditions:
-- `gcf/` exists; `gcf/INDEX.md` lists the current subsystems
+- `gcf/` exists; `gcf/INDEX.md` lists the current subsystems and items
 
 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, edit the backlog or write `status:` by hand: `ai-factory gcf take`, `item new`, `done`, `drop` and the item moves own those
+- do not reuse an id: an ended id stays ended; rework gets a new id with `reopens: <old id>`
+
+outputs:
+- each answered slot gets a provenance record `- slot: <block>` with `answer: manual`, or `answer: q-NNN` when it closes a question
+- a design-unit item body carries every block of its type plus `contract:` (paths and entry points) and `interactions:` (`<other id>: how the two cross`, or `- none: <why>`)
+- every item carries a `live:` delta before it ends: what it adds, modifies or removes in `gcf/LIVE.md`, 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 design 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. for non-design work: pick the type - tech, bug, spike, asset, content, perf, release - and propose the gate its type gives; the human may flip it (`--gate auto` is "no playtest")
+3. a bug needs `--severity` and a `repro:` the human confirms
+4. run `ai-factory gcf item new <id> --type <type> [--gate <gate>] [--parent <feature>] [--title "<line>"]`, add `--from <in-id>` when it comes from the inbox, `--blocked "file needed"` for a final asset; then write `intent:` and `live:` and stop
+5. for a design unit: 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
+6. 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
+7. 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
+8. 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
+9. ask the human one question per `TBD` slot, each with your proposed answer, questions per message <= 2
+10. write each answer into the unit in place, with its `answer:` provenance record
+11. run `ai-factory gcf design check --json` until the unit's entry in `units` reads `ready: true`, then commit the answered unit
+12. run `ai-factory gcf take <id>` for one unit, or `ai-factory gcf take <id> <id> --feature <feature-id>` to group several under a feature; it writes `gcf/work/<id>.md` and removes the sections and backlog lines in one step
+13. in each design-unit item write `contract:` from the code tree and `interactions:` from the units and items that write the same state; a soft unit whose human wants no playtest gets `gate: auto` - it will close as unplayed
+14. write the item's `live:` delta (a feature's children keep `none: parent`; the feature writes the capability), run `ai-factory gcf design check`, and commit
+15. report the item paths, each item's gate, and for a verdict item the one question the playtest will answer
 
 invocation:
-- run when work starts on a feature or the user names a candidate to materialize
+- run when work starts on a unit or a group of units, when non-design work needs an item, 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 work items: 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 waits for a verdict once in work; 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 work item 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

@@ -20,14 +20,14 @@ forbidden_behaviors:
 - pillar count <= 7, and do not pad the list to reach 7
 
 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
+1. when `.ai-factory/DESCRIPTION.md` is absent, tell the human to run `/aif` first: `aif-plan` reads it, and a work item cannot reach a plan without it
+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
+6. run `npx --yes cnlp-kit 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-triage/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: gcf-triage
+description: Triage gcf/inbox.md - playtest notes, CI failures, the agent's ideas and requests - into work items, tunes, ideas for the design, or noise, with the human approving each call. Use after a playtest session or when the user says "разбери инбокс".
+---
+
+mode: human gate
+
+purpose:
+- turn raw input into decided work: each inbox entry becomes a work item, a tune note, a design unit, a graveyard line, or nothing - and leaves the inbox
+
+inputs:
+- `gcf/inbox.md`, read through `ai-factory gcf inbox --json`
+
+preconditions:
+- `gcf/` exists and the inbox holds entries
+
+forbidden_behaviors:
+- do not create an item or erase an entry without the human's yes: the agent proposes, the human approves
+- do not turn a feel complaint into a bug: "jump feels floaty" is a tune of the item that owns the jump, a bug is behaviour that breaks a rule or a test
+- do not open a second item for something `gcf/graveyard.md` already buried: name the line and ask whether the reason still holds
+- do not edit `gcf/inbox.md` by hand: `ai-factory gcf item new --from` and `ai-factory gcf inbox drop` own its lines
+
+workflow:
+1. run `ai-factory gcf inbox --json`; read `gcf/LIVE.md` and `gcf/INDEX.md` to know what exists and what is in work
+2. classify each entry: bug, tune of a live or unplayed item, idea for the design, request (an asset file, a question), duplicate, or noise; search `gcf/graveyard.md` for each idea and bug
+3. for each entry propose one call with its fields: a bug gets type `bug`, severity and a repro; a tune names the item and the note; an idea names the subsystem; a duplicate names the item it repeats
+4. present the calls to the human, calls per message <= 5, and apply only the approved ones
+5. a bug or other work: run `ai-factory gcf item new <id> --type <type> [--severity <level>] --from <in-id>`, then write its `intent:` and `repro:`
+6. a tune of an item waiting for its verdict: keep the note for the verdict session and run `ai-factory gcf inbox drop <in-id>`; the note goes in through `/gcf-verdict … tune --note`
+7. an idea for the design: write a unit with `TBD` slots in `gcf/design/<system>.md` and its backlog line, then run `ai-factory gcf inbox drop <in-id>`
+8. a duplicate or noise: run `ai-factory gcf inbox drop <in-id>`
+9. report what each entry became and how many entries remain
+
+invocation:
+- run after a playtest session, after a CI run that added entries, or when the user asks to triage

package/skills/gcf-verdict/SKILL.md

@@ -1,32 +1,36 @@
 ---
 name: gcf-verdict
-description: Record the human playtest verdict on a built card - keep, tune or kill - and run the collapse. Use after a playtest or when the user says "вердикт".
+description: Record the human's verdict on an item waiting for play or unplayed - keep, tune or kill - or the human's decision on a decision item, a bug or a feature. Use after a playtest session or when the user says "вердикт" / "решение".
 ---
 
 mode: human gate
 
 purpose:
-- record the human verdict and run the one operation that collapses a card into subsystem state
+- record what the human decided and run the one command that ends or returns the item
 
 inputs:
-- a card-NNN id and a verdict word: keep, tune or kill; or nothing, which means "print the playtest list"
+- an item id and a verdict word (keep, tune, kill) or a decision word (go, no, wontfix, known, close, continue, kill); or nothing, which means "print the playtest list"
 
 preconditions:
-- the card sits in status `built`; the human has played the build
+- a verdict: the item is `awaiting-verdict` or `unplayed`, and the human has played the build
+- a decision: the item is `awaiting-decision`, or a bug in `ready`, `blocked` or `parked`, or a feature paused after a child died
 
 forbidden_behaviors:
-- do not decide the verdict: the human with hands on the controls decides, this skill records
-- do not run `keep` when the human has not answered the card's miss_criterion question
-- do not edit systems docs by hand: `ai-factory gcf verdict` owns the collapse
+- do not decide the verdict or the decision: the human decides, this skill records
+- do not run `keep` when the human has not answered the item's miss_criterion question
+- do not edit systems docs, `LIVE.md`, history or graveyard by hand: the commands own them
 
 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
+1. with no arguments: run `ai-factory gcf playtest` and stop - that list, awaiting-verdict and unplayed items, is the session's playtest sheet
+2. read the item; for a verdict ask the human the miss_criterion question and record the answer in one line
+3. for `tune` at the tune limit (`tune_limit` in `gcf/config.yml`, 3 by default): the command refuses; the way out is a kill, and a redesigned envelope becomes a new item with `reopens: <id>`
+4. for `keep` of a design-unit item still awaiting its verdict: compress it first - the collapse copies lines verbatim, 1 line per behavior record, refusal and boundary
+5. for that keep: strip `contract:` down to paths and entry points and cut `intent:` to the line the subsystem's purpose still lacks; leave an unplayed item as it is - its close froze the body
+6. run `ai-factory gcf verdict <id> <verdict> --note "<answer or reason>"`; a kill creates the removal item for code already in main unless the human says `--no-remove`
+7. for a decision run `ai-factory gcf decide <id> <choice> --reason "<why>"`; `known` parks a bug and lists it in `gcf/LIVE.md` known issues
+8. for a feature whose child died, the human picks: `close` without the child, `continue` with a replacement, or `kill` with its live children
+9. for `keep` on an item touching 2 or more subsystems: read each updated systems doc and report a contradiction between constraints as a D1 question instead of finishing silently
+10. report the commit hash, `git revert <hash>` is the undo, and the id of any removal item the command made
 
 invocation:
-- run after a playtest, or with no arguments to print the playtest sheet
+- run after a playtest session, on a human decision, 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/cnlp.config.json

@@ -1,7 +1,6 @@
 {
   "profiles": ".ai-factory/extensions/gcf-aif-ext/profiles",
   "corpus": [
-    { "profile": "card", "glob": "gcf/cards/*.md" },
     { "profile": "system", "glob": "gcf/systems/*.md" },
     { "profile": "pillars", "glob": "gcf/PILLARS.md" }
   ]

package/templates/config.yml

@@ -6,3 +6,10 @@ wip_built_limit: 5
 context_budget: 30000
 pillars_budget: 1500
 envelope_default_spread: 0.3
+unplayed_warn_after: 5
+plan_passes: 5
+dod_attempts: 2
+# The project's own commands for the auto DoD (Methodology §6); the engine does not matter.
+dod:
+  test:
+  build:

package/templates/design.md

@@ -0,0 +1,59 @@
+# example-system
+
+purpose:
+- holds the example mechanic and the rule it rests on
+
+## example-dash
+
+type: mechanic
+title: dash
+route: soft (acceptance is the feel of the move)
+system: [example-system]
+milestone: TBD
+pillars: TBD
+depends: [example-grid]
+source: manual
+
+intent:
+- the player crosses short gaps without breaking the pace of a fight
+
+behavior:
+- input: the player presses X
+  state: the character moves a short distance forward
+  feedback: TBD
+
+refusal:
+- pressing X during the cooldown does nothing
+
+boundaries: TBD
+
+persistence: none: a dash leaves no state behind
+
+feel_like: like Hades, not like Celeste
+
+feel:
+- name: duration
+  envelope: 0.15..0.25 s
+
+constraints:
+- do not add a new input binding
+
+miss_criterion: TBD
+
+## example-grid
+
+type: rule
+title: example grid
+route: hard (a structural invariant, unit-testable)
+system: [example-system]
+milestone: TBD
+pillars: TBD
+depends: none
+source: manual
+
+statement:
+- grid cells per side in {4, 6, 8}
+- the grid never scrolls
+
+check:
+- a unit test over the level data

package/templates/game.md

@@ -0,0 +1,24 @@
+logline: a short-session puzzle about placing tiles on a small board
+
+platforms:
+- web portals and mobile browsers, touch and mouse
+
+audience:
+- TBD
+
+references:
+- like a tabletop logic puzzle, not like a match-three game
+
+scope_in:
+- the core puzzle with one short win animation
+
+scope_out:
+- story, cutscenes and dialogue
+
+milestones:
+- name: web
+  goal: validate the core puzzle on a live audience
+  content: campaign levels = 50
+
+- name: steam
+  goal: a long campaign once the web version proves the puzzle keeps players

package/templates/glossary.md

@@ -0,0 +1,11 @@
+terms:
+- term: tile tray
+  means: the supply of unplaced tiles the player picks from
+  not: hand, table
+
+- term: void cell
+  means: a cell a shaped board leaves out
+  not: blocked cell
+
+units:
+- coins: the soft currency

package/templates/item.md

@@ -0,0 +1,58 @@
+---
+schema: 3
+id: example
+type: mechanic
+gate: verdict
+status: ready
+system: [example-system]
+depends: []
+pillars: []
+source: manual
+tune_count: 0
+since: null
+live:
+  changes:
+    - id: example
+      change: added
+      summary: A short dash forward between fights.
+      refs: gcf/systems/example-system.md
+created: "2026-01-01"
+---
+
+intent:
+- the player crosses short gaps without breaking the pace of a fight
+
+behavior:
+- 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
+
+interactions:
+- none: this example crosses no existing mechanic
+
+constraints:
+- do not add a new input binding
+- no per-frame allocations
+
+miss_criterion: does the move feel responsive on the first try