Skip to content

AI_RULES.MD

Latest commit

 

History

History
87 lines (76 loc) · 3.21 KB

AI_RULES.MD

File metadata and controls

87 lines (76 loc) · 3.21 KB

AI RULES

1. SCOPE

  • WORK ONLY WITH LOCAL FILES.
  • DO NOT USE CODEX APIS.
  • DO NOT EXTRACT TOKENS, CREDENTIALS, OR SECRETS.
  • DO NOT INTERCEPT NETWORK TRAFFIC.
  • DO NOT MODIFY CODEX BINARIES OR RUNTIME.
  • DO NOT CHECK CLOUD CLIENT PROCESS STATE.
  • DO NOT CHECK FREE SPACE IN CLOUD/NETWORK STORAGE.

2. MANDATORY SYNC MODEL

  • COLD SYNC ONLY.
  • SYNC IS ALLOWED ONLY WHEN CODEX IS FULLY STOPPED.
  • ONE ACTIVE MACHINE AT A TIME.
  • HANDOFF PROTOCOL IS MANDATORY:
    1. CLOSE CODEX ON SOURCE MACHINE.
    2. WAIT FOR CLOUD PROPAGATION.
    3. RUN SYNC ON TARGET MACHINE.
    4. START CODEX ON TARGET MACHINE ONLY AFTER SYNC IS COMPLETE.

3. SAFETY GUARANTEES

  • ALWAYS CREATE A BACKUP BEFORE ANY OVERWRITE.
  • IF DATA STATE IS UNCERTAIN, EXIT WITHOUT WRITING.
  • EXCLUDE TEMPORARY, LOCK, AND CACHE FILES FROM SYNC.
  • NEVER DELETE SOURCE DATA WITHOUT A CONFIRMED BACKUP.

4. TECHNICAL REQUIREMENTS

  • MINIMUM PYTHON VERSION: 3.11.
  • SUPPORTED OS:
    • WINDOWS 10+.
    • MACOS ON APPLE SILICON (MINIMUM OS VERSION REQUIRES SEPARATE VALIDATION; WORKING TARGET: 14+).
    • LINUX: OUT OF CURRENT MVP SCOPE (PENDING OFFICIAL CODEX LINUX RELEASE).

4.1 CI TARGETS

  • CI RUNS ON WINDOWS-LATEST AND MACOS-LATEST.
  • LINUX CI IS INTENTIONALLY DISABLED IN MVP.

5. TOOL INTERFACE REQUIREMENTS

  • CLI-FIRST.
  • CONFIGURATION FILE SUPPORT.
  • INIT-CONFIG COMMAND MUST GENERATE config.toml FROM TEMPLATE BUNDLED IN THE DISTRIBUTED PACKAGE.
  • DETAILED LOGGING.
  • --DRY-RUN MODE.
  • DOCTOR/PREFLIGHT MODE THAT CHECKS RUNTIME READINESS BEFORE SYNC.
  • SCHEDULED MODE:
    • WINDOWS TASK SCHEDULER.
    • MACOS LAUNCHAGENT (LAUNCHD).
  • FOR WINDOWS, .EXE PACKAGING IS ALLOWED.

6. IMPLEMENTATION RULES

  • ANY SYNC OPERATION MUST BE IDEMPOTENT WITHIN A SINGLE RUN.
  • CHANGE COMPARISON: TIMESTAMP FIRST, HASH WHEN AMBIGUOUS.
  • LOG DANGEROUS ACTIONS SEPARATELY (CREATE BACKUP, OVERWRITE, SKIP).
  • CONFLICT WHEN BOTH SIDES CHANGED:
    • DO NOT PERFORM SYNC WRITES.
    • RETURN CONFLICT CODE.
    • PRINT CONFLICT FILE LIST.
    • REQUIRE MANUAL RESOLUTION AND RERUN.
  • NO SEPARATE FILE-TIME NORMALIZATION IN MVP (NO UTC CONVERSION AND NO CLOCK DRIFT COMPENSATION).

7. CLI EXIT CODES

  • 0 SUCCESS (COMPLETED OR NO CHANGES).
  • 1 RUNTIME ERROR.
  • 2 CONFLICT DETECTED (MANUAL HANDLING REQUIRED).
  • 3 CODEX RUNNING (COLD-SYNC PRECONDITION VIOLATED).
  • 4 CONFIG/ARGS ERROR (INVALID CONFIG OR CLI PARAMETERS).
  • 5 SAFE ABORT (FAIL-SAFE STOP).

DOCTOR/PREFLIGHT MUST:

  • REPORT CHECK RESULTS (PASS|WARN|FAIL) WITH CLEAR DETAILS.
  • RETURN 0 WHEN ONLY PASS/WARN ARE PRESENT.
  • RETURN 5 WHEN AT LEAST ONE FAIL IS PRESENT.

8. MINIMUM MVP TEST SET

  • UNIT TESTS FOR EXCLUSION FILTERING.
  • UNIT TESTS FOR SOURCE-SIDE SELECTION IN COMPARISON LOGIC.
  • INTEGRATION TEST FOR DRY-RUN WITHOUT DISK WRITES.
  • INTEGRATION TEST FOR BACKUP+OVERWRITE ON TEST DIRECTORIES.
  • INTEGRATION CONFLICT TEST: NO WRITES, CONFLICT LIST OUTPUT, EXIT CODE 2.

9. DEFINITION OF DONE (MVP)

  • TOOL BLOCKS SYNC CORRECTLY WHEN CODEX IS RUNNING.
  • CREATES BACKUP BEFORE OVERWRITE IN EVERY OVERWRITE SCENARIO.
  • EXECUTES DRY-RUN SAFELY WITH A READABLE REPORT.
  • WORKS ON WINDOWS 10+ AND ON MACOS APPLE SILICON IN VALIDATED TEST CONFIGURATION.
  • ON CONFLICT, PERFORMS NO WRITES AND EXITS WITH CODE 2.