gf-framework-maintenance

name	gf-framework-maintenance
description	Maintain GF Framework source, docs, tests, API surface, generated references, and maintenance tooling. Use when Codex modifies addons/gf, tests/gf_core, docs/zh, API docs, tools, AI maintenance policy, or needs to choose GF-specific validation commands.

GF Framework Maintenance

Use this skill as the default project workflow for GF Framework maintenance. It does not replace AI_MAINTENANCE.md, CODING_STYLE.md, or API_SURFACE.md; those files remain the authority.

Start

1. Read AI_MAINTENANCE.md first. Read CODING_STYLE.md before editing .gd files. Read API_SURFACE.md before changing public API, API comments, section layout, or generated API docs.
2. Run python tools\gf_maintenance.py workspace-status --json to classify current changes before choosing checks. If ordinary work starts from a clean synchronized main, create a short-lived branch that satisfies .github/repository-policy.json before editing. Preserve an existing user branch or dirty worktree; never move unrelated work just to satisfy this default. In a dirty long-running workspace, pass repeated --path <file> arguments for the current turn's touched files before using the global recommendation list.
3. Use lightweight python tools\gf_maintenance.py summary or the API commands (api-search, api-class, api-module) to gather context before scanning broad source trees. Use summary --release --artifact-manifest <path> only after the immutable release artifact set exists.
4. Keep ai_analysis/ ignored and out of commits. Write diagnostic logs only under ai_analysis/godot_logs/, never as .gf/*.log or beside source files. Do not submit temporary reports, generated AI API summaries, local logs, or session notes. Successful maintenance commands remove their session-owned logs and legacy top-level .gf/*.log files automatically without touching package state; use --keep-logs only while evidence is still needed. Save machine-readable CLI results with --json-output build/<name>.json; do not use Windows PowerShell's default redirection because it rewrites native stdout as UTF-16. Before the final response, run log-hygiene --all --json when diagnostics are resolved, or bounded log-hygiene --json when a failure still needs retained evidence.
5. For any .gd edit, keep Godot reload warning clean while writing the code: do not generate Variant as GFType casts, direct Variant method calls, discarded return values, Script.new() on a Script-typed value, or constants/locals that shadow class_name values. Use explicit is checks, typed helper functions, _result variables, and _SCRIPT suffixes where needed. Run python tools\gf_maintenance.py check --check gdscript_lsp_diagnostics --json early when editor diagnostics help localize a warning; check --suite full, Ready/main's framework-lsp shard, and the release framework shard always run the same strict LSP gate for errors, warnings, diagnostic timeouts, connection failures, and transport failures. For focused scans, connect to the active editor with python tools\gdscript_lsp_diagnostics.py --file <path> --format json; use --connect-or-spawn when the same command must also work in CI. Do not use --spawn-lsp while a user editor is open, and never terminate unrelated Godot processes as LSP cleanup.

Decision Tree

• Runtime source changed under addons/gf/**: update focused tests/gf_core/**, docs/zh/changelog.md, relevant docs, generated API reference if public docs changed, and run the checks in checks.md.
• Public API changed: apply API_SURFACE.md, update @api, @category, @since, @param, @return, and @schema, regenerate API reference, and verify AI API summaries.
• Docs changed: keep handwritten docs in docs/zh/**; regenerate reference docs only with tools/generate_api_reference.py; run docs checks.
• Generator or generated-tree logic changed: keep generated output roots fail-closed, stage and validate every related tree before replacing any of them, and test rollback behavior. generate_ai_api.py may write outside ai_analysis/generated_api only with the explicit unsafe-output flag.
• Maintenance runner or CI topology changed: preserve Draft's independent quick gate and metadata-only policy path, require both GF repository policy and GF merge gate, keep Ready/main shards set-equivalent to full, run maintenance-self-test, and retain the Ready/main Windows process-supervision job as a merge-gate dependency. Local full runs default to three isolated workers, allow an explicit bounded --jobs 2 through --jobs 6, and use --jobs 1 only as a serial diagnostic fallback. They must batch workspace setup/cleanup, cover setup with the suite deadline, prove Godot's platform data/config/cache and user:// roots are private before starting shards, and fail closed when Windows clone/staging/private-temp paths cannot fit the projected short-path budget. GF_MAINTENANCE_VALIDATION_TEMP_ROOT only selects a validated direct local fixed-volume short-path parent for a random identity-pinned runner child, never an in-workspace, linked, UNC, device, mapped, or substituted path. Snapshot capture reads untracked regular files through stable handles in deadline-aware chunks, capped at 64 MiB per file and 256 MiB total. Every shard's owned process group or Windows Job Object must be empty before its report is accepted. Package smoke consumers must privately copy one hash- and workspace-fingerprint-validated artifact set built for the current suite invocation, and the parent must match each consumer report to that exact manifest digest and artifact count; never cache it across revisions or allow a consumer to mutate shared bytes.
• Release metadata changed: use $gf-release-flow.
• External reference project changed or examples suite is involved: use $gf-reference-boundary.
• Broad refactor, layer move, or multi-module behavior change: use $gf-change-audit.
• GDScript warning fixes: prefer real type narrowing and ownership changes over @warning_ignore; after edits run focused GUT for the touched scripts plus python tools\gf_maintenance.py check --check gdscript_warnings --json. Use python tools\gf_maintenance.py check --check gdscript_lsp_diagnostics --json or the focused tools/gdscript_lsp_diagnostics.py --file form for early diagnosis; the final full/release suite must also pass its unconditional LSP hard gate. If the change touches shadowed names, GF class casts, or dynamic script instantiation, also run tests/gf_core/maintenance/test_gdscript_parse_validation.gd.
• Project settings drift: if GUT, editor reload checks, or plugin tests appear to modify project.godot, run python tools\gf_maintenance.py project-settings-drift --json and fix the leaking test or plugin state instead of committing transient settings.
• Signature changes: search addons/gf and tests/gf_core for same-name func declarations, mocks, and reflective call sites before validating, because override signature drift is a Godot parse error.
• Editor-only plugin tests: do not instantiate editor-owned Godot plugin classes such as EditorDebuggerPlugin in plain headless GUT. Validate contributed records, script metadata, inheritance, and helper wiring unless the test runs through a real editor plugin lifecycle.
• Godot command wrappers: delete configured stale log files before launch, merge the newly written log into the result, fail when the log is missing or unreadable, and require a non-empty GUT pass summary even when the process exits with code 0. Let the maintenance CLI delete successful session logs; use --keep-logs or GF_MAINTENANCE_KEEP_LOGS=1 only for follow-up diagnostics, then explicitly clean them.

Testing Style

Prefer tests that verify observable GF behavior through public or documented interfaces. Do not expose private helpers just to test them. For bug fixes, establish a failing behavior signal first, then implement the smallest fix that makes that signal pass. See tdd-diagnose.md for the detailed loop.

Boundaries

• Keep dependency direction stable: addons/gf/kernel <- addons/gf/standard <- addons/gf/extensions.
• Do not write reference-project business rules into addons/gf.
• Do not turn the external reference project's directory layout into a framework requirement.
• When reviewing external reference projects, exported plugin sources, or design notes, classify each idea before adopting it: stable GF mechanism, editor/tooling pattern, documentation reminder, third-party service adapter, or project business rule. Implement only the stable GF mechanism or clearly reusable tooling pattern.
• Do not change vendored addons/gut/** unless the task explicitly requires GUT maintenance.
• Use apply_patch for manual edits; avoid reverting user or other-session changes.