Skip to content
Programming Bible

Trait columns · quality hybrid Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Replace the single/dual TraitId gate with quality-gated Trait columns (Bullets · MagFeel · Plate · Verb) plus Origin, place every existing weapon Trait in the correct column, expand MagFeel, and support a craft/inventory hybrid for changing picks.

Architecture: Each unlocked column holds a pool; the player activates one Trait per column. Gate 2026-11-13d: guns Common none · Uncommon Verb · Augmented Feed+Verb · Rare Bullets+Feed+Verb · L/U/Apex +Plate; armor/shield Shell·Stride·Brace·Verb on the same unlock counts; jewelry none; Unique 1 Origin + optional Set; Apex 2 Origins + optional Set. Mag/Barrel meshes stay Refit-only. Catalog rows gain column; plates stay separate (weapons gate + armor gate).

Column rename (locked): Data id Feed (ex-MagFeel). Inspect / HUD label = {MagFamily} Spec (e.g. Cell Spec · Drum Spec · Quiver Spec · Box Spec) from existing MagFamily — no Crafting Refit rename, no MagFamily enum change. Rejected: MagFeel, Mag Refit.

Tech Stack: Pack docs (design · FS · PB) · tfa_trait_origin_catalog_v1.json · tfa_trait_column_map_v1.json · Demo Mod / Inspect mocks · GDD section + quality-gate plate (later)

Global Constraints

Section titled “Global Constraints”
  • No mid-fight multi-column perk chore UI — swaps are Inventory/Inspect out of combat (Unique/Apex) or Crafting Rewrite (lower).
  • Refit never writes TraitId* / OriginId / column unlocks (existing FS-CRF-011 / FS-ITM-010 spirit).
  • Mag / Barrel / Optic remain modular parts; Trait columns own effects that used to live on barrel/mag perk columns.
  • AlwaysOn / Ambient only — no Kill Clip–style activation chores.
  • Cap 4 Trait columns + Origin at Apex — do not add a 5th Trait column.
  • Verb column is mixed families (mixed Verb-column style). Bullets / Feed / Plate are typed.
  • Do not rename Crafting Refit. Feed column is Traits-only; MagFamily player words stay as-is.

Locked design

Section titled “Locked design”

Columns

Section titled “Columns”
Column Role Pool style
Bullets What the shot does (payload, pellet density, band/shield damage, channel-on-shot) Typed AlwaysOn packs; multi-mod fields allowed
Feed (ex-MagFeel) Mag / ammo economy (overflow, scavenger, kill refund rounds, reserve drain, empty-mag panic) Data id Feed. Player label {MagFamily} Spec. Typed AlwaysOn / ammo Ambient; multi-mod OK
Plate Gunfeel (range falloff, flinch, sway, bloom, slide accuracy retain, brace, ready/handling settle) Typed AlwaysOn (+ settle Ambient that is gunfeel, not ammo)
Verb Mixed combat verbs (reload-on-X, DoT ticks, chains, utility bites, parkour-gunfeel triggers) Mixed families — mixed Verb-column style
Origin Authored identity (unchanged buckets) Unique 1 · Apex 2 (OriginId2)
Set Optional 2–6 thresholds Unique/Apex only (Rare never Set)

Quality gate (weapons 2026-11-13c · full pack 2026-11-13d dual tables)

Section titled “Quality gate (weapons 2026-11-13c · full pack 2026-11-13d dual tables)”
Quality Trait columns Origin / Set
Common — (none) —
Uncommon Verb —
Augmented Feed + Verb —
Rare Bullets + Feed + Verb —
Legendary Bullets + Feed + Plate + Verb —
Unique Bullets + Feed + Plate + Verb (same as Apex) 1 Origin · optional Set
Apex Bullets + Feed + Plate + Verb (same as Unique) 2 Origins · optional Set

Feed label = {MagFamily} Spec. Crafting Refit unchanged. Legendary opens Plate but never Origin. Unique and Apex share Trait columns; Apex runs dual Origin. Rare never Set and never Origin.

Pool size (choices offered / rolled onto the instance) scales up with quality inside each unlocked column — exact counts = Lab dials / TBD ship numbers.

Placement rule (how to put Traits in the right column)

