aetherbound-guild/AGENTS.md

# Aetherbound Guild Agent Contract

This file narrows the portfolio rules for this repository.

## Aetherbound Visual Direction Override

The portfolio-level pixel-art production rule does not apply to Aetherbound
Guild. This repository's Owner-approved product authority is an original
landscape Japanese 2D hand-drawn fantasy presentation:

- thin-line, cel-color actors whose proportions follow the accepted reference
  and remain readable at actual play size;
- softly painted environments with editable depth layers;
- ordinary battle units sized to preserve the complete Company line, enemy
  relation and movement corridor, with final scale confirmed from a real frame;
- compact field-attached HUD chrome rather than a card wall; and
- engine-rendered text and values over non-pixel runtime art.

The `05_battle_ui_japanese_scale.png` file under
`docs/prototype/generation/phase6_ui_direction_01/outputs/` is the accepted
battle-scale direction.
`docs/01_GAME_DESIGN.md` and `docs/04_ART_ANIMATION_AUDIO.md` remain the
product and style authority. Pixel
art, nearest-neighbor conversion, low-resolution palette reduction and
post-process pixelation are prohibited for final Aetherbound presentation.
Existing pixel runtime assets are rejected historical candidates: preserve
their provenance, but do not expand or treat them as accepted visual authority.

## Plan-Driven Development

Every non-trivial implementation milestone must have one active durable plan
before product code changes continue. The active plan is named by
`CURRENT_CHECKPOINT.md` and lives beside the milestone contract under `docs/`.
This repository contract contains the mandatory planning and execution process.

- The plan must define the player-visible stopping point, ordered steps,
  acceptance checks, frozen scope, commit boundaries and final handoff.
- Exactly one step may be `IN_PROGRESS`. Code changes must belong to that step.
  New findings are recorded in the plan's issue register and do not silently
  expand the active step.
- Finish the narrowest focused verification and create a focused pushed commit
  before changing the next step to `IN_PROGRESS`.
- Update the plan and checkpoint after an actual status change, not after every
  command. Chat summaries never replace the durable status.
- A failed check keeps the same step active. Repair the earliest failed product
  boundary; do not skip ahead, loosen the check or start unrelated polish.
- Packaging, deployment and release remain separate steps and require the
  owner's explicit authorization even when they appear in a future plan.
- A milestone ends at its written stopping point. Further systems require a new
  plan or an explicit revision approved by the owner.

## Current Stage

The complete-game program has verified functional gameplay through the RG-04
midpoint. Owner review rejected the midpoint pixel-art H5 on 2026-08-17 because
it contradicts the accepted Japanese 2D hand-drawn direction. The Owner has
now approved an entry-first redevelopment order.

The only first implementation step is `DEV-1`: real Godot boot, first-launch
setup, Title and essential Settings reached in player order. Later steps add
new-run selection, Guild, Market, automatic formation, risk, battle, result and
continuation in that order. Gameplay, economy, content, Save and audio semantics
remain unchanged until their named step. No historical Phase, Goal, test attempt
or H5 document is current authority merely because it still exists in Git
history.

## Test Attempt Hygiene

- Fresh Git archive/import, capture, MovieWriter, Web and Playwright evidence
  commands must run through `tools/run_test_attempt.py` unless the active Goal
  names a stricter checked-in runner. The command owns one source/HOME/cache/
  TMP/browser root and removes it after archiving compact evidence on success,
  failure, timeout or handled interruption.
- The attempt runner must block handled termination signals while it creates
  and marks the owned root, then restore delivery only after its cleanup guard
  is active. A signal during startup is not permission to leave an unowned or
  half-initialized source/import root behind.
- Cleanup owns the complete child process group, not only the immediate shell.
  After timeout or interruption it must TERM, wait, KILL only if required, and
  retry removal after browser writers exit before recording the terminal.
- A zero child exit is not sufficient. Godot/runtime diagnostics remain strict,
  and formal calls must pass each expected terminal with `--require-marker`;
  every required marker must appear exactly once before the runner records PASS.
- Test commands write retained artifacts only below `ABG_EVIDENCE_DIR`. Do not
  place source archives, Godot import caches, browser profiles, raw Chrome
  code-signing copies or temporary HOME directories there.
- The default retention ceiling is three unprotected passed attempts and three
  unprotected failed attempts per label. `FAIL`, `TIMEOUT`, `INTERRUPTED` and
  `HARNESS_ERROR` share the same failed-attempt ceiling. Every terminal remains
  in the compact append-only `attempts.jsonl` journal.
- A retained attempt referenced by tracked authority or marked with `.keep` is
  protected from runner pruning. Never use the runner to delete older evidence
  roots created outside its own artifact family.
- Repository Playwright checks must install `tools/browser_temp.js` before
  requiring Playwright. It confines Chrome profiles/artifacts/signing copies to
  an owned root, cleans normal/signal exits and removes stale owned roots on the
  next invocation.

## Originality Boundary

- Authorized private reference material may be inspected only to identify
  systems, player decisions, content categories, pacing patterns, and production
  scope.
- Do not copy reference names, prose, formulas, layouts, progression trees,
  source code, art, music, sound effects, or other expressive assets.
- Do not place third-party commercial assets in this repository.
- Every product-facing design must be independently authored and traceable to
  this game's approved product contract.

## Design Completion Gate

Formal development remains frozen until all of these are complete, mutually
consistent, independently reviewed, and owner-approved:

1. Product and player-experience contract.
2. Core loop, battle, profession, skill, progression, economy, failure, save,
   difficulty, and postgame specifications.
3. Complete generated-recruit rules; 12 base, 24 advanced, and 6 hidden
   professions; 36 mechanical traits; 320 equipment items; 60 artifacts;
   100 ordinary/elite enemies; 16 bosses; and 8 regions, with no filler rows.
   Recruits are not fixed story protagonists and do not require relationship,
   affinity, romance, personal-arc, or individual voice-content systems.
4. Complete screen/state map, onboarding, accessibility, localization, input,
   error, empty, confirmation, settings, and endgame states.
5. Art direction, asset inventory, animation matrix, VFX language, music plan,
   and SFX event catalog.
6. Landscape HTML design gallery showing every player-facing page and key state.
7. Economy/build simulations and a decision-density audit.
8. Interactive design prototype and owner review.

Owner visual/feel acceptance applies only to the bounded P9.0R3 tutorial
battle presentation. Human listening, broader comprehension/fun, device,
packaging, store, and release acceptance remain separate gates. P9.0R3 does
not authorize the later authoritative battle system.