Skyhawk Site Modernization Roadmap

RULES REVIEWED: YES
GERMANE REFERENCE REVIEWED: YES
UPDATE REQUIRED: YES/NO
BACKUP REQUIRED: YES/NO
NEXT: one concrete next state

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

15. 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.
16. 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.
17. 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.
18. 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.
19. 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

11. 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.
12. 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.
13. 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.
14. 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.
15. 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

• Drupal Environment Reference — environment, modules, directories, and established code patterns.
• Squadron Modernization Roadmap — North Star, modernization classes, census data, and current phase.
• VMA-131/214 Squadron Template — proven squadron architecture and regression standard.
• Upload Token System — token/contact/notification architecture and current state.
• SDO System Status — SDO mechanism and current state.
• Site Menu Reference — menu machine names and established structure.
• Termux SSH Notes — mobile SSH workflow and constraints.
• Windows Tooling Notes.
• Mac Tooling Notes.

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.

Personal-data ownership before removal

When personal information appears on an inappropriate page,
identify both the storage owner and the render owner before changing
anything. User/profile data rendered through article authorship is
not node content merely because it appears on a node page.

• If personal information is authoritative user/account data,
  preserve it and suppress the inappropriate presentation at the
  narrowest proven render owner.
• If personal information is a duplicate stored specifically in
  page content, remove the unnecessary duplicate.
• Do not delete authoritative member information merely to correct
  an inappropriate public presentation.
• Prefer Drupal-managed users, roles, configuration, mail services,
  and other maintained Drupal mechanisms when communication can occur
  without exposing private contact information.
• Verify privacy corrections against the actual rendered public
  page, not merely configuration, lint, or assumed ownership.

Semantic Visual Design

Skyhawk.org uses a small global semantic visual vocabulary rather
than inventing page-specific decorative CSS. HTML identifies what
content means; global CSS controls how that meaning appears.

• skyhawk-focus - current or primary purpose.
• skyhawk-feature - person, squadron, aircraft,
  creator, honoree, event, or other principal subject.
• skyhawk-context - supporting explanation.
• skyhawk-note - secondary information.
• skyhawk-reference - references,
  administrative information, and related material.

Optional identity modifiers are
skyhawk-navy,
skyhawk-marine,
skyhawk-joint, and
skyhawk-heritage.
Navy blue, Marine scarlet, gold, khaki, slate, and neutral colors
form the common palette. Bold colors are punctuation; muted colors
are prose. Color never carries meaning by itself.

Do not automatically color every paragraph or legacy page.
Apply semantic blocks where they improve hierarchy. Prefer the
existing global vocabulary over new CSS. Add a new semantic class
only when a proven requirement cannot reasonably use the existing
system. Keep mobile readability and accessibility intact. KISS.

Deterministic Execution Gate

Purpose: Convert the Rules, LOST-D, and germane references from material that is merely read into constraints that control the next action.

1. MISSION. Before substantive discussion or executable work, identify the single current objective from LOST-D and its hard scope boundary. Do not pursue adjacent work.
2. LOCATION. Establish the actual execution location before generating commands. Normal Skyhawk command-line work assumes the user is already at the interactive A2 prompt unless current evidence proves otherwise. Do not invent hosts, aliases, shells, paths, or execution environments.
3. KNOWN. Extract the settled facts relevant to the current action from the Rules and germane references. Proven and documented facts are authoritative until current evidence contradicts them. Do not rediscover, redesign, retest, or reopen completed decisions without new evidence or explicit user direction.
4. ACTION. Perform one meaningful state transition broad enough to accomplish the agreed step. Prefer the simplest proven method. Do not add instrumentation, abstraction, safeguards, audits, or side work that do not materially improve the required outcome.
5. STOP. Define success, failure, and NEXT before execution. A failed prerequisite prevents later success output. After the result, verify the state, reread LOST-D, update durable documentation when required, and continue from the last proven state.

Human-AI Friction Gate

• If the user must repeat an already documented instruction, treat the reminder as evidence that retrieval or execution discipline failed.
• If the same governing instruction must be repeated again during the same workstream, stop expanding the task. Correct the retrieval/enforcement failure first, then resume from the last proven state.
• User frustration is an operational signal when it results from repeated reminders, reopened completed work, unnecessary complexity, failed code blocks, or ignored scope.

Execution Contract

Before generating executable code, the AI must be able to state internally and unambiguously:

• MISSION: What single objective is being advanced?
• LOCATION: Where will this command actually run?
• KNOWN: Which settled facts control this action?
• ACTION: What one meaningful state transition will occur?
• STOP: What proves success or failure, and what is NEXT?

If any required field cannot be established from the current conversation, LOST-D, Rules, germane reference, or current proven output, do not invent it. Retrieve the missing fact first.

KISS applies to the collaboration itself: prefer fewer assumptions, fewer moving parts, fewer prompts, fewer rediscoveries, and fewer opportunities for improvisation.

Complete Code Window Rule

• Once executable code is authorized, provide one complete working code block for the agreed step whenever one block can reasonably perform it.
• If a supplied executable block needs correction before execution, replace the entire corrected block in a new code window.
• Never instruct Gene to splice, patch, merge, substitute, or manually combine executable fragments from separate code windows.
• A correction supersedes the prior unexecuted block in toto. The prior block is invalid and must not be partially reused.
• The only normal exception is a workflow that necessarily changes execution environments, such as the established A2-to-local backup-download and reconnect procedure.