Section titled “Placement rule (how to put Traits in the right column)”
  1. MagFeel if the Trait is primarily mag/ammo economy (fill, refund rounds, reserve, empty reload panic, scavenger bricks).
  2. Else Bullets if it changes shot/payload/target damage bands / pellet / shield-vs-bullet (AlwaysOn damage identity).
  3. Else Plate if it changes gunfeel settle (accuracy retain, flinch, sway, bloom, brace, ready/handling without being a reload-on-event verb).
  4. Else Verb — including reload-on-kill / slide / hip / sprint (those are Verb-column verbs, not MagFeel).

Authoritative id lists: docs/superpowers/specs/tfa_trait_column_map_v1.json

Column Count (WT-01…120) Ids
Bullets 24 WT-05,09,11,21,25,28,56–58,61,63–65,68–70,83–86,90,97,98,103
MagFeel 11 WT-01–04,34,43,72,76,77,89,111
Plate 30 WT-07,08,10,12–14,23,24,27,29,32,39,40,46–48,53–55,62,67,71,78,80,101,102,105–107,114
Verb 55 All remaining WT (incl. WT-31/36/66/73/74 reload-on-X, DoT ticks, chains, parkour glues)

Note: MagFeel is thin (11). Expand with the MagFeel backlog below (~+20) before ship pools feel fair — do not steal Verb reload-on-X into MagFeel.

Feed expansion backlog (ideas → new WT rows)

Section titled “Feed expansion backlog (ideas → new WT rows)”

Keep these ammo / mag-state only (AlwaysOn or ammo Ambient). Reload-on-event stays Verb. Column id in data: Feed (map JSON may still say MagFeel until rename stamp).

Working name Feel Suggested magKey
Top-Off Discipline Partial reloads waste less reserve partialReloadRefundPct
Deep Clip / Deep Drum Larger mag, slower top-off magSizePct + reloadSpeedPct trade (mods[])
Slim Clip / Slim Cell Smaller mag, snappier reload inverse of Deep Clip
Twin Stack / Helix Clip / Offset Feed Alternate pack geometry fantasy magSizePct / handling trade
High-Density Pack / Loose Pack / Compression Load Density vs snappy seat mods[]
Hot Swap Cell / Holster Prime First reload after holster is faster holsterReloadCutPct
Brick Magnet / Brick Pull / Brick Bias Ammo bricks grant bonus rounds more often brickChancePct
Twin Brick / Double Brick Occasional double brick on pickup doubleBrickChancePct
Caliber Match / Matched Caliber Matching ammo type bricks fill more matchBrickBonusPct
Reserve Vault / Reserve Lid / Vault Siphon Soft cap on reserve drain (ADS or general) adsReserveDrainCutPct
Belt Feed / Belt Catch / Latch Reload Continuous-feed kits resist dry-fire gap feedGapCutPct
Chamber Keeper / Chamber Ride / Keeper Pin / Mercy Chamber Reload keeps one round chambered more often chamberKeepChancePct
Tactical Topper / Tactical Prime Tactical (not empty) reloads fill extra tacticalBonusFillPct
Panic Drum / Empty Snap Empty-mag reload dumps a burst from reserve emptyReserveDumpPct
Soft Seat / Partial Mercy Partial reload efficiency / seat forgiveness partialReloadRefundPct
Siphon Clip / Precision Crumb Precision kills refund rounds into mag (not Verb reload speed) precKillRefundRounds
Assist Cell / Assist Crumb Assists refund tiny mag crumbs assistRefundRounds
Streak Cell / Multi-Kill Drop / Finish Refund Streak/finish crumbs into mag streakRefundRounds
Hip Crumb / ADS Crumb / Weakspot Return Situational crumbs *RefundRounds
Objective Hoard / Objective Tick Holding objective slowly tops mag from reserve objMagTick
Cover Feed / Cover Tick / Brace Top-Off / Anchor Feed Behind cover / braced, mag ticks from reserve coverMagTick
Sprint Starve / Sprint Sip Sprinting drains reserve slightly slower sprintReserveCutPct
ADS Appetite / ADS Thirst ADS slightly thirstier reserve, denser mag feel trade mods[]
Cold Mag / Cold First Mag First mag of engagement has bonus fill firstMagBonusPct
Warm Drum / Warm Mag / Aftershock Fill After N kills this mag, next reload refunds warmReloadRefundPct
Split Feed / Split Hopper / Dual Buffer Dual-mag / fire-mode buffer fantasy splitFeedBuffer
Scavenger Quiet / Quiet Pickup Faster brick pickup commit brickPickupCutPct
Overpack Soft / Side Pocket / Ghost Round / Failsafe Round / Echo Cell Tiny overflow pocket (not full Overflow Mag) sidePocketRounds
Dry Click Mercy / Dry-Click Grace After dry fire, next reload starts already hot dryClickReadyPct
Swap Prime / Second Wind Cell After weapon swap, soft mag grace swapReloadCutPct
Extended Spine / Staggered Rounds / Parasite Feed Long-pack / exotic feed fantasy magSize or siphon Ambient

