codeninja 3.2.0 → 4.0.1

package/ide/claude-code/.claude/commands/codeninja-sync.md

@@ -0,0 +1,964 @@
+This command runs when user types /codeninja:sync
+
+---
+type: workflow
+name: sync
+description: >
+  Scans the entire repository and builds or rebuilds context.json from
+  what actually exists on disk. Works on both agent-initialized projects
+  and pre-existing legacy projects with completely different structures.
+  Always writes context.json — creates it if missing. Safe to run at any time.
+---
+
+# Workflow: @sync
+
+## Goal
+Make context.json an accurate, complete reflection of the current
+repository — whether the project was initialized by this agent or
+existed long before this system was introduced.
+
+ALWAYS write context.json at the end of every sync run.
+If context.json does not exist → create it from scratch using the
+empty schema from write-context.task.md and populate it from scan results.
+Never skip the write step even if nothing changed.
+
+---
+
+## Two Operating Modes
+
+Sync detects which mode to use automatically. Do not ask the user.
+
+### Mode A — Agent-Initialized Project
+Indicators: `.codeninja/context/context.json` exists AND has
+`context_version > 0` AND `context.services` has at least one entry.
+
+In this mode: trust context.json as a baseline, scan for drift and
+gaps, merge new findings into existing context without overwriting
+known-good values.
+
+### Mode B — Legacy / No-Context Project
+Indicators: context.json is missing OR `context_version == 0` OR
+`context.services` is empty.
+
+In this mode: treat every discovery as new. Build context.json
+entirely from what is found on disk. Make no assumptions about
+structure — the project may follow completely different conventions
+from the agent's own generated patterns. Be inventive and read deeply.
+
+---
+
+## Core Rules (apply to both modes)
+
+- ALWAYS write context.json at the end — no exceptions
+- NEVER delete existing context entries — only add or update
+- NEVER assume a file will be in a specific location — scan first
+- NEVER assume a project follows agent conventions — verify everything
+- Preserve all existing `change_log` entries — append only
+- Report all findings in the sync report at the end
+- If a value conflicts with what is already in context → list it and
+  ask user to confirm which to keep — one conflict at a time — before
+  writing context
+
+---
+
+## Step-by-Step Execution
+
+---
+
+### Phase 0 — Determine Mode and Prepare
+
+0a. Check if `.codeninja/context/` directory exists.
+    If not → create it now. Do not fail on missing directory.
+
+0b. Attempt to read context.json via MCP tool `context_read`.
+    If it returns the empty schema (context_version == 0) or fails →
+    set mode = B and prepare a fresh empty schema in memory.
+    If it returns data with context_version > 0 and populated services →
+    set mode = A and load all existing values as the working baseline.
+
+0c. Run task: `detect-repository-state`
+    This scans root for service folders, database folder, and
+    React apps regardless of mode.
+
+0d. Determine sync report counters — initialize all to zero:
+    services_synced, routes_discovered, routes_new,
+    db_tables_synced, db_tables_new, gaps_filled, unchanged,
+    legacy_inferences
+
+---
+
+### Phase 1 — Repository Structure Discovery
+
+This phase maps every part of the repository before any context
+is written. Read first, write later.
+
+#### 1a — Find all service-like directories
+
+Scan every directory at repository root. A directory is a candidate
+service if it contains ANY of these signals:
+  - `package.json` (Node/React project)
+  - `app.js` or `index.js` (Node entry points)
+  - `src/` directory (could be React or modern Node)
+  - `composer.json` (PHP project — record but do not deep-scan)
+  - `requirements.txt` or `pyproject.toml` (Python — record, note unsupported)
+  - `Gemfile` (Ruby — record, note unsupported)
+  - `pom.xml` or `build.gradle` (Java — record, note unsupported)
+
+For each candidate directory: record name and what signal triggered it.
+
+Skip: `.codeninja/`, `node_modules/`, `.git/`, `dist/`, `build/`,
+`.next/`, `.nuxt/`, `coverage/`, `.cache/`
+
+#### 1b — Classify each candidate
+
+For each candidate directory, determine its tech type:
+
+**NodeJS detection (check in order):**
+  1. `package.json` exists → read it
+  2. Check `dependencies` for: express, fastify, koa, hapi, nestjs
+  3. Check for `app.js`, `server.js`, `index.js` at root of directory
+  4. Check for `src/app.js` or `src/index.js`
+  → If any match: classify as `nodejs`
+
+**ReactJS detection (check in order):**
+  1. `package.json` exists → read it
+  2. Check `dependencies` or `devDependencies` for: react, react-dom
+  3. Check for `src/App.jsx`, `src/App.js`, `src/App.tsx`
+  4. Check for `src/index.jsx`, `src/index.js`, `src/main.jsx`
+  5. Check for `public/index.html`
+  → If any match: classify as `reactjs`
+  Note: If both express AND react are in the same package.json →
+  classify as `nodejs` and note the React dependency as unusual.
+
+**Unknown:** Record the folder, note what was found, do not classify.
+
+#### 1c — Find the database directory
+
+Search for database files using ALL of the following patterns —
+not just the agent's convention of `database/` at root:
+
+  - `database/` at repository root (agent convention)
+  - `db/` at repository root
+  - `<service_name>/database/` inside any service folder
+    (misplaced — flag it)
+  - `<service_name>/db/` inside any service folder
+    (misplaced — flag it)
+  - `migrations/` at repository root or inside any service
+  - `schema/` at repository root or inside any service
+  - `sql/` at repository root or inside any service
+  - Any `.sql` files anywhere in the repo
+  - For MongoDB: `models/` directories containing Mongoose schema
+    files (files with `mongoose.Schema` or `new Schema(`)
+  - For MongoDB: any `*.model.js` files with Schema definitions
+
+Record all database locations found. The agent's expected location
+is `database/<db_type>/migrations/` — anything else is noted in
+the report as non-standard but still scanned.
+
+#### 1d — Find shared infrastructure
+
+Scan for files that exist outside service folders and may be shared:
+  - `docker-compose.yml` or `docker-compose.yaml`
+  - `Dockerfile` at root
+  - `.env` at root (shared environment)
+  - `nginx.conf` or `nginx/`
+  - `kubernetes/` or `k8s/`
+  - `scripts/` at root
+  - `docs/` or `documentation/`
+  - `README.md` at root
+
+Record all found. These do not create service entries but inform
+the project_info summary.
+
+---
+
+### Phase 2 — Deep Scan Each NodeJS Service
+
+For each directory classified as `nodejs` in Phase 1:
+
+#### 2a — Identity and Package
+
+Read `package.json` → extract:
+  - `name` → candidate for service_name
+  - `version`
+  - `description`
+  - `author`
+  - `main` → note actual entry point
+  - `scripts` → note start script key and value
+  - All `dependencies` → full list
+  - All `devDependencies` → full list
+
+If `package.json` not found → use directory name as service_name.
+
+#### 2b — Find the Entry Point
+
+The entry point is NOT always `app.js`. Check in this order:
+  1. `package.json` `main` field
+  2. `package.json` `scripts.start` → extract filename from `node <file>`
+  3. `app.js` at service root
+  4. `server.js` at service root
+  5. `index.js` at service root
+  6. `src/app.js`
+  7. `src/index.js`
+
+Read the entry point file → extract:
+  - Port: scan for `process.env.PORT`, `.listen(`, `PORT =`
+  - Middleware registrations (look for `app.use(`)
+  - Route registrations (look for `app.use('/', `, `require(`)
+  - Any `dotenv` or `dotenv.config()` call
+
+#### 2c — Find Environment Config
+
+Search for `.env` file in this order:
+  1. `<service>/.env`
+  2. `<service>/.env.local`
+  3. `<service>/.env.development`
+  4. `.env` at repository root
+
+If found → read all key=value pairs. Extract:
+  - PORT → service port
+  - PROJECT_NAME or APP_NAME or SERVICE_NAME → service name hint
+  - API_KEY or APIKEY → api_key
+  - KEY, ENCRYPTION_KEY, SECRET_KEY, APP_KEY → encryption_key
+  - IV, ENCRYPTION_IV, SECRET_IV → encryption_iv
+  - ENCRYPTED_TRANSPORT → encrypted_transport (parse as boolean)
+  - SUPPORTED_LANGUAGES, LANGUAGES → parse as array
+  - DB_HOST, DATABASE_HOST, PGHOST, MYSQL_HOST → db host
+  - DB_PORT, DATABASE_PORT, PGPORT, MYSQL_PORT → db port
+  - DB_NAME, DATABASE_NAME, PGDATABASE, MYSQL_DATABASE → db name
+  - DB_USER, DATABASE_USER, PGUSER, MYSQL_USER → db user
+  - DB_PASSWORD, DATABASE_PASSWORD, PGPASSWORD → note exists (never store value)
+  - REDIS_HOST, REDIS_URL → redis host
+  - REDIS_PORT → redis port
+
+If `.env` not found → also check `.env.example` for key names
+(even if values are blank, it documents what the service expects).
+
+#### 2d — Find Route Definitions
+
+Routes may live in many structures. Scan all of these:
+
+**Agent-convention structure:**
+  - `modules/v1/<ModuleName>/route.js`
+  - `modules/v2/<ModuleName>/route.js`
+
+**Common legacy structures:**
+  - `routes/<n>.js` or `routes/<n>.route.js`
+  - `routes/v1/<n>.js`
+  - `src/routes/<n>.js`
+  - `api/routes/<n>.js`
+  - `controllers/<n>.js` (routes may be defined here in some patterns)
+  - `src/controllers/<n>.js`
+  - Any file named `*.router.js`, `*.routes.js`, `route.js`, `router.js`
+
+For each route file found → extract:
+  - HTTP method: `router.get`, `router.post`, `router.put`,
+    `router.patch`, `router.delete`, `app.get`, `app.post`, etc.
+  - Route path: the string argument (e.g. `/login`, `/users/:id`)
+  - Handler name or comment if present
+  - Version prefix if detectable from folder or router mount path
+
+Also read the entry point for `app.use('/v1', ...)` style mounts to
+determine base prefix for routes.
+
+#### 2e — Determine Encryption Library and Client Type
+
+Scan for encryption setup. Do NOT assume a specific file location:
+  - Search all `.js` files for: `require('crypto-js')`,
+    `require("crypto-js")`, `import CryptoJS`
+  - Search for: `require('cryptlib')`, `require("cryptlib")`,
+    `import cryptlib`
+  - Search for: `require('crypto')` (Node built-in AES — different approach)
+  - Search for: `CryptoJS.AES`, `cryptlib.encrypt`, `crypto.createCipheriv`
+
+Also check for the encryption/decryption pattern inline in other files:
+  - `headerValidator.js`, `common.js`, `app.js`, any middleware file
+    may contain the encrypt/decrypt logic directly in older projects
+
+Map findings to client_type:
+  - crypto-js found → `client_type = "reactjs"`
+  - cryptlib found → `client_type = "app"`
+  - Node crypto with AES → `client_type = "app"` (note: custom implementation)
+  - Nothing found → `client_type = null` (record as unknown)
+
+Also look for encrypted transport pattern:
+  - Any middleware that calls `decrypt(req.body)` or similar before
+    passing to handlers → `encrypted_transport = true`
+  - Check ENCRYPTED_TRANSPORT in .env as backup
+  - If neither found → `encrypted_transport = false`
+
+#### 2f — Detect DB Driver and Type
+
+Scan `package.json` dependencies AND all `require()`/`import`
+statements across the service for:
+  - `pg` or `pg-pool` or `postgres` → `db_type = "postgresql"`
+  - `mysql` or `mysql2` → `db_type = "mysql"`
+  - `mongoose` or `mongodb` → `db_type = "mongodb"`
+  - `better-sqlite3` or `sqlite3` → `db_type = "sqlite"` (note: not fully supported)
+  - `knex` or `sequelize` or `typeorm` or `prisma` →
+    note ORM found, attempt to infer underlying DB from config files
+
+Also check `config/database.js`, `config/db.js`, `database.js`,
+`src/config/database.js`, `db/index.js`, `src/db/index.js` for
+connection config strings that reveal the DB type.
+
+#### 2g — Detect Middleware Stack
+
+Do NOT assume agent-convention filenames. Instead, scan for
+middleware by behavior:
+
+Scan `app.use(` calls in the entry point AND any route manager /
+router index files. Also scan all files in:
+  - `middleware/`
+  - `middlewares/`
+  - `src/middleware/`
+  - Any file named `*middleware*`, `*validator*`, `*auth*`, `*guard*`
+
+For each middleware file found, classify by behavior:
+  - Reads `api-key` or `x-api-key` header and validates it →
+    record as `api_key_validator`
+  - Reads `Authorization` header or verifies JWT →
+    record as `auth_validator`
+  - Calls `req.ip` and tracks request counts →
+    record as `rate_limiter`
+  - Extracts language from header (Accept-Language, lang, language) →
+    record as `language_extractor`
+  - Decrypts `req.body` using AES or similar →
+    record as `decrypt_request`
+
+In legacy projects the functions above may all be in a single file
+(e.g. `common.js`, `headerValidator.js`, `app.js` directly).
+Classify by the behavior found, not by the filename.
+
+#### 2h — Detect Language / i18n Setup
+
+Scan for any of these i18n patterns:
+  - `languages/` directory with `*.js` files → read all filenames
+  - `locales/` directory with `*.json` files → read all filenames
+  - `i18n/` directory
+  - `localizify` in package.json → agent convention confirmed
+  - `i18next`, `vue-i18n`, `react-intl` in package.json → note library
+  - Any `require('../languages/')` or `require('./locales/')` references
+
+For `languages/` files → extract language code from filename
+(e.g. `en.js`, `ar.js`, `fr.js`) → build `supported_languages[]`
+
+#### 2i — Read Config Files (wherever they are)
+
+Do NOT look only in `config/`. Search for configuration across:
+  - `config/*.js` (agent convention)
+  - `src/config/*.js`
+  - `settings.js`, `settings/index.js`
+  - `constants.js`, `src/constants.js`, `config/constants.js`
+  - `common.js`, `config/common.js`
+
+From these files extract:
+  - Any hardcoded port references
+  - Any API version declarations (v1, v2)
+  - Any service name or project name constants
+  - Any feature flags
+
+#### 2j — Detect Redis Usage
+
+Scan for Redis client setup anywhere:
+  - `require('ioredis')`, `require('redis')`, `require("ioredis")`
+  - `new Redis(`, `redis.createClient(`
+  - Check extracted .env values for REDIS_HOST, REDIS_PORT
+
+#### 2k — Classify Service vs Agent-Initialized
+
+After all scans for this service, determine:
+
+**Agent-initialized** if ALL of these are true:
+  - `modules/v1/` directory exists
+  - `utilities/` directory exists with at least encryption.js and response.js
+  - `middleware/` directory exists with headerValidator.js
+  - `.codeninja/context/context.json` has an entry for this service
+
+**Legacy** if ANY of the above is false.
+
+Record the classification. Legacy services get a note in the sync
+report. Neither classification affects how the service is synced —
+both are fully scanned and registered in context.
+
+---
+
+### Phase 3 — Deep Scan Each ReactJS Service
+
+For each directory classified as `reactjs` in Phase 1:
+
+#### 3a — Identity and Package
+
+Read `package.json` → extract name, description, version, scripts.
+Note all dependencies.
+
+#### 3b — Find Entry and Port
+
+Look for dev server port in:
+  - `package.json` `scripts.start` (e.g. `PORT=3001 react-scripts start`)
+  - `.env` → `PORT` or `REACT_APP_PORT`
+  - `vite.config.js` or `vite.config.ts` → `server.port`
+  - `webpack.config.js` → `devServer.port`
+  - Default: 3000
+
+#### 3c — Find API Integration
+
+Determine what backend this React app talks to:
+  - `.env` → look for keys containing: BASE_URL, API_URL, API_BASE,
+    REACT_APP_BASE_URL, VITE_API_URL, VUE_APP_API_URL
+  - Extract hostname/port from those values
+  - Match the port against all known NodeJS services in current scan
+    to identify the `linked_service`
+  - Also scan `src/api/`, `src/services/`, `src/utils/`, `src/helpers/`
+    for axios/fetch base URL declarations (e.g. `baseURL:`, `axios.create(`,
+    `fetch('http`, `const API_URL =`, `const BASE_URL =`)
+
+#### 3d — Find Page / Route Structure
+
+Scan for React Router or equivalent:
+  - `src/App.jsx`, `src/App.js`, `src/App.tsx` → extract `<Route` declarations
+  - `src/router/`, `src/routes/` → extract route configs
+  - `src/pages/` → list subdirectories as page names
+  - `src/views/` → list subdirectories as view names
+  - `src/screens/` → list subdirectories (common in React Native style)
+
+#### 3e — Find Encryption Setup
+
+Scan for crypto-js usage in src/:
+  - Any `require('crypto-js')` or `import CryptoJS`
+  - Any `CryptoJS.AES.encrypt` / `CryptoJS.AES.decrypt` calls
+  - Check for these in: api/, utils/, services/, config/ subdirs
+  - In legacy React: may be in a standalone `utils/encryption.js` or
+    `helpers/crypto.js` or even inline in an axios interceptor
+
+#### 3f — Classify as Agent-Initialized or Legacy
+
+**Agent-initialized** if ALL true:
+  - `src/api/apiClient.js` exists
+  - `src/api/apiHandler.js` exists
+  - `.env` has REACT_APP_KEY, REACT_APP_IV, REACT_APP_API_KEY
+
+**Legacy** if any of the above is false.
+
+---
+
+### Phase 4 — Deep Scan Database
+
+For each database location found in Phase 1c:
+
+#### 4a — Determine Database Type
+
+If not already determined from service scans:
+  - Check folder name: `postgresql/`, `postgres/`, `mysql/`, `mongodb/`
+  - Check file extensions: `.sql` → relational; `.js` with Schema → MongoDB
+  - Check first SQL file header comments
+  - Check for `CREATE TABLE` → SQL-based
+  - Check for `mongoose.Schema` or `new Schema(` → MongoDB
+
+#### 4b — Parse SQL Migration Files
+
+For SQL databases, scan ALL `.sql` files regardless of naming convention.
+Do NOT require the agent's `N-setup-tbl-*.sql` naming pattern.
+
+For each `.sql` file found, parse for:
+
+**CREATE TABLE statements:**
+  - Extract table name (remove schema prefix if present, e.g. `public.`)
+  - Extract all column definitions:
+    - Column name
+    - Data type (normalize to lowercase)
+    - Constraints (NOT NULL, DEFAULT, CHECK, UNIQUE)
+    - PRIMARY KEY columns
+  - Extract inline index definitions
+  - Note any seed INSERT statements in the same file
+
+**ALTER TABLE statements:**
+  - ADD COLUMN → record column addition with table name
+  - RENAME COLUMN → record rename (from → to) with table name
+  - DROP COLUMN → record column removal with table name
+  - ADD CONSTRAINT → record constraint addition
+  - Modify type → record type change
+
+**CREATE INDEX statements:**
+  - Extract index name, table name, columns
+
+**DROP TABLE statements:**
+  - Record that the table was dropped
+
+Apply changes in file sort order:
+  - Try numeric prefix first: `1-*.sql`, `2-*.sql`, etc.
+  - Try timestamp prefix: `20240101_*.sql`
+  - Try V-prefix Flyway style: `V1__*.sql`, `V2__*.sql`
+  - If no order can be determined → process alphabetically and note it
+
+Build the final effective schema state from all migrations in order.
+The last state is what goes into `context.db.schema.tables`.
+
+#### 4c — Parse MongoDB Schema Files
+
+For MongoDB, scan ALL files for mongoose Schema definitions.
+
+For each Schema found → extract:
+  - Model name (from `mongoose.model('ModelName', schema)`)
+  - All field definitions with types and constraints
+  - Indexes defined with `schema.index()`
+
+Convert model name to snake_case for context key.
+Example: `UserBot` → stored as `user_bots`
+
+#### 4d — Find Non-Standard Schema Definitions
+
+For legacy projects that define schema in code rather than files:
+
+Scan ALL JavaScript files for ORM model definitions:
+  - Sequelize: `sequelize.define('model', {...})` or `DataTypes.*` in object
+  - TypeORM: `@Entity()`, `@Column()` decorators
+  - Prisma: check `prisma/schema.prisma`
+  - Knex: check migration files in any `migrations/` folder
+
+For each found → extract model/table name and column list as best
+as possible. Note in sync report that schema was inferred from ORM
+definitions, not raw SQL.
+
+#### 4e — Infer Schema From Query Patterns (last resort)
+
+If no migration files, schema files, or ORM models are found, but
+a database driver IS present in the service:
+
+Scan all model files (`*_model.js`, `*Model.js`, `*model.js`,
+files in `models/` directories) for SQL query strings:
+  - `SELECT * FROM <table>` → table name hint
+  - `INSERT INTO <table>` → table name hint
+  - Column names in SELECT lists → column hints
+  - Column names in WHERE clauses → column hints
+
+This is low-confidence data. Tag all values inferred this way as
+`confidence: "low"` and list them clearly in the sync report as
+requiring manual verification.
+
+---
+
+### Phase 5 — Infer Cross-Service Relationships
+
+After scanning all services individually, look for connections:
+
+#### 5a — ReactJS → NodeJS linking
+
+For each ReactJS service:
+  - Take the extracted API base URL port from Phase 3c
+  - Find the NodeJS service whose port matches
+  - Set `linked_service` to that service's name
+  - If no match found → note as "unlinked frontend" in sync report
+
+#### 5b — Shared Database
+
+Check if multiple services share the same DB connection config
+(same host, port, name) → they share a database. Note this in report.
+
+#### 5c — Port Inventory
+
+Build a complete port registry across all services found.
+Check for port conflicts (two services on the same port).
+If conflict found → flag in sync report as requires manual resolution.
+
+#### 5d — Shared Utilities or Libraries
+
+Check if any service directories import from each other or from a
+shared `lib/`, `shared/`, or `common/` directory at repository root.
+Note shared dependencies in the sync report — they may indicate
+a monorepo pattern that context should record.
+
+#### 5e — Environment Variable Cross-References
+
+If multiple services have `.env` files, check whether any service
+references another service's port in its config
+(e.g. one service's REDIS_HOST pointing to another service's host).
+Record these links as `service_dependencies` in context.
+
+---
+
+### Phase 6 — Conflict Resolution
+
+Before writing context, check for conflicts between scan results
+and existing context (Mode A only — skip in Mode B):
+
+For each discovered value that differs from an existing context value:
+  - Collect all conflicts into a list
+  - Show the user a conflict summary with current vs discovered values
+  - Ask user to confirm which to keep, ONE conflict at a time
+  - Do not write context until all conflicts are resolved
+
+Example conflict:
+  "Port for service 'auth' in context.json: 1001
+   Port found in auth/.env on disk: 1002
+   Which is correct? (context / disk)"
+
+---
+
+### Phase 7 — Build Context Updates
+
+Construct the full delta object to pass to context_write:
+
+#### 7a — For each service found:
+
+If service is NEW (not in context.services):
+  - Build full service entry from Phase 2 or Phase 3 scan results
+  - Set `sync_origin = "legacy"` if classified as legacy,
+    `sync_origin = "agent"` if agent-initialized
+  - Increment `services_synced` and `services_new` counters
+
+If service is EXISTING (already in context.services):
+  - Only update fields that were empty/null in context AND found on disk
+  - Never overwrite a populated context value unless user confirmed it
+    in Phase 6
+  - Record what was filled in for the report
+  - Increment `services_synced` counter
+
+Fields to sync per NodeJS service:
+  - name, port, description, author, package_name
+  - client_type, encrypted_transport, supported_languages
+  - encryption_key (if found in .env and not already in context)
+  - encryption_iv (if found in .env and not already in context)
+  - api_key (if found in .env and not already in context)
+  - redis_host, redis_port
+  - entry_point (actual path if different from app.js)
+  - tech_stack.dependencies (full list from package.json)
+  - middleware_stack (list of detected middleware types)
+  - sync_origin, last_synced_at = ISO now
+
+Fields to sync per ReactJS service:
+  - name, port, description
+  - linked_service, linked_service_port
+  - tech_stack.dependencies
+  - sync_origin, last_synced_at = ISO now
+
+#### 7b — For each route found:
+
+If route is NEW (not in context.api_routes):
+  - Add to api_routes[] with: service, method, path, version, module
+  - Increment `routes_discovered` and `routes_new` counters
+
+If route ALREADY in context.api_routes:
+  - Increment `routes_discovered` counter only
+
+#### 7c — For database:
+
+If db.type was empty in context:
+  - Set db.type, db.name, db.host, db.port, db.user from scan results
+
+For each table found during scan:
+  - If NEW → add to context.db.schema.tables with full column list
+    Increment `db_tables_new`
+  - If EXISTING → merge any new columns found on disk that are not
+    in context (may happen if migration was added manually)
+  - Increment `db_tables_synced` counter
+
+#### 7d — Set top-level context fields:
+
+  - If `project_name` is empty → set to first service name found
+  - If `initialized_at` is empty → set to ISO now
+  - Set `last_command` = "sync"
+  - Set `last_updated_at` = ISO now
+  - Set `last_command_at` = ISO now
+
+---
+
+### Phase 8 — Write Context
+
+Call MCP tool `context_write` with:
+  - `updates` = full delta object from Phase 7
+  - `operation` = "sync"
+
+This ALWAYS runs — even if nothing changed.
+context.json is always written at the end of @sync.
+
+If context.json did not exist before → this creates it for the first time.
+After context_write succeeds → call `context_clear_scratchpad` for
+any stale `current_*` keys found in Phase 0.
+
+---
+
+### Phase 9 — Drift Detection (Mode A only)
+
+This phase only runs when mode = A (agent-initialized project with
+existing context). Skip entirely for Mode B — legacy projects have
+no expected structure to drift from.
+
+Drift detection is read-only. Nothing is modified. Findings are
+informational only.
+
+For each service in context.services where `sync_origin == "agent"`
+(or sync_origin is absent, meaning it predates this sync versioning):
+
+#### Check 1 — route_manager.js middleware order
+
+Read: `<service>/modules/v1/route_manager.js`
+Expected: middleware registered in this exact order:
+  1. rateLimiter
+  2. extractLanguage
+  3. validateApiKey
+  4. validateToken
+  5. decryptRequest (only if encrypted_transport == true)
+
+How to check:
+Scan all `router.use('/', ...)` lines in order.
+Extract the middleware name from each line.
+Compare the extracted order against the expected order above.
+
+Drift conditions:
+- Any middleware is missing → DRIFT: "Missing middleware: [name]"
+- Any middleware appears in wrong position → DRIFT:
+  "[name] appears at position [n], expected position [m]"
+- decryptRequest present when encrypted_transport == false → DRIFT:
+  "decryptRequest registered but encrypted_transport is false"
+- decryptRequest absent when encrypted_transport == true → DRIFT:
+  "decryptRequest missing but encrypted_transport is true"
+- asyncHandler not wrapping any middleware → DRIFT:
+  "asyncHandler wrapper missing on [middleware_name]"
+
+---
+
+#### Check 2 — encryption.js library consistency
+
+Read: `<service>/utilities/encryption.js`
+Expected: imports only the library matching context.services[<n>].client_type
+  - client_type == "reactjs" → should import crypto-js, not cryptlib
+  - client_type == "app" → should import cryptlib, not crypto-js
+
+Drift conditions:
+- File imports cryptlib but context says client_type == "reactjs" →
+  DRIFT: "encryption.js uses cryptlib but client_type is reactjs"
+- File imports crypto-js but context says client_type == "app" →
+  DRIFT: "encryption.js uses crypto-js but client_type is app"
+- File imports both libraries → DRIFT:
+  "encryption.js imports both crypto-js and cryptlib — only one should be active"
+- Neither library found → DRIFT:
+  "encryption.js does not import any encryption library"
+
+---
+
+#### Check 3 — response.js encrypted_transport flag
+
+Read: `<service>/utilities/response.js`
+Expected: reads ENCRYPTED_TRANSPORT from process.env
+
+Drift conditions:
+- ENCRYPTED_TRANSPORT not referenced → DRIFT:
+  "response.js does not check ENCRYPTED_TRANSPORT — all responses
+  may be unencrypted regardless of config"
+- res.json( appears directly → DRIFT:
+  "response.js calls res.json() directly — responses bypass the encryption wrapper"
+
+---
+
+#### Check 4 — headerValidator.js decryptRequest presence
+
+Read: `<service>/middleware/headerValidator.js`
+Expected based on context.services[<n>].encrypted_transport:
+  - true → decryptRequest function must be defined and exported
+  - false → decryptRequest must NOT be present
+
+Drift conditions:
+- Function present but encrypted_transport == false → DRIFT:
+  "headerValidator.js defines decryptRequest but encrypted_transport
+  is false — dead code"
+- Function absent but encrypted_transport == true → DRIFT:
+  "headerValidator.js is missing decryptRequest but encrypted_transport
+  is true — request bodies will not be decrypted"
+
+---
+
+#### Check 5 — language file key parity
+
+Read: all files in `<service>/languages/`
+Expected: every language file has the same set of keys as en.js
+
+Drift conditions:
+- Any language file has fewer keys than en.js → DRIFT:
+  "[lang].js is missing [n] keys that exist in en.js: [list]"
+- Any language file has extra keys → DRIFT:
+  "[lang].js has [n] extra keys not in en.js: [list]"
+
+---
+
+#### Check 6 — package.json dependencies vs expected
+
+Read: `<service>/package.json` dependencies
+
+Required packages always:
+express, dotenv, localizify, moment, jsonwebtoken, ioredis,
+nodemailer, firebase-admin, validatorjs, pg-format,
+express-rate-limit, rand-token
+
+Required by client_type:
+- reactjs → crypto-js must be present
+- app → cryptlib must be present
+
+Required by db_type:
+- postgresql → pg must be present
+- mysql → mysql2 must be present
+- mongodb → mongoose must be present
+
+Drift conditions:
+- Required package missing → DRIFT:
+  "package.json is missing required dependency: [package_name]"
+- Wrong encryption package present → DRIFT:
+  "package.json has [wrong_package] but client_type is [type]"
+
+---
+
+#### Check 7 — model files pattern compliance
+
+For each module in context.services[<n>].modules:
+Read: `<service>/modules/v1/<ModuleName>/<module>_model.js`
+
+Drift conditions:
+- express imported → DRIFT:
+  "[module]_model.js imports express — model files must not use Express objects"
+- res.json or res.status found → DRIFT:
+  "[module]_model.js calls res.json/res.status directly"
+
+---
+
+## Drift Report Format
+
+After all checks complete, append to the sync report:
+```
+Drift Analysis
+─────────────────────────────────────────
+Files checked   : [n]
+Clean           : [n] (no drift detected)
+Drift found     : [n] files
+─────────────────────────────────────────
+[If drift found:]
+
+⚠ DRIFT DETECTED — manual review recommended
+
+[service_name]/modules/v1/route_manager.js
+  → Missing middleware: decryptRequest
+
+[service_name]/utilities/encryption.js
+  → encryption.js uses cryptlib but client_type is reactjs
+─────────────────────────────────────────
+NOTE: Drift is informational only. No files were modified.
+Run @audit for deeper code quality analysis.
+─────────────────────────────────────────
+```
+
+If no drift found:
+```
+Drift Analysis  : ✓ All [n] files match expected structure
+```
+
+---
+
+### Phase 10 — Sync Report
+
+Display the full sync report.
+
+```
+┌─────────────────────────────────────────────────┐
+│                  @sync Complete                 │
+└─────────────────────────────────────────────────┘
+
+Mode             : [Agent Project / Legacy Project]
+─────────────────────────────────────────────────
+Services scanned : [n]  ([x] new, [y] updated, [z] unchanged)
+Routes found     : [n]  ([x] new to context)
+DB tables found  : [n]  ([x] new to context)
+Gaps filled      : [n]
+Legacy inferences: [n]  (values derived from code analysis)
+─────────────────────────────────────────────────
+[If Mode B or any legacy services found:]
+
+⚙ Legacy Services Detected
+─────────────────────────────────────────────────
+[service_name]  ([tech_type])
+  Entry point   : [actual entry point file]
+  Port          : [port or "not found — check manually"]
+  Routes found  : [n] (from [location(s)])
+  DB driver     : [driver or "not detected"]
+  Encryption    : [library or "not detected"]
+  client_type   : [value or "could not determine — set manually"]
+  Languages     : [list or "none detected"]
+  Middleware    : [list of detected types]
+  ⚠ Values inferred from code — review and correct if needed
+
+[Repeat per legacy service]
+─────────────────────────────────────────────────
+[If any low-confidence values were inferred:]
+
+⚠ Low-Confidence Values (verify before using)
+  [service_name].port = [value]  — inferred from [source]
+  [service_name].client_type = [value]  — inferred from [source]
+  [list any others]
+  To correct: update context.json directly or re-run @sync
+  after adding a .env file with the correct values.
+─────────────────────────────────────────────────
+[If any misplaced database/ folders found:]
+
+⚠ Misplaced Database Folder
+  Found: [path inside service folder]
+  Expected: [repo_root]/database/
+  Scanned and added to context — consider moving to repo root.
+─────────────────────────────────────────────────
+[If any port conflicts found:]
+
+⚠ Port Conflicts
+  Port [port] is used by both: [service_a] and [service_b]
+  Review and update .env files to resolve before starting services.
+─────────────────────────────────────────────────
+[If any unlinked React frontends:]
+
+⚠ Unlinked Frontend
+  [service_name] — no matching backend found for API URL: [url]
+  Set context.services.[service_name].linked_service manually
+  or re-run @sync after the backend is initialized.
+─────────────────────────────────────────────────
+[If non-JS projects found:]
+
+ℹ Unsupported Tech Detected (recorded only, not parsed)
+  [folder_name] — [detected_tech]
+─────────────────────────────────────────────────
+[If Mode A — drift analysis section:]
+
+[Drift report as formatted above]
+─────────────────────────────────────────────────
+Context updated  : .codeninja/context/context.json ✓
+─────────────────────────────────────────────────
+```
+
+After the report, run task: `show-final-summary`
+
+---
+
+## Inference Confidence Levels
+
+When recording legacy-inferred values in context, tag each with:
+
+**HIGH** — value read directly from a config file (.env, package.json,
+  explicit constant). Treat as fact.
+
+**MEDIUM** — value inferred from code patterns (port from `.listen(PORT)`
+  where PORT came from a variable, not a literal).
+  Usable but should be confirmed.
+
+**LOW** — value guessed from folder name, comment, or single ambiguous
+  occurrence. Always listed in the sync report. User should confirm.
+
+Store as: `context.services[<n>].<field>_confidence = "high"|"medium"|"low"`
+
+---
+
+## What Sync Never Does
+
+- Never modifies any source file — read only outside of context.json
+- Never deletes service folders, SQL files, or any project files
+- Never removes existing context entries
+- Never overwrites a HIGH-confidence context value with a MEDIUM or
+  LOW inferred value without user confirmation
+- Never assumes a value is correct if two files disagree on it —
+  flag the conflict and ask
+- Never silently skips a directory — if it cannot be classified,
+  record it as unknown and mention it in the report
+- Never runs drift detection on legacy services — only agent-initialized