Riftbound Chronicle

A bounded Riftbound rules engine, and the evidence-aware assistant built
on top of it.

What this is — a versioned clause grammar that compiles printed card text
into typed programs, a capability manifest the engine derives from its own
source, and machine-checked evidence for covered mechanical conclusions.

What this is not — a game simulator, an official rules authority, or an
automated player. Coverage is measured and published; the parts the engine
cannot read say so by name rather than guessing.

繁體中文 · 한국어

Keywords: Riftbound AI agent, deck coach, rule consult, Player 2 agent, TCG
deckbuilding, gameplay assistant, Claude Skill.

Why this exists

A language model can "judge" a card interaction without any of this machinery.
It will just be judging by plausible-sounding text continuation, which is not
the same thing as legality. It will read a Reaction card and conclude you may
insert it at the end of a Showdown to add Might, because that reads fine — and
it is not a legal play.

So the program owns the mechanical part. When you may play what, what can be
responded to, how priority passes, what the current score and costs and Might
actually are: these are rule-governed and arithmetic, and handing them to a
model invites drift. Even the strongest model will still tell you 8.11 is
greater than 8.9 unless something checks the number.

The model then reasons inside the space the program has already constrained,
under the same external constraints as the real rules. That is the whole
design: not translating the rules so the model can read them, but bounding
what the model is allowed to conclude.

Today the program owns timing and permission. Full legality is still
confirmed by the human — see the Player 2 boundary below — and automated rules
enforcement is not currently approved by Riot in any case. Enumerating legal
actions is a planned release gated on conformance coverage, not on collecting
more game records first.

The project is split into three systems with deliberately different authority:

Engine connection

A system counts as connected only when all six checklist conditions pass:
artifact accepts the envelope, runner produces it, validator rejects overclaims,
UI renders the outcomes, regressions cover a supported and an abstaining case,
and the authority boundary survives. skill/scripts/check_readme_connection_claims.py
derives this table from the artifacts and fails if the table drifts either way.

Deck Coach consumes the envelope as rules-consistency evidence only (ADR-0006):
attaching a check never changes the diagnosis or primer, and it produces no
checks of its own. Match Analyst is specified, fixtured, and not routed.

The current Player 2 implementation is P2-A: the Agent recommends and
explains an action, then waits for the human to confirm legality and the resulting
state. The future P2-S simulator is documented but is not implemented.

All systems share a Chronicle-owned sovereign rules core, and it only ever
claims what its conformance suite executes:

• a timing and permission kernel for the four turn states, Action/Reaction,
  Priority/Focus, and HOT/FEPR —
  21 executable cases (skill/data/rules_core_cases.json);
• a bounded typed-effect IR — 21 operations plus sequencing, targets, linked
  effects, lethal cleanup, and trigger emission, which fails closed on any
  card behaviour it does not model rather than guessing one;
• an atomic bridge between the two, so a timing decision and its typed effects
  commit together or roll back together.

It has no runtime dependency on another fan simulator, and it does not claim
complete card-effect resolution — the unsupported outcome is a first-class
result, not an error path. See the
sovereign rules-layer architecture
and ADR-0001 for why this
layer exists at all after two audits advised against one.

A fourth system, match-analyst (post-game Review and Commentary over one
normalized timeline), is fully specified but deliberately not routed until
its activation gates pass — see
the spec. The table above
lists what the Skill router actually exposes today.

All four sit in the preparation phase; none of them plays the game.
Construction, knowledge, practice, review — the game itself is played by people,
away from this. That is why an authoritative rules engine, including an official
digital client should one ship, would strengthen these rather than replace them:
such an engine serves play, and this serves preparation.

This is an assistant for preparation, built for research and educational use.
Using it during an event is against tournament rules — see
the compliance boundary for the
governing clauses.

The repository name intentionally stays riftbound-chronicle: it is the product
brand. Search terms such as AI agent, deck coach, and rule consult belong in
the GitHub description, topics, README, and Skill metadata rather than replacing
the brand name. See the GitHub discovery metadata.

Quick start

Requirements: Git and Python 3.10 or newer. The static demonstrations need no
package installation or build step.

Clone the repository, then run a complete Deck Coach case:

git clone https://github.com/Zaious/riftbound-chronicle.git
cd riftbound-chronicle
python skill/scripts/deck_coach_pipeline.py run `
  --case-id DC-RNG-GLOBAL-001 `
  --output-dir deck-coach-output

The command writes five reviewable files:

deck-coach-output/
  input.json
  profile.json
  mask.json
  primer.json
  evaluation.json

Open any demonstration directly in a browser:

• Deck Coach review workspace
• Rule Consult evidence workspace
• P2-A practice workspace

The pages are local, dependency-free demonstrations. They do not call a model,
persist browser data, or silently automate rules. Each one exposes the artifact
contract that a model or product integration would use.

Deck Coach closed loop

Deck Coach does not send a bare card-name list directly to a language model. It
first creates a structured observation that can be inspected and graded:

decklist + environment + player level
  -> structured deck profile
  -> recommendation mask
  -> eight-section primer
  -> seven-dimension evaluation
  -> optional blind A/B primer battle

The profile records:

• Legend and Chosen Champion;
• format, region, legal set pool, and player level;
• Energy curve, Domains, and Power requirements;
• unit, spell, Gear, and Battlefield mix;
• eight qualitative card roles;
• interaction, draw/selection, recursion, and movement density;
• engine anchors and candidates;
• provenance, confidence, and unresolved data gaps.

Before recommending cards, the mask rejects candidates that are known to be:

• unreleased in the selected environment;
• banned in the selected format;
• outside the Legend's Domain identity;
• unavailable in the player's collection;
• based on stale pre-errata text; or
• drawn from a mismatched tournament environment.

The bundled legality snapshot is only a dated input. A real recommendation must
still re-check current official sources.

There are 5 executable cases in skill/data/deck_coach_cases.json: a global
Rengar deck, a Taiwan Rengar environment, an Annie mask stress case, a Legend
that is legal in 1v1 and banned in 2v2, and a fully legal deck where the
player's collection is the only thing constraining the advice. The evaluation contract scores:

1. card and rules facts;
2. format and regional legality;
3. deck identity;
4. engine recognition;
5. actionable advice;
6. evidence and confidence; and
7. correct abstention.

The deterministic evaluator is a regression-test proxy, not an expert or a
claim of strategic truth. Primer battles therefore keep automatic preference and
human expert preference as separate fields.

See Deck Coach evaluation plan and the
Deck Coach method.

Rift Atlas handoff

The repository also includes an offline bridge for a user-pasted Rift Atlas
decklist. It records a public deck URL as provenance, then writes the existing
Deck Coach input, profile, recommendation mask, eight-section primer scaffold,
and a human-readable brief:

