draft

.claude/skills/_ctx-audit/SKILL.md

@@ -323,8 +323,6 @@ rg 'default|Default' docs/configuration.md -n
 ```
 
 Cross-check:
-- `config.DirContext` value matches the `context_dir` default in docs
-  and sample `.ctxrc`
 - `FileReadOrder` entries match the `priority_order` list in sample
   `.ctxrc` and the docs "Default priority order" section
 - `DefaultTokenBudget`, `DefaultArchiveAfterDays`, etc. in `rc.go`

.context/AGENT_PLAYBOOK.md

@@ -15,6 +15,54 @@ making a decision, learning something, or hitting a milestone:
 persist before continuing. Don't wait for session end; it may
 never come cleanly.
 
+## File Interaction Protocol
+
+When a task involves reading, modifying, or reasoning about a file:
+
+1. **Read before act**
+    - Read the file content directly before making any change
+    - Do not rely on memory, summaries, or prior reads
+2. **No partial reads**
+    - Do not sample the beginning or end of a file and assume the rest
+3. **Freshness requirement**
+    - A read must be recent relative to the action
+    - Do not reuse stale context from earlier in the session
+4. **No implicit scope**
+    - "This change is small" is not a valid justification
+    - "This file is large" is not a valid justification
+5. **Edit authority comes from visibility**
+    - If you haven't seen it, you don't get to modify it
+
+## Spec Requirement
+
+Do not begin implementation work without a spec.
+
+- Every implementation task must trace to a spec file
+- **If no spec exists, STOP and create one first**
+- Do not treat task text alone as a substitute for a spec
+
+## Independent Review
+
+Sub-agent review is not optional once implementation begins.
+
+A review must be invoked when ANY of the following occur:
+
+- Before the first modification to the codebase
+- After completing one or more tasks in TASKS.md
+- Before declaring the work complete
+
+Required review inputs:
+- the governing spec
+- TASKS.md
+- the current implementation
+
+Review prompt:
+- "Review <spec-file>, TASKS.md, and the current implementation for drift,
+  omissions, invalid assumptions, and incomplete requirements."
+
+Do not declare work complete until review findings are either resolved or
+explicitly recorded.
+
 ## Invoking ctx
 
 Always use `ctx` from PATH:
@@ -24,9 +72,23 @@ ctx agent         # ✓ correct
 ./dist/ctx        # ✗ avoid hardcoded paths
 go run ./cmd/ctx  # ✗ avoid unless developing ctx itself
 ```
-
 Check with `which ctx` if unsure whether it's installed.
 
+### When ctx Returns an Error
+
+Triage the error before reacting:
+
+- **Invocation error**: the message points at your call: unknown
+  flag, unknown command, wrong argument count, missing required
+  flag. Read `ctx <command> --help`, fix the call, and retry.
+- **Everything else**: missing context directory, config problem,
+  hook rejection, permission denied, unexpected failure. Relay the
+  output to the user **verbatim** and stop. Do not add flags, run
+  other commands, edit files to fix the cause, or retry. Wait for
+  the user's next instruction.
+
+When unsure which kind you're looking at, treat it as the second.
+
 ## Context Readback
 
 Before starting any work, read the required context files and confirm to the
@@ -36,14 +98,36 @@ conventions." Do not begin implementation until you have done so.
 ## Supplementary Files
 
 These files live in `.context/` alongside the core context files.
-Read them when the task at hand warrants it — not on every session.
+Read them when the task at hand warrants it, not on every session.
 
 | File               | Read when                                                      |
 |--------------------|----------------------------------------------------------------|
 | ARCHITECTURE.md    | Working on structure, adding packages, or tracing flow         |
 | DETAILED_DESIGN.md | Deep-diving into internals (generated via `/ctx-architecture`) |
 | GLOSSARY.md        | Encountering unfamiliar project-specific terminology           |
 
+## Context Directory Lives at the Project Root
+
+The project root is the parent of `.context/`, by contract —
+specifically `filepath.Dir(ContextDir())`. That's where `ctx sync`,
+`ctx drift`, and the memory-drift hook look for code, secrets,
+and `MEMORY.md`.
+
+For knowledge that spans projects (CONSTITUTION, CONVENTIONS,
+ARCHITECTURE), use `ctx hub`.
+
+Recommended layout:
+
+```
+~/WORKSPACE/my-project
+  ├── .git
+  ├── .context
+  ├── Makefile
+  ├── Makefile.ctx
+  └── specs
+      └── ...
+```
+
 ## Reason Before Acting
 
 Before implementing any non-trivial change, think through it step-by-step:
@@ -100,7 +184,6 @@ Surface problems worth mentioning:
 - **Stale context files** (not modified recently): mention before
   stale context influences work
 - **Bloated token count** (over 30k): offer `ctx compact`
-- **Long single-line entries**: run `ctx fmt` to normalize line widths
 - **Drift between files and code**: spot-check paths from
   ARCHITECTURE.md against the actual file tree
 
@@ -123,14 +206,6 @@ is running long:
 Context compaction happens automatically, but the next window loses
 nuance. Explicit persistence is cheaper than re-discovery.
 
-### Check Available Skills
-
-Before starting any task, scan the skill list in your system
-prompt to see if a dedicated skill already handles the request.
-Prefer invoking an existing skill over ad-hoc implementation:
-skills encode project conventions, quality gates, and
-persistence steps that are easy to miss otherwise.
-
 ### Conversational Triggers
 
 Users rarely invoke skills explicitly. Recognize natural language:
@@ -242,7 +317,7 @@ Never assume. If you don't see it in files, you don't know it.
 ## Planning Work
 
 Every commit requires a `Spec:` trailer (CONSTITUTION rule). This means
-every piece of work needs a spec — no exceptions, no "trivial" qualifier.
+every piece of work needs a spec; no exceptions, no "trivial" qualifier.
 A one-liner bugfix gets a one-paragraph spec; a multi-package feature gets
 a full design document. The spec exists for traceability, not ceremony.
 
@@ -341,4 +416,3 @@ re-discovering it. 5 minutes reading saves 50 minutes of wasted work.
 - [ ] DECISIONS.md has no superseded entries unmarked
 - [ ] LEARNINGS.md gotchas still relevant
 - [ ] Run `ctx drift` and address warnings
-- [ ] Run `ctx fmt` to normalize line widths

.context/AGENT_PLAYBOOK_GATE.md

@@ -8,36 +8,66 @@ lifecycle details, or anti-patterns.
 
 ```bash
 ctx status        # correct
-./dist/ctx        # wrong — never hardcode paths
-go run ./cmd/ctx  # wrong — unless developing ctx itself
+./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. Use `/ctx-spec`
+a spec; no exceptions. Scale the spec to the work. Use `/ctx-spec`
 to scaffold.
 
 ## Proactive Persistence
 
-After completing a task, making a decision, or hitting a gotcha —
+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.
 
-## Check Available Skills
-
-Before starting any task, scan available skills to see if one
-already handles the request. Prefer skills over ad-hoc work.
-
 ## Conversational Triggers
 
 | User Says                                       | Action               |