Skip to main content

Skyhawk Site Modernization Roadmap

Skyhawk Site Modernization Roadmap

READ THIS FIRST: AI / Maintainer Operating Contract

Mission: Deliver verified, maintainable changes to this specific Skyhawk Drupal site with the fewest practical iterations. Plausible code is not success. Verified working behavior is success.

Read this page in full before coding, then read every reference page relevant to the task. Do not reconstruct facts from memory, guess at the current state, or rediscover settled decisions.

Required external behavior: known state → applicable references → agreed task → inspection → implementation → lint/validation → execution → evidence capture → verification → reference update → next state. The model may be probabilistic internally; the workflow must be deterministic.

1. Mandatory Workflow

  1. Reference authority comes first. Before each material Skyhawk coding step, read this page and every applicable subject-specific reference page in the current task context. Do not substitute conversation history, model memory, prior-chat recollection, or general Drupal knowledge for an available current reference.
  2. Authority order is explicit. Tier 1: binding operating rules on this page. Tier 2: current environment, architecture, and subject-specific /blade/ references. Tier 3: historical lessons and failure notes. Conversation history and model memory are fallback context only when the durable references are silent. If memory conflicts with a current reference, the reference wins.
  3. No code before reference resolution. Before producing executable Skyhawk code, identify which reference pages govern the task and read them. If the applicable references have not been read, stop before code.
  4. State before action. Inspect the relevant file, configuration, route, View, module, theme, template, field, log, or rendered output before changing anything. Never code against an imagined state.
  5. Discuss narrowly and agree first. Do not expand scope, create side projects, or infer new goals. Ask before writing code unless Gene has explicitly authorized coding.
  6. Search before creating. Search the actual codebase and Drupal configuration, including all custom modules and relevant theme/configuration locations, before adding a mechanism.
  7. One complete block per agreed step. Include pre-flight checks, backup/rollback when consequential, modification, lint/validation, execution, evidence capture, and targeted verification. Then stop for actual results.
  8. One change set, one verification target. Do not mix unrelated changes. Each change must have a defined expected result and a test that proves or disproves it.
  9. Compliance gate before code. Before presenting executable code, confirm internally that the applicable references were read; current state was inspected; established Drupal/Skyhawk mechanisms were preferred; core/contrib remain untouched; the correct custom location is used; clean replacement is preferred over cumulative patching; lint/validation is included; rollback is appropriate; verification proves the intended result; the SSH/Termux session is preserved; and durable documentation will be updated if the agreed state changes. If any required item is unresolved, do not issue the code block yet.
  10. Drift-stop rule. If, while constructing or executing a code block, the AI discovers that the proposed action has wandered outside the agreed task, conflicts with a current reference, depends on an unverified assumption, or would reopen a closed branch without new evidence, stop that action before the unsafe or irrelevant step. Preserve the shell session, state exactly what triggered the stop, inspect the specific conflict, and redesign only that affected step before proceeding.
  11. Creativity before commitment; discipline after commitment. Use broad reasoning while diagnosing and designing. Once Gene and the AI agree on an implementation path, novelty is not a virtue. Do not substitute a different technique merely because another plausible approach occurs to the model. Change course only when new evidence or a changed requirement justifies it.
  12. Close branches. Every failed test must narrow the search space. Record what the evidence eliminated. Do not repeat the same failed test or revive a disproved theory unless new evidence reopens it.
  13. Proceed linearly. Do not redo, redesign, move, replace, or reopen completed verified work merely because another approach exists.
  14. Visible compliance checkpoints are encouraged. At useful, non-repetitive points during longer work, the AI may give Gene a brief concrete statement identifying a rule it is actively following, such as the reference consulted, the branch closed, the established mechanism being reused, or the reason a step was stopped. These statements are evidence of process, not ceremony, and must never substitute for actual verification.

2. Drupal Architecture: Let Drupal Be Drupal

Drupal is the platform. Conform to Drupal before customizing Drupal. Access to enormous amounts of source code does not make custom code the preferred answer. On skyhawk.org, sophistication includes knowing when not to write code.

  1. Preference order: Drupal core behavior/configuration first; established contributed modules/themes second; Views wherever Views can reasonably solve a listing, query, grid, filter, or administrative-report problem; existing Skyhawk custom mechanisms next; new custom code only when the preceding choices cannot cleanly meet the requirement.
  2. Views rule: Do not hand-code entity queries, listing pages, grids, filters, or content reports when Views can reasonably provide them.
  3. Core and contrib remain pristine. Never implement Skyhawk-specific behavior by editing /core, /modules/contrib, or /themes/contrib. Drupal updates must not erase or collide with site-specific work.
  4. Use established custom locations. Genuinely site-specific integration belongs in the existing skyhawk_site_fixes custom module unless an established mechanism already owns the behavior. Do not create another custom module merely to isolate a small fix.
  5. One global stylesheet. Global site behavior belongs in skyhawk_site_fixes/css/skyhawk-global.css. Do not create another global stylesheet. Do not turn page-specific exceptions into global rules.
  6. Preserve established architecture. Do not recreate retired CSS, retired themes, superseded implementations, or duplicate mechanisms.
  7. Legacy content is preserved unless there is a practical reason and explicit agreement to modernize it.

