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.