Target: Feed ≥ 35 rows (11 existing MagFeel + backlog). Final names/mags TBD at catalog stamp.

Instance schema (replaces TraitId / TraitId2-only gate)

Section titled “Instance schema (replaces TraitId / TraitId2-only gate)”

Per weapon instance:

  • traitBulletsId · traitMagFeelId · traitPlateId · traitVerbId — active pick; empty if column locked for quality
  • trait*Unlocked[] — Unique/Apex (and Rare if we grant unlock lists later); Common→Legendary store rolled single / small set for Rewrite
  • Magnitudes: keep per-Trait magKey dials; add optional mods[] for multi-stat AlwaysOn packs on Bullets/MagFeel/Plate
  • originId · originId2 (Apex only; empty elsewhere; must differ from originId) · setId (Unique/Apex only; Rare fail-closed)

Apply order (unchanged spirit): Affixes → active Trait columns (Familiarity may scale Trait mag) → Origin(s) on Unique/Apex → sockets → Set → Artifact → Masterwork finish.

flowchart LR
  quality[Item quality]
  cols[Unlocked Trait columns]
  pick[One active Trait per column]
  refit[Refit Mag Barrel Optic]
  craft[Crafting Rewrite or unlock]
  inv[Inventory swap Unique Apex]
  quality --> cols --> pick
  refit -.->|never writes Traits| pick
  craft --> pick
  inv --> pick

File map

Section titled “File map”
File Responsibility
docs/superpowers/specs/tfa_trait_column_map_v1.json Authoritative WT → column lists (shipped with this plan)
docs/superpowers/specs/tfa_trait_origin_catalog_v1.json Add column on each WT; expand MagFeel; optional mods[]
docs/superpowers/specs/2026-11-10-traits-origin-set-perks-design.md Rewrite quality gate + column hybrid
New: docs/superpowers/specs/2026-11-13-trait-columns-quality-hybrid-design.md Design lock mirror of this plan
Terra_Firma_Functional_Specification.md Replace FS-ITM-010 table; instance fields; Forge/Rewrite; TBD-064
docs/30-traits-origin-sets.md · 13 · 19 · demo-mod specs PB + mock field contracts
GDD traits-origin-quality-gate + plate Teaching still remake (Grok, 1280×720)
Demo Mod + Inspect Column UI by quality; Apex swap among unlocked

Out of scope until ordered: UE ASC wiring, final pool size numbers. Armor Trait columns (Shell·Stride·Brace·Verb) + jewelry exclusion locked 2026-11-13d — see design + tfa_armor_trait_column_map_v1.json.

Task 1: Design lock + column map (docs)

Section titled “Task 1: Design lock + column map (docs)”

Files:

  • Create: docs/superpowers/specs/2026-11-13-trait-columns-quality-hybrid-design.md

  • Modify: docs/superpowers/specs/2026-11-10-traits-origin-set-perks-design.md

  • Keep: docs/superpowers/specs/tfa_trait_column_map_v1.json

  • Write design lock (columns, quality ladder, hybrid swap, placement rules, MagFeel expansion need).

  • Point 2026-11-10 spec at the new gate (deprecate TraitId/TraitId2-only stacking prose).

  • Confirm map counts Bullets 24 / MagFeel 11 / Plate 30 / Verb 55 and list MagFeel expansion as open fill.

