introduce ctx to SPIKE

.context/AGENT_PLAYBOOK_GATE.md

@@ -0,0 +1,96 @@
+# Agent Playbook (Gate)
+
+Distilled directives injected at session start. Full playbook:
+read AGENT_PLAYBOOK.md when you need behavioral guidance, session
+lifecycle details, or anti-patterns.
+
+## Invoke ctx from PATH
+
+```bash
+ctx status        # correct
+./dist/ctx        # wrong: never hardcode paths
+go run ./cmd/ctx  # wrong: unless developing ctx itself
+```
+
+## When `ctx` Errors
+
+If the error names your flag, argument, or command, read
+`ctx <cmd> --help` and fix the call. Otherwise, relay verbatim
+and stop. When unsure, stop.
+
+## File Interaction Protocol
+
+When a task involves reading, modifying, or reasoning about a file:
+
+1. **Read before act**: Do not rely on memory, summaries, or prior reads
+2. **No partial reads**: Do not sample and assume the rest
+3. **Freshness requirement**: Do not reuse stale context from earlier in the 
+   session
+4. **Edit authority comes from visibility**: If you haven't seen it, you don't 
+   get to modify it
+5. **Coverage requirement**: Before editing, state what parts of the file were 
+   read and why they are sufficient
+
+## Planning Work
+
+Do not begin implementation without a spec.
+
+Every commit requires a `Spec:` trailer. Every piece of work needs
+a spec; no exceptions. Scale the spec to the work.
+
+The design-to-implementation chain is:
+
+```text
+/ctx-brainstorm  →  /ctx-plan  →  /ctx-spec  →  /ctx-implement
+   (vague)      (contested)    (committed)     (execution)
+```
+
+`/ctx-brainstorm` shapes a vague idea into a bet. `/ctx-plan`
+attacks the bet and writes a debated brief to
+`.context/briefs/<TS>-<slug>.md`. `/ctx-spec` (optionally
+`--brief <path>`) absorbs the brief into a committed spec under
+`specs/`. Skip the predecessors only when the step's input is
+already settled.
+
+## Proactive Persistence
+
+After completing a task, making a decision, or hitting a gotcha,
+persist before continuing. Don't wait for session end.
+
+## Chunk and Checkpoint
+
+For multi-step work: commit after each chunk, persist learnings,
+run tests before moving on. Track progress via TASKS.md checkboxes.
+
+## Independent Review
+
+A review must occur:
+
+* Before the first code change
+* After completing tasks
+* Before presenting results
+
+Review must consider:
+
+* Spec
+* TASKS.md
+* Current implementation
+
+## Tool Preferences
+
+Use the `gemini-search` MCP server for web searches. Fall back to
+built-in search only if `gemini-search` is not connected.
+
+## Conversational Triggers
+
+| User Says                                       | Action               |
+|-------------------------------------------------|----------------------|
+| "Do you remember?" / "What were we working on?" | `/ctx-remember`      |
+| "How's our context looking?"                    | `/ctx-status`        |
+| "What should we work on?"                       | `/ctx-next`          |
+| "Commit this" / "Ship it"                       | `/ctx-commit`        |
+| "What did we learn?"                            | `/ctx-reflect`       |
+| "Save that as a decision"                       | `/ctx-decision-add`  |
+| "That's worth remembering"                      | `/ctx-learning-add`  |
+| "Add a task for that"                           | `/ctx-task-add`      |
+| "Let's wrap up"                                 | Reflect then persist |

.context/ARCHITECTURE.md