AI Execution Core

Purpose: These eight invariants govern AI-generated Skyhawk maintenance. They replace overlapping AI-process rules. Do not create another AI-process rule when correcting the implementation of one of these invariants.

1. Facts Before Code

• The AI must verify every material fact required by executable work before depending upon it. Assumptions about paths, executables, shell behavior, ownership, dependencies, Drupal state, Git state, hosting capabilities, prior commands or human actions are forbidden.
• When uncertainty exists, inspect read-only first. A convenient local observation must not be generalized beyond what the evidence proves.
• The AI must think both backward and forward: verify current state and identify routine future actions that could make the solution stale, unsafe or incomplete.

2. AI Owns Deterministic Execution

• Because AI writes nearly all Skyhawk maintenance code, correct paths, working directories, execution context, command grammar, prerequisite checks, stop behavior and verification are primarily the AI's responsibility.
• Location-sensitive code must explicitly enter and verify its canonical working directory. Never rely on the human's current directory, inherited shell state or a previous command.
• Automation must explicitly use proven executables and environment facts rather than depend on interactive aliases or PATH behavior unless that behavior itself is the intended, proven mechanism.
• Shared-hosting work must remain within the authorized user/account/project boundary unless the human explicitly authorizes a broader change that the host permits.

3. Evidence Automatically Controls the Next Step

• When executable work creates an authoritative or immutable report, the AI must retrieve and read it automatically before diagnosis or further executable work.
• The human must never have to tell the AI to read evidence generated by the AI's own workflow.
• Failure diagnosis must come from actual evidence, not intended behavior, memory, assumptions or footer wording.
• When only one safe evidence-supported AI-owned next action remains, the AI must provide that executable action automatically in the same response. The human is not required to ask "next."

4. A Response Cannot Promise Its Own Missing Work

• If NEXT identifies an unperformed AI-owned executable action, the response is incomplete and must continue until that action is supplied.
• A response may stop only for genuine human judgment/action, unavailable required evidence, a safety/authorization boundary, or completed work.
• Writing "NEXT: AI will provide code" without providing the code is a failure.

5. Executable Blocks Must Fail Closed

• Every executable block must begin with the literal first line # RULES + GERMANE REFERENCE READ.
• AI-generated blocks must use control flow that is valid for the actual shell/context and mechanically prevents later mutating steps after a failed prerequisite.
• Do not use top-level shell constructs that cannot stop the running context. Test shell syntax before mutation when practical.
• PASS, FAIL, UPDATE REQUIRED, BACKUP REQUIRED and NEXT must reflect gates that actually completed. Intended results never override execution evidence.
• After a failure, repair the proven failure only. Do not reopen completed work or redesign unrelated components.

6. One Complete Code Window

• Once executable work is authorized, provide one complete working code block whenever one block can reasonably perform the agreed step.
• If an unexecuted block needs correction, replace it completely in a new code window. Never require the human to splice, patch, merge or combine executable fragments.
• The prior unexecuted block is superseded in toto.
• The established local-download/reconnect workflow is the normal exception when execution necessarily crosses environments.

7. Durable State, Minimal Rules

• When a human correction exposes a broadly reusable requirement, the AI must first verify whether an existing Rule already covers it.
• If covered, fix the implementation rather than adding another Rule. If genuinely new, update the smallest appropriate Rule or germane reference in the same successful transaction and independently reread it.
• Environment-specific facts belong in germane references; universal behavior belongs in Rules.
• Critical workflow state should live in durable references, reports or deterministic wrappers rather than depend upon conversational memory.
• KISS governs both code and rules: use the simplest maintainable mechanism that satisfies the proven requirement.

8. Human / AI Boundary and Completion

• The AI owns evidence retrieval, deterministic reasoning, command construction, environment verification, automatic continuation and technical bookkeeping.
• The human is required only for genuine choices, authorization, credentials, physical-device action, visual/functional judgment or policy decisions.
• Do not transfer an AI obligation to the human by calling the human an operator.
• Before declaring a workstream complete, verify not only today's result but the routine future maintenance path, backup/recovery relationship, documentation state and deterministic mechanism that keeps the solution current.
• Closed and proven work stays closed unless new evidence invalidates it.

Composer / Git Completion Gate

• Normal Skyhawk dependency maintenance uses /home/darwus/drupalbeta/bin/skyhawk-composer.
• skyhawk-composer update is the normal full-update command. Package names or Composer options may follow for targeted updates.
• require and remove use the same pending maintenance lifecycle. install reconstructs from composer.lock and must not change tracked reconstruction architecture.
• Before mutation, Git must be clean and local HEAD must match origin/main.
• After mutation, Drupal database updates and cache rebuild run before the transaction becomes pending.
• finish is the explicit human functional-acceptance and publication act.
• finish requires zero active-vs-sync Drupal configuration differences.
• The staged set is safety-checked and Composer-validated before commit.
• Maintenance is complete only after push and exact local/remote commit parity.
• Composer hooks must never automatically commit or push.