codeninja 2.0.0

package/tasks/write-context.task.md

@@ -0,0 +1,314 @@
+---
+type: task
+name: write-context
+---
+
+# File: .codeninja/context/context.json
+
+## Purpose
+Persists all in-memory context accumulated during the current workflow
+to disk. This file is the project's single source of truth — it must
+be written after every command that changes project state. If this
+file does not exist yet, create it. If it exists, merge the new values
+into it without removing existing entries.
+
+---
+
+## CRITICAL — How to Write This File
+
+Call MCP tool `context_write` with two parameters:
+- `updates` — the object containing all changes for this operation,
+  as defined in the Write Rules section below
+- `operation` — the command name e.g. "initialize-project",
+  "create-api", "db:create-table"
+
+The MCP tool handles everything automatically:
+reading the existing file, deep-merging updates, incrementing
+context_version, setting timestamps, and writing the file.
+
+After context_write succeeds, call MCP tool `context_clear_scratchpad`
+with the relevant current_* key for this operation.
+Example: after @initialize-project → clear ["current_init"]
+Example: after @create-api → clear ["current_api"]
+
+Do NOT write context.json any other way.
+Do NOT output context.json as a code block.
+Do NOT attempt to merge or write manually.
+
+---
+
+## Rules
+- NEVER delete existing entries — only add or update
+- NEVER clear `change_log` or `db.schema.change_log` — append only
+- NEVER leave `current_*` keys populated after a workflow completes —
+  always clear the relevant one
+- ALWAYS read the existing file first before writing — never blindly
+  overwrite with only the new data
+- ALWAYS increment `context_version` by 1 on every write
+- ALWAYS set `last_command_at` = ISO now on every write
+
+---
+
+## Stale Scratchpad Recovery
+
+After loading context.json in step 1 above, check all `current_*`
+keys in the loaded object.
+
+If any `current_*` key is non-empty AND `last_command_at` is more
+than 10 minutes ago → the previous workflow likely failed mid-run.
+
+Inform the user:
+"⚠ Found incomplete workflow state from a previous session:
+  current_[type] has data from [last_command_at].
+  This may be from an interrupted [last_command] operation.
+
+Options:
+1. Clear it — discard the incomplete state and start fresh
+2. Inspect it — show me what was in progress"
+
+If user selects Clear → set the non-empty `current_*` key to `{}`
+and run write-context to persist the cleanup.
+If user selects Inspect → display the `current_*` key contents
+and let the user decide what to do.
+
+Never silently discard stale scratchpad data.
+Never silently proceed with stale scratchpad data.
+Always surface it and let the user decide.
+
+---
+
+## Change Log Separation Rule
+
+- `context.change_log` (top-level): records COMMAND-level events only.
+  Who ran what command, when, and which files were affected.
+  Example: "initialize-project created auth service"
+
+- `context.db.schema.change_log`: records SCHEMA-level events only.
+  Column renames, table drops, index additions — the structural history
+  that agents need to reconstruct the DB state.
+  Example: "column_renamed from user_name to full_name in tbl_users"
+
+Never write the same event to both. DB operations append to
+db.schema.change_log only. The top-level change_log gets one summary
+entry per command run.
+
+---
+
+## Write Rules Per Operation
+
+### After @initialize-project
+- Set `project_name` = `current_init.service_name`
+  (top-level key — set on first init, kept as-is on subsequent services)
+- Set `initialized_at` = ISO now if not already set
+  (only set on the very first @initialize-project run)
+- Set `last_command` = `"initialize-project"`
+- Set `services.<service_name>` with values from `current_init`
+  according to project type:
+
+  **If `type == "nodejs"`** — store:
+  `type, port, description, package_name, author,`
+  `client_type, encrypted_transport, supported_languages, init_mode,`
+  `encryption_key, encryption_iv, api_key,`
+  `initialized_at = ISO now`
+
+  **If `type == "reactjs"`** — store:
+  `type, port, description, package_name, author,`
+  `linked_service, linked_service_port, init_mode,`
+  `initialized_at = ISO now`
+  Do NOT store `encryption_key`, `encryption_iv`, or `api_key` on the
+  reactjs service entry — those live only on the linked nodejs service.
+- Append to top-level `change_log`:
+  `{ timestamp, command: "initialize-project", action: "Service <name> initialized", affected_files: [] }`
+- Set `current_init` = `{}`
+- Set `last_updated_at` = ISO now
+- Increment `context_version` by 1
+- Set `last_command_at` = ISO now
+
+### After @create-api
+- Append route to `services.<name>.modules.<Module>.routes`
+- Append to `api_routes`
+- Append to `change_log`: "Route [METHOD] [path] added to [service]"
+- Set `current_api` = `{}`
+- Set `last_updated_at` = ISO now
+- Increment `context_version` by 1
+- Set `last_command_at` = ISO now
+
+### After @db:create-table
+- Append table to `db.schema.tables[<table_name>]` with full column list
+- Append to `db.schema.change_log`: `{ type: "table_created", table, file }`
+- Append to top-level `change_log`
+- Set `current_db` = `{}`
+- Set `last_updated_at` = ISO now
+- Increment `context_version` by 1
+- Set `last_command_at` = ISO now
+
+### After @db:modify-table (add column)
+- Append new column to `db.schema.tables[<table>].columns`
+- Append to `db.schema.change_log`: `{ type: "column_added", ... }`
+- Set `current_db` = `{}`
+- Set `last_updated_at` = ISO now
+- Increment `context_version` by 1
+- Set `last_command_at` = ISO now
+
+### After @db:modify-table (rename column)
+- Update column name in `db.schema.tables[<table>].columns`
+- Append to `db.schema.change_log`: `{ type: "column_renamed", from, to }`
+- Set `current_db` = `{}`
+- Set `last_updated_at` = ISO now
+- Increment `context_version` by 1
+- Set `last_command_at` = ISO now
+
+### After @db:modify-table (drop column)
+- Remove column from `db.schema.tables[<table>].columns`
+- Append to `db.schema.change_log`: `{ type: "column_dropped", snapshot: <col_def> }`
+- Set `current_db` = `{}`
+- Set `last_updated_at` = ISO now
+- Increment `context_version` by 1
+- Set `last_command_at` = ISO now
+
+### After @db:add-index
+- Append index name to `db.schema.tables[<table>].indexes`
+- Append to `db.schema.change_log`: `{ type: "index_added", ... }`
+- Set `current_db` = `{}`
+- Set `last_updated_at` = ISO now
+- Increment `context_version` by 1
+- Set `last_command_at` = ISO now
+
+### After @db:drop-table
+- Save full table snapshot to change_log entry before removing
+- Remove table from `db.schema.tables`
+- Append to `db.schema.change_log`: `{ type: "table_dropped", snapshot: {...} }`
+- Set `current_db` = `{}`
+- Set `last_updated_at` = ISO now
+- Increment `context_version` by 1
+- Set `last_command_at` = ISO now
+
+### After @db:seed
+- Append to `db.schema.change_log`: `{ type: "seed_added", table, rows: n }`
+- Set `current_db` = `{}`
+- Set `last_updated_at` = ISO now
+- Increment `context_version` by 1
+- Set `last_command_at` = ISO now
+
+### After @sync / @db:sync
+- Merge all discovered data — never overwrite existing entries
+- Append gap-fill entries to relevant change_log arrays
+- Set `last_updated_at` = ISO now
+- Increment `context_version` by 1
+- Set `last_command_at` = ISO now
+
+### After @refactor
+- Update the renamed key in its location
+- Append to top-level `change_log` with before/after values
+- For column renames: also append to `db.schema.change_log`
+- Set `current_refactor` = `{}`
+- Set `last_updated_at` = ISO now
+- Increment `context_version` by 1
+- Set `last_command_at` = ISO now
+
+### After @design (approved)
+- Append to `designs` array with `status: "planned"`
+- Set `current_design` = `{}`
+- Set `last_updated_at` = ISO now
+- Increment `context_version` by 1
+- Set `last_command_at` = ISO now
+
+### After @integrate-api / @modularize / @validate-page
+- Set `current_action` = `{}`
+
+### After @test
+- Append to `context.services[<n>].tests`: `{ module, type, file, timestamp }`
+- Set `current_test` = `{}`
+- Set `last_updated_at` = ISO now
+- Increment `context_version` by 1
+- Set `last_command_at` = ISO now
+
+---
+
+## current_* Namespace Rules
+- The `current_*` keys are scratchpad only — in-progress workflow state
+- ALWAYS clear the relevant `current_*` key after a workflow completes
+- NEVER read stale `current_*` data from a previous workflow run
+- If a workflow is aborted mid-way, clear its `current_*` key and
+  run write-context to persist the cleanup before exiting
+- If a `current_*` key is non-empty at activation time and
+  `last_command_at` is more than 10 minutes old → follow the
+  Stale Scratchpad Recovery procedure above
+
+---
+
+## Empty Schema (use when context.json does not exist yet)
+```json
+{
+  "context_version": 0,
+  "project_name": "",
+  "initialized_at": "",
+  "last_updated_at": "",
+  "last_command": "",
+  "last_command_at": "",
+  "repository_state": "",
+  "has_context_file": false,
+  "detected_services": [],
+  "detected_db": false,
+  "project_info": {
+    "has_doc": false,
+    "doc_url": "",
+    "doc_source": "",
+    "doc_content": "",
+    "has_sow": false,
+    "sow_url": "",
+    "sow_source": "",
+    "sow_content": "",
+    "has_figma": false,
+    "figma_url": "",
+    "figma_accessible": false,
+    "figma_screens": "",
+    "summary": "",
+    "detected_entities": [],
+    "from_doc": {
+      "project_name": "",
+      "domain": "",
+      "purpose": "",
+      "features": [],
+      "entities": [],
+      "tech_preferences": []
+    },
+    "from_sow": {
+      "phases": [],
+      "deliverables": [],
+      "apis_expected": [],
+      "tables_expected": [],
+      "integrations": [],
+      "constraints": [],
+      "timeline": ""
+    },
+    "from_figma": {
+      "screens": [],
+      "components_hinted": [],
+      "color_theme": ""
+    }
+  },
+  "db": {
+    "type": "",
+    "name": "",
+    "host": "",
+    "port": 0,
+    "user": "",
+    "schema": {
+      "tables": {},
+      "change_log": []
+    }
+  },
+  "services": {},
+  "api_routes": [],
+  "designs": [],
+  "change_log": [],
+  "current_init": {},
+  "current_api": {},
+  "current_action": {},
+  "current_refactor": {},
+  "current_design": {},
+  "current_test": {},
+  "current_db": {}
+}
+```