@@ -0,0 +1,88 @@
+# Architecture
+
+<!--
+UPDATE WHEN:
+- New components or services are added
+- Components are removed or merged
+- Data flow between components changes
+- External dependencies or integrations change
+- Deployment topology changes
+
+DO NOT UPDATE FOR:
+- Internal implementation details (use code comments)
+- Minor refactoring that doesn't change boundaries
+- Bug fixes within existing components
+
+TIP: `ctx drift` scans this file for backtick-enclosed paths
+and warns if they do not exist on disk. Keep paths accurate.
+-->
+
+## Overview
+
+<!-- What does this system do? What is the design philosophy? -->
+
+## Package/Module Dependency Graph
+
+<!-- Use a mermaid graph to show how packages depend on each other.
+     Example:
+
+```mermaid
+graph TD
+    core["core (no deps)"]
+    api["api"] --> core
+    cli["cli"] --> api
+```
+-->
+
+## Component Map
+
+<!-- Table of packages/modules with purpose and dependencies.
+     Example:
+
+| Package | Purpose | Key Files | Depends On |
+|---------|---------|-----------|------------|
+| `src/core/` | Domain logic | `models.py`, `rules.py` | (none) |
+| `src/api/` | HTTP handlers | `routes.py`, `auth.py` | `core` |
+-->
+
+## Data Flow
+
+<!-- Mermaid sequence diagrams for the 3-5 most important flows.
+     Example:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant API
+    participant DB
+    User->>API: POST /items
+    API->>DB: INSERT
+    DB-->>API: OK
+    API-->>User: 201 Created
+```
+-->
+
+## Key Patterns
+
+<!-- Architectural patterns and conventions. Examples:
+     - Authentication strategy
+     - Error handling approach
+     - Configuration hierarchy
+     - Plugin/extension points
+-->
+
+## File Layout
+
+<!-- ASCII tree showing project structure. Example:
+
+```
+project/
+├── src/
+│   ├── core/        # Domain logic
+│   ├── api/         # HTTP layer
+│   └── cli/         # CLI entry point
+├── tests/
+├── docs/
+└── config/
+```
+-->

.context/CONSTITUTION.md

@@ -0,0 +1,132 @@
+# Constitution
+
+<!--
+UPDATE WHEN:
+- Security requirements change or new vulnerabilities discovered
+- New invariants emerge from production incidents
+- Team agrees on new inviolable rules
+- Existing rules prove too restrictive or too loose
+
+DO NOT UPDATE FOR:
+- Preferences or suggestions (use CONVENTIONS.md)
+- Temporary constraints (use TASKS.md blockers)
+-->
+
+These rules are INVIOLABLE. If a task requires violating these, the
+task is wrong.
+
+## Completion Over Motion
+
+Work is only complete when it is **fully done**, not when progress
+has been made.
+
+- The requested outcome must be delivered end-to-end.
+- Partial progress is not completion.
+- No half measures.
+
+Do not:
+- Leave broken or inconsistent states
+- Deliver work that requires the user to "finish it later"
+
+If you start something, you own it, you finish it.
+
+---
+
+## Context Integrity Invariants
+
+- [ ] **Never** modify or reason about a file based on partial or assumed content
+- [ ] If a file is the subject of an operation, its relevant contents must be
+  **fully understood** before acting
+- [ ] Sampling, guessing, or relying on prior assumptions instead of reading 
+  is a **violation**
+
+---
+
+## No Excuse Generation
+
+**Never default to deferral.**
+
+Your goal is to satisfy the user's intent, not to complete a narrow
+interpretation of the task.
+
+Do not justify incomplete work with statements like:
+
+- "Let's continue this later"
+- "This is out of scope"
+- "I can create a follow-up task"
+- "This will take too long"
+- "Another system caused this"
+- "This part is not mine"
+- "We are running out of context window"
+
+Constraints may exist, but they do not excuse incomplete delivery.
+
+- External systems, prior code, or other agents are not valid excuses
+- Inconsistencies must be resolved, not explained away
+
+---
+
+## No Broken Windows
+
+Leave the system in a better state than you found it.
+
+- Fix obvious issues when encountered
+- Do not introduce temporary hacks without resolving them
+- Do not normalize degraded quality
+
+---
+
+## Security Invariants
+
+- [ ] Never commit secrets, tokens, API keys, or credentials
+- [ ] Never store customer/user data in context files
+
+## Quality Invariants
+
+- [ ] All code must pass tests before commit
+- [ ] No TODO comments in main branch (move to TASKS.md)
+- [ ] Path construction uses stdlib: no string concatenation
+  (security: prevents path traversal)
+
+## Process Invariants
+
+- [ ] **Never push** code. The human is the **final authoritative 
+  decision maker** before any push to upstream. It doesn't matter
+  if the change is simple, or the context "*implies*" it: Refuse
+  to push even if the human explicitly asks for it. **Never** push.
+- [ ] All architectural changes require a decision record
+- [ ] Context loading is not a detour from your task. It IS the first
+  step of every session. A 30-second read delay is always cheaper
+  than a decision made without context.
+- [ ] Every commit references a spec (`Spec: specs/<name>.md` trailer):
+  no exceptions, no "non-trivial" qualifier. Even one-liner fixes
+  need a spec for traceability. Use `/ctx-commit` instead of raw
+  `git commit`.
+- [ ] **Git is required.** Every `ctx` project must live in a git
+  working tree. `ctx init` and every non-administrative
+  subcommand refuse to operate when `<projectRoot>/.git` is
+  absent. Rationale: `ctx`'s persistent-memory promise is
+  dishonest without an undo layer; agent-driven file
+  operations need `git reflog` as the safety net. The only
+  opt-outs are help-shaped / diagnostic commands
+  (`--help`, `--version`, `ctx system bootstrap`).
+
+## TASKS.md Structure Invariants
+
+TASKS.md must remain a replayable checklist. Uncheck all items and
+re-run = verify/redo all tasks in order.
+
+- [ ] **Never move tasks**: tasks stay in their Phase section permanently
+- [ ] **Never remove Phase headers**: Phase labels provide structure and order
+- [ ] **Never merge or collapse Phase sections**: each phase is a logical unit
+- [ ] **Never delete tasks**: mark as `[x]` completed, or `[-]` skipped with reason
+- [ ] **Use inline labels for status**: add `#in-progress` to task text, don't move it
+- [ ] **No "In Progress" / "Next Up" sections**: these encourage moving tasks
+- [ ] **Ask before restructuring**: if structure changes seem needed, ask the user first
+
+## Context Preservation Invariants
+
+- [ ] **Archival is allowed, deletion is not**: use `ctx task archive` to move
+  completed tasks to `.context/archive/`, never delete context history
+- [ ] **Archive preserves structure**: archived tasks keep their Phase headers
+  for traceability