python skill/scripts/riftatlas_bridge.py `
  --source-url https://riftatlas.com/decks/community/DECK_ID `
  --deck-file decklist.txt `
  --environment global-vendetta `
  --player-level new `
  --output-dir riftatlas-output

The adapter does not scrape Rift Atlas, call a private API, or automate
gameplay. Partnership drafts and unaccepted localization material are kept
outside the public repository until the other maintainer agrees to publish
them.

Deck closure

Two Master Yi decklists are engine-closed in Chronicle's private licensed
overlay and can generate evidence-backed Deck Coach primers. The evidence is a
rules-consistency and coverage check only: it is not a complete game simulator,
an official ruling source, or an automated player.

A closure is verified by re-derivation, not by trusting a stored file: every
deck slot is rechecked against the live engine, current card text, and—where
applicable—the current grammar or private card-program pack. The resulting
program and evidence receipt must match. The public repository carries the
contracts and verifiers this uses; the closures themselves, their licensed deck
snapshots, card mappings, and Deck Coach artifacts are private overlay data.

Rule Consult

Rule Consult is for players who need a careful explanation, including detailed
interactions, without pretending that the assistant is an official judge.

Every answer separates supplied facts from assumptions and records:

• the question and relevant game state;
• the controlling rule or tournament procedure;
• source URL, document version, and checked date;
• analysis and conclusion;
• confidence and unresolved ambiguity;
• escalation to the live Head Judge when appropriate;
• official_status: unofficial and state_effect: none.

For tournament procedure, the working precedence is event addendum, Tournament
Rules, Core Rules where unmodified, then the live Head Judge. The versioned
source registry prevents the Core Rules
PDF from being treated as a complete or permanently current authority.

See Rule Consult method and the
rule corpus engineering note.

Optional local rule documents

The public repository does not commit Riot-owned rule documents. When exact clause
work is needed, install the controlling English pair locally. The optional
Simplified Chinese pack adds regional rules, FAQs, errata, and separately
labeled judge guidance:

python skill/scripts/bootstrap_rules.py --yes
python skill/scripts/bootstrap_rules.py --include-supplemental-en --yes
python skill/scripts/bootstrap_rules.py --include-zh-cn --yes
python skill/scripts/rules_index.py build
python skill/scripts/rules_index.py search "連鎖 結算"

Selected files go into the ignored skill/.local/rules/ directory with a local
SHA-256 lock and a page-addressable SQLite index. Results retain source,
version, locale, authority, page, and rule locator; they are evidence candidates,
not automated rulings. The English supplemental pack includes errata PDFs and
an HTML snapshot of the superseded Origins FAQ; default search masks that FAQ.
A custom location is available through
RIFTBOUND_RULES_DIR or --rules-dir. English controls translation conflicts,
and superseded sources are excluded from current search by default.

Player2 Agent

P2-A supports one person practising with two physical decks while the Agent
chooses a strategic direction for Player 2. The ledger permits three event types:

human confirms visible state
  -> Agent proposes an action and rationale
  -> human confirms legality
  -> human resolves it physically and confirms the new state

The Agent cannot inspect opponent hidden information, claim that its proposal is
legal, infer the post-resolution state, or enable P2-S behaviour. Automated
shuffling, draws, rules enforcement, combat resolution, scoring, winner
determination, self-play, and reinforcement learning are outside this runtime.

See the P2-A product specification and
P2-S future proposal.

Source authority

The shared authority model is:

1. current official Riot rules, tournament documents, errata, ban lists, and
   product announcements;
2. official card text available to the project;
3. reputable community material for observed play and terminology;
4. explicit inference, labelled as inference;
5. unknown, when the evidence does not support a conclusion.

Sources keep provenance and effective dates. Card facts, legal environments,
observed strategy, and model inference are not interchangeable.

The bundled card snapshot contains 1,451 rows and 1,304 unique card IDs from the
unofficial RiftCodex API. It makes this Skill portable, but a clean clone cannot
regenerate the file byte-for-byte and it is not official Riot API data. Read the
data provenance and limitations before redistributing or
building a public product from it.

Repository map

Design rationale worth reading before changing the rules layer:
ADR-0001 (why a rules layer
exists after two audits advised against one, and what it does not claim),
RELATED_WORK (where this sits in published
work), and ITERATION_INPUTS (research that
should change what gets built next).

skill/
  SKILL.md          mode router
  references/       system methods and shared source policy
  data/             cases, environment snapshots, registries, card snapshot
  schemas/          versioned JSON artifact contracts
  scripts/          CLIs, evaluators, and deterministic checks
prototype/
  deck-coach/       profile, mask, primer, and evaluation review
  rule-consult/     cited consultation and evidence ledger
  p2a/              human-confirmed practice session
docs/
  product/          product scope
  architecture/     three-system boundaries
  evaluation/       evaluation design
  player2-agent/    P2-A specification and gated P2-S proposal
  policy/           Riot boundary and application package
  audits/           dated independent and implementation reviews

Start with product scope, then read the
systems architecture.

Validation

Run every deterministic gate, exactly as CI does — the loop discovers the
checks on disk, so it cannot drift out of date the way a hand-copied list can
(this list previously omitted four gates, including the rules-core ones):

Get-ChildItem skill/scripts/check_*.py | ForEach-Object {
  python $_.FullName
  if ($LASTEXITCODE -ne 0) { Write-Error "FAILED: $($_.Name)" }
}

.github/workflows/ci.yml is the authority on what runs on push; it also
re-runs the suite from a directory outside the repository to prove the scripts
do not depend on the working directory.

Compliance

This repository intentionally does not publish or retain win rates, play rates,
matchup rates, or tier rankings. It does not claim official judge authority and
does not automate a Riftbound match. See the dated
Riot compliance boundary for the full
product interpretation and open questions.

Two important issues remain open:

• Riot product registration or written approval is not represented as granted.
• The bundled card data comes from an unofficial community API rather than an
  official Riot API source.

Those limitations are recorded plainly so a prototype cannot be mistaken for an
approved public deployment.

Roadmap

• expand full-deck expert-reference cases and regional environments;
• collect blind expert preferences for real model-generated primers;
• replace unofficial card data with an approved, reproducible source adapter;
• connect the three artifact contracts to a model without weakening their
  authority boundaries;
• keep P2-S planned but unimplemented unless Riot approval and a separate product
  decision justify opening that gate.

What is open, and what is not

The public repository ships the reusable engine, schemas, verifiers, and
synthetic fixtures. Licensed card programs, deck snapshots, and the two
evidence-backed deck closures live in the private overlay and are not
included in a public clone.

This repository is the verifiable base of Riftbound Chronicle, and it is
deliberately the whole of that base: the rules engine, every gate, the schemas,
the ADRs, the clause-grammar.v1 contract with all of its productions, the
Wave A seed corpus, and verify_evidence_pack.py. Anyone can re-run an
evidence pack the service emits with nothing but this repo, because the
service's authority claim is that its answers can be re-run by someone who is
not us.

What is not here, and will not be: the compiled card corpora from Wave B
onward, the coverage debt over them, the deck snapshots, the card mappings that
tie a reading the rules leave open to a real card, the deck closures and their
Deck Coach artifacts, the state builder, the fact-ledger gate, the evidence-pack
assembly, the consult command, and the question corpus. Those
are the labour and the product, and they live in a private overlay that pins
this repo as a submodule and reads extra packs through CHRONICLE_PACK_PATHS
without editing anything here.

The line is drawn so the two do not conflict: re-runnability is per
answer — an evidence pack discloses the programs that one answer used — while
the corpus is per service. Pull requests that add a card program pack
beyond the public seed are closed; see CONTRIBUTING.md.

License and Riot notice

Original code and methodology are licensed under the
GNU Affero General Public License v3.0. Versions released before the
licence change remain available under the MIT licence they were published
with. Contributions of code, data or documentation require the
Contributor License Agreement; reporting an issue does not. The
bundled card names, rules text, and other Riot-owned material are not covered
by either grant; see skill/data/README.md for
provenance.

Riftbound Chronicle was created under Riot Games' "Legal Jibber Jabber" policy
using assets owned by Riot Games. Riot Games does not endorse or sponsor this
project.

Riftbound Chronicle is an unofficial fan project and is not affiliated with Riot
Games.