gcf-aif-ext 0.2.4 → 0.2.7

package/skills/gcf-card/SKILL.md

@@ -15,21 +15,22 @@ 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 (GCF-PRD §5.4)
+- 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 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
 
 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 candidate line and stop
-2. 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 and let the human veto
-3. 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 (GCF-PRD §6.3)
-4. 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
-5. fill the frontmatter: status proposed, route, system list from the INDEX vocabulary, depends from cards this feature builds on, source, created
-6. fill the six slots with the human: behavior, contract, feel (comparison + envelopes), interactions, constraints, miss_criterion
-7. when the card came from a candidate, delete that candidate line from `gcf/backlog.md`
-8. run `ai-factory gcf index`, then `npx cnlp check`, and fix what they report
-9. report the card path and the one question the playtest will answer
+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
 
 invocation:
 - run when work starts on a feature or the user names a candidate to materialize

package/skills/gcf-debate/SKILL.md

@@ -21,7 +21,7 @@ forbidden_behaviors:
 
 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 (GCF-PRD §11.4)
+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

package/skills/gcf-ingest/SKILL.md

@@ -16,23 +16,34 @@ 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, a card materializes only at pull (GCF-PRD §5.2)
+- 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 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 read `gcf/source/` files whole after anchoring: address sections by anchor
+- 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
+
+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)
 
 workflow:
-1. run `ai-factory gcf anchor <file>`; on a re-import read the printed delta and jump to step 9
-2. 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
-3. verify provenance: a unit whose quote is not found verbatim in its section becomes `inferred` and moves to the question list
-4. turn each exact number into an envelope: value ± the `envelope_default_spread` from `gcf/config.yml`, marked assumed, listed for the human's skim
-5. run the completeness lenses per candidate and write gaps into the candidate line as `gaps:` notes - questions at import time go only to document-level findings
-6. run the coherence lenses over the whole set; build the interaction matrix and record `deps:` between candidates from it
-7. write the outputs: candidate lines into `gcf/backlog.md` (route guessed per GCF-PRD §6, human vetoes later); D1 and D2 records into `gcf/open-questions.md`; then run `ai-factory gcf index`
-8. mark a candidate whose nouns match the `purpose` or the `code` paths of an existing systems doc with `impl?` in its backlog line: on an adopted codebase the mechanic may already ship, and the human is the one who deletes the line
-9. on a re-import, apply the delta classes (GCF-PRD §11.6): added -> new candidates; changed -> mark `src-changed`, and D1 when an open card or a collapsed system cites the anchor; removed -> orphan marks; renamed -> update anchors in place
-10. report the package, ordered: D1 questions (the main product), pillar candidates, dictionary conflicts, backlog summary with the top crossing candidates, D2 assumptions
-11. state the next step: answer D1s, confirm pillars, then pull the first candidate with `/gcf-card`
+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`
 
 invocation:
 - run when a GDD arrives or changes

package/skills/gcf-init/SKILL.md

@@ -16,17 +16,18 @@ preconditions:
 
 forbidden_behaviors:
 - do not overwrite an existing gcf/ tree: re-running repairs missing files only
-- do not write pillars the human did not confirm: pillar authorship is human (GCF-PRD §5.3)
+- do not write pillars the human did not confirm: pillar authorship is human
 - pillar count <= 7, and do not pad the list to reach 7
 
 workflow:
-1. run `ai-factory gcf init` and report which files it created
-2. read `gcf/PILLARS.md`; when it still holds template content, start the interview
-3. 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. rewrite `gcf/PILLARS.md` with the confirmed pillars in the pillars record-list form
-5. run `npx cnlp check` and fix form issues it reports
-6. ask the human to run `ai-factory gcf hooks-install`: the commit gate is theirs to arm
-7. state the next step: fill `gcf/backlog.md` with candidates by hand or import a GDD
+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
+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
+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`
 
 invocation:
 - run when the user asks to set up gcf in a project

package/skills/gcf-verdict/SKILL.md

@@ -22,7 +22,7 @@ forbidden_behaviors:
 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 (GCF-PRD §7.2)
+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

package/templates/backlog.md

@@ -1,4 +1,5 @@
 # Backlog — candidates, one line each. Order = priority, owned by the human.
-# Format: - <cand-id> | <name> | route: soft|hard | sys: <system> | deps: <ids or -> | src: <GDD#id|manual> | <one-line description>
-
-- cand-001 | example move | route: soft | sys: example-system | deps: - | src: manual | the move this template illustrates
+# 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