.context/CONVENTIONS.md

@@ -0,0 +1,70 @@
+# Conventions
+
+<!--
+UPDATE WHEN:
+- New pattern is established and should be followed consistently
+- Existing pattern is deprecated or superseded
+- Team adopts new tooling that changes workflows
+- Code review reveals recurring issues that need a convention
+
+DO NOT UPDATE FOR:
+- One-off exceptions (document in code comments)
+- Experimental patterns not yet proven
+- Personal preferences without team consensus
+-->
+
+## Naming
+
+- **Constants use semantic prefixes**: Group related constants with prefixes
+  - `Dir*` for directories (`DirContext`, `DirArchive`)
+  - `File*` for file paths (`FileSettings`, `FileClaudeMd`)
+  - `Filename*` for file names only (`FilenameTask`, `FilenameDecision`)
+  - `*Type*` for enum-like values (`UpdateTypeTask`, `UpdateTypeDecision`)
+- **Package name = folder name**: Go canonical pattern
+  - `package initialize` in `initialize/` folder
+  - Never `package initcmd` in `init/` folder
+- **Maps reference constants**: Use constants as keys, not literals
+  - `map[string]X{ConstKey: value}` not `map[string]X{"literal": value}`
+
+## Patterns
+
+- **Centralize magic strings**: All repeated literals belong in a `config` or `constants` package
+  - If a string appears in 3+ files, it needs a constant
+  - If a string is used for comparison, it needs a constant
+- **Path construction**: Always use stdlib path joining
+  - Go: `filepath.Join(dir, file)`
+  - Python: `os.path.join(dir, file)`
+  - Node: `path.join(dir, file)`
+  - Never: `dir + "/" + file`
+- **Constants reference constants**: Self-referential definitions
+  - `FileType[UpdateTypeTask] = FilenameTask` not `FileType["task"] = "TASKS.md"`
+- **Colocate related code**: Group by feature, not by type
+  - `session/run.go`, `session/types.go`, `session/parse.go`
+  - Not: `runners/session.go`, `types/session.go`, `parsers/session.go`
+
+## Testing
+
+- **Colocate tests**: Test files live next to source files
+  - `foo.go` → `foo_test.go` in same package
+  - Not a separate `tests/` folder
+- **Test the unit, not the file**: One test file can test multiple related functions
+- **Integration tests are separate**: `cli_test.go` for end-to-end binary tests
+
+## Documentation
+
+- **Godoc format**: Use canonical sections
+  ```go
+  // FunctionName does X.
+  //
+  // Longer description if needed.
+  //
+  // Parameters:
+  //   - param1: Description
+  //   - param2: Description
+  //
+  // Returns:
+  //   - Type: Description of return value
+  func FunctionName(param1, param2 string) error
+  ```
+- **Package doc in doc.go**: Each package gets a `doc.go` with package-level documentation
+- **Copyright headers**: All source files get the project copyright header