3. Clean Editing: Know and Replace, Never Guess and Append

  1. Search before edit. Before changing a selector, hook, route, service, template, View, formatter, configuration key, or related mechanism, locate the relevant existing implementation and references.
  2. No cumulative patching. Inspect and understand the current logical block, then replace that complete logical block with the final version whenever practical. Do not stack corrective fragments on top of earlier corrective fragments.
  3. CSS sediment is a failure state. Do not append one rule to reverse another, then a third to reverse the reversal. Locate the owning block and replace it cleanly.
  4. Do not blindly append to PHP, JS, Twig, YAML, CSS, or configuration. Know the current contents and ownership first.

4. Code Quality Gate

Code is not ready merely because an AI generated it. Before presenting executable code, validate syntax, paths, quoting, environment assumptions, destructive scope, rollback, and the verification method.

  • PHP: php -l where applicable.
  • Bash: bash -n where applicable.
  • JSON: parse with available tooling such as jq or python -m json.tool.
  • YAML and PowerShell: perform practical parser/syntax validation when tooling is available.
  • Drupal: use the appropriate Drush/configuration/cache action plus a targeted functional check.
  • CSS/JS/Twig: use available static/syntax checks, then verify the actual rendered or loaded result.

Do not demand imaginary tooling. Use the strongest practical validation available.

5. Evidence and Verification

  1. No success language without proof. Do not claim fixed, working, loaded, deleted, redirected, clean, installed, or confirmed unless the evidence directly proves that claim.
  2. If execution occurred but verification has not, say changed, attempted, or not yet verified.
  3. Separate diagnosis from modification. When the cause is uncertain, begin with a read-only audit.
  4. Back up before consequential changes and verify afterward. Read-only diagnostics do not need ceremonial backups.
  5. Confirmed live docroot: /home/darwus/drupalbeta/web. Do not use /home/darwus/public_html/drupalbeta or variants.
  6. Confirmed site error log: /home/darwus/drupalbeta/web/error_log. Before trusting any log, prove it belongs to the site/domain being worked on.
  7. To prove a JavaScript library is loading, inspect actual rendered script src output or the aggregated bundle it references. Grepping rendered HTML for a Drupal library machine name proves nothing.
  8. Any route showing per-request or token-gated state must trigger Drupal's page_cache_kill_switch in the form/controller so stale page cache cannot silently serve old state.

6. Standard AI Debug Channel

The debug channel exists to eliminate routine copy/paste between Termux, Windows, Mac, mobile devices, and the AI.

Authoritative current-report URL: https://skyhawk.org/downloads/chatgpt-debug-latest.txt.

The authoritative latest file contains the complete current report, not merely a pointer. Each diagnostic run also creates an immutable archive report named with a unique Report-ID, such as /downloads/chatgpt-debug-20260824T164135Z-698130.txt. The immutable archive is retained as historical execution evidence, but the AI normally reads the fixed latest URL directly.

Publish atomically. Build the complete report in a temporary file. After the report is finished, move it into the immutable archive filename, then copy that completed archive to a temporary latest filename and atomically move the temporary latest file into /downloads/chatgpt-debug-latest.txt. Never stream a still-changing report directly into either public filename.

The complete report must begin with:

SKYHAWK AI DEBUG REPORT
Task: <plain-language task>
Generated: <timestamp with timezone>
Report-ID: <unique timestamp/nonce>
Archive-URL: https://skyhawk.org/downloads/chatgpt-debug-<Report-ID>.txt
Host: <hostname>
Working directory: <pwd>
Drupal root: /home/darwus/drupalbeta/web

===== PRE-FLIGHT =====
...
===== ACTION =====
...
===== LINT / VALIDATION =====
...
===== VERIFICATION =====
...
===== ERRORS =====
...
===== END =====

Freshness is mandatory. After Gene confirms that a report was updated, the AI reads chatgpt-debug-latest.txt and validates Task:, Generated:, Report-ID:, host, working directory, and Drupal root against the current work before relying on it.

If the first retrieval is stale, that is a retrieval-layer failure, not evidence that the A2 command failed. Retry the known latest URL with a cache-busting query value when the retrieval tool permits it. Do not report server failure merely because an intermediary served an older object.

Do not ask Gene to paste terminal output merely because retrieval is stale. Manual copy/paste is a fallback only when the fixed latest-report channel cannot be read after reasonable fresh-retrieval attempts.

Never place secrets in public debug reports. Do not include passwords, private keys, session cookies, API keys, active upload tokens, personal data, database credentials, or other sensitive material. Redact before publication.

Capture enough evidence to determine the next state, not thousands of irrelevant lines. Use the older A2-to-Windows report-transfer workflow only when Gene actually needs a local file.

