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.

Live Deployment Gate

  1. Never expose changed live functionality merely because code deployed successfully. A consequential live change requires explicit prerequisite checks, postconditions, an end-to-end production smoke test, and direct verification of the affected user path before release is considered accepted.
  2. Every run owns its gate. Required files, routes, services, libraries, database objects, storage paths, and telemetry endpoints must be positively re-proven whenever the run changes them.
  3. Failed live verification stops release. A failed or unknown postcondition prohibits downstream testing and user release. Establish that failed condition first.
  4. Instrumentation must self-test. Observer source, attachment, route, endpoint persistence, and delivered browser JavaScript must all pass before a device test relies upon that observer.
  5. Use the permanent health surface. The standard production health page is /admin/skyhawk/system-status. Future consequential changes must add their critical health assertions there rather than inventing isolated readiness conventions.
  6. Automatic evidence promotion is mandatory. The run must atomically publish the evidence governing the next decision to /downloads/chatgpt-debug-latest.txt. Gene is not a manual evidence transport layer.

Verified Prerequisite Gate

  1. No functional test may be requested until its instrumentation prerequisites are explicitly proven. The immediately preceding evidence must demonstrate every component required to observe that test. Script completion, lint success, cache rebuild, intended configuration, or assumed state are not substitutes.
  2. Verification is a decision gate, not merely a script section. Before instructing Gene to perform the next action, the AI must inspect the actual verification result and independently determine that every prerequisite passed. If any prerequisite is missing, failed, ambiguous, or unobserved, stop and repair or inspect that prerequisite first.
  3. Telemetry must prove itself before measuring the product. Diagnostic instrumentation must pass an end-to-end smoke test proving that it is installed, attached, reachable, and capable of persisting evidence before any user/device test relies upon it.
  4. Missing telemetry is evidence about telemetry first. If expected diagnostic evidence is absent after a test, do not infer anything about the product under test until the instrumentation itself has been verified. Absence of an observer result cannot be used as evidence that the observed product transition failed.
  5. State prerequisites explicitly. For any instrumented test, define a finite PASS checklist before requesting the test. Every item must be positively proven. For the current upload observer this means: JS file FOUND; controller FOUND; library DEFINED; form ATTACHED; Drupal route RESOLVES; observer endpoint WRITES. Only an all-PASS result authorizes the Pixel functional test.
  6. Do not reason past a failed gate. A failed prerequisite has exactly one next path: establish that prerequisite. Do not troubleshoot downstream behavior, redesign the feature, or ask Gene to repeat the functional test until the gate passes.

Functional Evidence Gate

  1. Verification must match the user's failure. Syntax checks, route ownership, cache rebuilds, rendered HTML, database state, and server-side probes prove only those layers. They do not prove a browser workflow works. A user-facing feature is not functionally accepted until the exact failing user action succeeds on the affected device/browser.
  2. Honor the evidence boundary. Model the path as stages and mark each stage proven, disproven, or unproven. When evidence proves a stage works, close that branch and investigate the first unproven transition downstream. Do not reopen proven upstream stages without new contradictory evidence.
  3. A failed acceptance test narrows scope; it does not authorize redesign. After a functional test fails, stop modification, record the exact observed failure, inspect the first unproven transition, and make at most one targeted change against that transition. Do not use a failed acceptance test as permission for another subsystem rewrite, architecture change, or broad diagnostic sweep.
  4. Server success and product success are separate states. Use language such as installed, rendered, or server-side checks passed until the real user workflow passes. Reserve working, fixed, and accepted for direct functional proof.
  5. Update the subject reference at the evidence boundary. When a real test changes what is known, record the newly proven and newly failing stage on the subject page before the next material code change. Remove or supersede stale failure descriptions instead of allowing them to coexist.

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.

Debug Evidence Promotion

  1. Promote the relevant final evidence automatically. Every diagnostic or test block must finish by placing the evidence that determines the next state into /downloads/chatgpt-debug-latest.txt. Gene must not be required to run a second copy/promote command after the test.
  2. Keep immutable evidence separately. Installation or diagnostic runs continue to create their immutable Report-ID archive. A temporary live-event stream may use its own fixed file while the test is occurring, but when the test produces the evidence needed for the next decision, that evidence must be atomically promoted to chatgpt-debug-latest.txt.
  3. The fixed latest URL is the normal machine handoff. After Gene reports that a command or requested test is complete, the AI should retrieve https://skyhawk.org/downloads/chatgpt-debug-latest.txt itself, force freshness when possible, and validate the contents before asking Gene for output. The immutable archive is fallback evidence, not a routine human relay requirement.
  4. Live browser instrumentation must self-report. When a browser/device action is the only human-dependent step, the observer or diagnostic mechanism must capture and publish the resulting evidence automatically. Gene's role should end with performing the irreducible device action, such as choosing files on the Pixel.
  5. Do not overwrite useful evidence prematurely. A subsequent installation report, smoke test, cleanup action, or unrelated diagnostic must not replace chatgpt-debug-latest.txt before the AI has consumed the evidence from the just-completed functional test.

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.

KISS and Deterministic Work

KISS: Keep It Simple, Stupid.
Use the simplest maintainable method that satisfies the proven
requirement. Complexity requires justification. Do not add custom
code, instrumentation, validation layers, workflows, abstractions,
diagnostic gates, or other machinery merely because they are
possible.

  • Test outcomes, not implementation trivia.
    Determine whether the required user or business outcome works.
    Inspect internal transitions only when that outcome fails, and only
    deeply enough to identify and repair the failure.
  • Honor proven progress.
    Once functionality has been accepted, move forward unless new
    evidence contradicts it. Do not repeatedly reopen completed work.
  • Isolate failures.
    A failure authorizes investigation of that failed requirement, not
    a general reaudit or redesign of unrelated working functionality.
  • Read before changing.
    When live state is uncertain, inspect the actual current
    configuration, source, database state, Rules, and applicable
    reference before modifying anything.
  • Know and replace.
    Do not guess and append competing code or configuration when an
    existing owner can be identified and changed cleanly.
  • Let Drupal be Drupal.
    Prefer Drupal core, configuration, Views, and maintained contributed
    functionality. Add custom mechanisms only when the actual
    requirement cannot reasonably be satisfied otherwise.
  • Keep evidence concise.
    Routine work reports should state what was found, what changed,
    PASS/FAIL, meaningful evidence, and the next action. Do not build
    forensic reporting systems for already-proven behavior.

Consequential Change Backup Rule

Before a structural database change, migration, destructive
operation, or other consequential change for which database rollback
could reasonably matter:

  1. Create a specifically named database backup on the server.
  2. Generate its SHA-256 checksum.
  3. Download it to the specific hardware being used for the work.
  4. Verify the downloaded file SHA-256 against the server copy.
  5. Only after successful local verification may the temporary server
    backup be deleted.
  6. Record the backup identity, destination hardware, and successful
    verification in the work result.

Do not create database backups for read-only work, routine cache
rebuilds, harmless inspection, ordinary presentation changes, or
trivial code edits where database rollback has no meaningful value.
The purpose is reliable rollback, not accumulation of backup files.