Done when: Design specs agree with this plan; map JSON is the placement authority.

Task 2: Catalog — stamp column + expand MagFeel

Section titled “Task 2: Catalog — stamp column + expand MagFeel”

Files:

  • Modify: docs/superpowers/specs/tfa_trait_origin_catalog_v1.json

  • Script: tfa_gdd_html/figures/ stamp helper (optional)

  • Add "column": "Bullets"|"MagFeel"|"Plate"|"Verb" to every weaponTraits row from the map.

  • Add MagFeel backlog rows (~20) from this plan so MagFeel ≥ 30.

  • For Bullets/MagFeel/Plate AlwaysOn packs that need multi-stat barrel/mag feel: add optional mods[] { key, default, unit, min, max } without removing single magKey dials.

  • Do not move reload-on-X Traits out of Verb.

  • Stamp column + wire Rare originId2 in catalog/docs notes.

Done when: Every WT has column; MagFeel count ≥ 30; verify script checks map ↔ catalog.

Task 3: FS + PB + TBD-064

Section titled “Task 3: FS + PB + TBD-064”

Files:

  • Terra_Firma_Functional_Specification.md (FS-ITM-010, Forge, Rewrite, instance fields)

  • docs/30-traits-origin-sets.md, docs/13-progression-itemization.md, docs/19-tbd-and-traceability.md

  • Arch / FE specs as needed

  • Replace quality table with column ladder above.

  • Lock TBD-064: Common→Legendary Rewrite changes Trait column picks; Unique/Apex Crafting unlocks options; Origin never Rewrite.

  • Rebuild FS HTML after FS edit.

Done when: FS shalls match hybrid; pack verify needles updated.

Task 4: Demo Mod + Inspect mocks

Section titled “Task 4: Demo Mod + Inspect mocks”

Files:

  • tfa_gdd_html/figures/demo_mod_mock_data.js / _app.js / demo_mod_mock.html

  • tfa_gdd_html/js/gui.js Inspect verb strips

  • Expose column fields by quality (hide locked columns).

  • Unique/Apex: select among unlocked for each column.

  • Common→Legendary: single active + note “change at Rewrite”.

  • Lab dials for pool sizes optional.

Done when: Common hides Trait strips; Uncommon Verb; Augmented Feed+Verb; Rare 3; Legendary/Unique/Apex 4; Unique 1 Origin; Apex 2 Origins.

Task 5: GDD section + teaching plate

Section titled “Task 5: GDD section + teaching plate”

Files:

  • tfa_gdd_html/js/gdd-content.js quality-gate section

  • tfa_gdd_html/figures/tfa_trait_origin_quality_gate.jpg (Grok remake 1280×720)

  • Rewrite gate HTML/table for 2026-11-13c ladder.

  • Remake plate: Common none · Uncommon Verb · Augmented Feed+Verb · Rare 3 cyan · Legendary +Plate · Unique gold +1 Origin · Apex purple +2 Origins.

Done when: GDD + plate match FS; pack verify PASS.

Task 6: Verify + graphify

Section titled “Task 6: Verify + graphify”
  • Extend _verify_trait_origin_pack.py for column field + map consistency.
  • graphify update .

Done when: RESULT PASS.

Acceptance

Section titled “Acceptance”
  • Column count: Common 0 < Uncommon 1 (Verb) < Augmented 2 (Feed+Verb) < Rare 3 (Bullets+Feed+Verb) < Legendary/Unique/Apex 4 (+Plate).
  • Unique = four Trait columns + 1 Origin + optional Set; Apex = four + 2 Origins + optional Set; Rare/Legendary never Origin/Set.
  • Traits sit in the mapped columns (reload-on-X in Verb; overflow/refund in Feed; slide accuracy retain in Plate; payload/band damage in Bullets).
  • Feed catalog ≥ 35 after expansion backlog.
  • Lower quality = fewer columns + smaller pools; Unique/Apex out-of-combat unlock swap; Refit never edits Traits.
  • Mag/Barrel remain modular parts.
  • Quality chrome LOCKED: Rare cyan #00d4ff · Unique antique gold #c9a227.