7. Living Reference System

  1. Reference continuously, update immediately. The /blade/ reference pages are the persistent operating state of skyhawk.org, not historical notes.
  2. Durable reference outranks memory. Conversation history and model memory are working aids and last-resort context. When a current durable reference contains the applicable fact, path, architecture decision, convention, completed decision, or known state, use it instead of remembered conversation. Memory must not silently override documented site state.
  3. Code and documentation are one transaction. When Gene and the AI agree during a session to a material architecture decision, path, procedure, convention, completed feature, or changed system state, update the appropriate reference page during that same work session as part of the change.
  4. Do not postpone documentation until the end. If direction changes during coding, update the reference page as soon as the new direction is settled so obsolete instructions do not poison the next step or next session.
  5. One source of truth per subject. Keep detailed facts on the appropriate subject page and link to them rather than maintaining conflicting copies.
  6. Read the subject page again when the task crosses a boundary. A change from Drupal configuration to Termux workflow, upload-token behavior, menu structure, Mac backup work, squadron modernization, or another documented subsystem requires consulting that subsystem's reference before continuing.
  7. Document supersession explicitly. When a durable rule changes, replace the obsolete rule on its authoritative page and state what the new rule supersedes when ambiguity would otherwise remain. Do not leave mutually contradictory instructions for the next machine to arbitrate.

8. Existing Binding Site Rules

  1. Respect limited-answer requests. If Gene requests Yes/No only, answer Yes or No.
  2. Use the word "hero" only for someone who did something heroic.
  3. No Drupal messenger()/status popups for Skyhawk custom forms. Form/action results render inline using the established PageMessageTrait pattern in skyhawk_site_fixes/src/Traits. The known skyhawk_gallery/PhotoContributionForm.php exception is not a pattern to copy and is not authorization for a side project.
  4. Downloaded scripts are ZIP files rather than loose plain-text script downloads.
  5. For squadron work, follow the current squadron modernization prototype and lessons rather than one-node patches.

9. Cleanup, Retention, and Backup Discipline

  1. Cleanup protects surviving work; tidiness is not the objective. Never delete material merely because it is old, unfamiliar, inconvenient, or apparently unused. Unknown material must be investigated before deletion.
  2. Clean at verified logical stopping points. Temporary scripts, probes, test uploads, verification files, abandoned experiments, superseded implementations, duplicate artifacts, and other known disposable material should not accumulate indefinitely. Remove them after their purpose is complete and the surviving implementation has been verified.
  3. WHATIF/inventory before meaningful bulk deletion. First identify exactly what would be removed, what would remain, and why. Perform the destructive step only after the inventory establishes that the candidates are safe to remove.
  4. Drupal content is not disposable housekeeping. Preserve legitimate nodes and content. Test nodes, abandoned prototypes, duplicates, or superseded temporary nodes may be removed only after identifying and verifying the surviving replacement. Do not create new nodes when editing the established canonical node is the correct operation.
  5. Drupal revisions are distinct from duplicate nodes. Revision growth may be audited periodically, but revision history must not be blindly purged merely to reduce database size.
  6. Diagnostic-report retention is 30 days. Immutable chatgpt-debug-*.txt and related AI diagnostic files may be pruned after 30 days. The active chatgpt-debug-latest.txt mechanism remains. Diagnostic cleanup must not be confused with deletion of site content or historical source material.
  7. A2 is not the long-term database-backup repository. Database dumps created on A2 during maintenance are temporary working/transfer artifacts unless explicitly designated otherwise. Do not accumulate redundant database archives on the same hosting account as the live database.
  8. The established Mac database-backup workflow remains authoritative. The Mac already downloads the Drupal database nightly. When work is being performed from the Mac and a newer database copy is required, replace/update the latest local backup using the already-established Mac replacement and retention pattern. Do not redesign that working retention scheme as part of unrelated Drupal work.
  9. Protect before removing. A consequential change may require a temporary A2 backup for immediate rollback. Once the change is verified and the data is safely represented by the established backup process, remove unnecessary A2 temporary copies rather than allowing them to become accidental permanent archives.
  10. Deletion requires knowledge. "I do not recognize this" means inspect it. "This is positively identified as temporary, duplicate, abandoned, superseded, or safely backed up" means it may become a cleanup candidate.

10. Reference Pages

11. Continuity Test

A future AI agent or maintainer should be able to read this page, resolve the applicable references, establish the current state without rediscovering settled facts, make the smallest correct update-safe change, validate it, capture evidence, verify it, update the durable reference state, clean only proven disposable artifacts, and continue without reopening completed work.

Operating shorthand: reference authority → inspect actual state → agree → compliance gate → implement → lint → execute → capture → verify → update reference → conservative cleanup → next task.

If the workflow begins to drift, stop the affected action, preserve the session and surviving state, identify the exact rule or evidence conflict, correct that specific problem, and only then resume. The goal is deterministic external behavior from a probabilistic tool: creative in diagnosis, disciplined in execution, and boring enough to keep airplanes flying.