Merge pull request #69 from ActiveMemory/feat/docgo-quality-floor

Enrich all 610 doc.go files to meet quality floor

Author: josealekhine

.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.
 
+## 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.
+
+## 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
+
 ## Invoking ctx
 
 Always use `ctx` from PATH:

.context/AGENT_PLAYBOOK_GATE.md

@@ -10,10 +10,25 @@ lifecycle details, or anti-patterns.
 ctx status        # correct
 ./dist/ctx        # wrong — never hardcode paths
 go run ./cmd/ctx  # wrong — unless developing ctx itself
-```
+````
+
+## 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`
 to scaffold.
@@ -28,16 +43,25 @@ persist before continuing. Don't wait for session end.
 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               |

.context/CONSTITUTION.md

@@ -30,6 +30,16 @@ 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.**

.gitignore

@@ -46,6 +46,7 @@ dist/
 .claude/settings.local.json
 .claude/ralph-loop.local.md
 .claude/scheduled_tasks.lock
+.claude/worktrees/
 
 # Hook diagnostic logs (machine-specific, not committed)
 .context/logs/

cmd/ctx/doc.go

@@ -6,8 +6,29 @@
 
 // Package main is the entry point for the ctx CLI.
 //
-// The binary delegates immediately to [bootstrap.Execute], which
-// builds the root cobra.Command, registers all 24 subcommand
-// packages, and calls cmd.Execute. No business logic lives here;
-// version injection happens via ldflags at build time.
+// The binary performs three steps at startup:
+//
+//  1. Initializes the embedded asset lookup table via
+//     [lookup.Init] so that YAML-backed descriptions,
+//     templates, and text constants are available to
+//     every subcommand.
+//  2. Builds the root cobra.Command through
+//     [bootstrap.Initialize], which registers all
+//     subcommand packages, wires persistent flags,
+//     and injects build-time version metadata via
+//     ldflags.
+//  3. Calls cmd.Execute and translates any returned
+//     error into a formatted stderr message via
+//     [writeErr.With] before exiting with code 1.
+//
+// No business logic lives in this package. All
+// domain behavior is delegated to packages under
+// internal/.
+//
+// # Build-Time Injection
+//
+// Version, commit hash, and build date are injected
+// via ldflags at compile time. The Makefile and
+// goreleaser config set these values; the bootstrap
+// package reads them.
 package main

internal/assets/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,7 +72,6 @@ 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.
 
 ## Context Readback

internal/assets/context/AGENT_PLAYBOOK_GATE.md

@@ -10,10 +10,25 @@ lifecycle details, or anti-patterns.
 ctx status        # correct
 ./dist/ctx        # wrong — never hardcode paths
 go run ./cmd/ctx  # wrong — unless developing ctx itself
-```
+````
+
+## 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`
 to scaffold.
@@ -28,6 +43,20 @@ persist before continuing. Don't wait for session end.
 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

internal/assets/context/CONSTITUTION.md

@@ -32,6 +32,16 @@ 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.**

internal/assets/doc.go

@@ -4,11 +4,45 @@
 //   \    Copyright 2026-present Context contributors.
 //                 SPDX-License-Identifier: Apache-2.0
 
-// Package assets provides the embedded filesystem for ctx.
+// Package assets provides the embedded filesystem for
+// ctx.
 //
-// All templates, skills, hooks, YAML text files, and the Claude
-// Code plugin manifest are compiled into the binary via go:embed.
-// The single exported variable [FS] is the entry point for all
-// embedded asset reads. Subdirectories under assets/read/ provide
-// typed accessors grouped by domain (desc, entry, hook, skill, etc.).
+// All templates, skills, hooks, YAML text files, and
+// the Claude Code plugin manifest are compiled into
+// the binary via go:embed. The single exported
+// variable FS is the entry point for all embedded
+// asset reads.
+//
+// # Embedded Content
+//
+// The FS variable includes:
+//
+//   - claude/ -- CLAUDE.md, plugin.json, and skill
+//     definitions with SKILL.md and reference docs
+//   - context/ -- context file templates (TASKS.md,
+//     DECISIONS.md, CONVENTIONS.md, etc.)
+//   - entry-templates/ -- Markdown scaffolds for new
+//     decisions, learnings, tasks, conventions
+//   - hooks/ -- message templates and trace scripts
+//     for lifecycle hooks
+//   - integrations/ -- Copilot instructions, CLI
+//     hooks, agent configs, and scripts
+//   - project/ -- README templates for subdirectories
+//   - schema/ -- JSON Schema for .ctxrc validation
+//   - why/ -- philosophy documents (manifesto, about,
+//     design invariants)
+//   - permissions/ -- permission text files
+//   - commands/ -- YAML command/flag descriptions
+//
+// # Accessor Packages
+//
+// Subdirectories under assets/read/ provide typed
+// accessors grouped by domain, so callers do not
+// need to know embed paths:
+//
+//   - read/desc      -- command/flag/text descriptions
+//   - read/entry     -- entry template files
+//   - read/hook      -- hook message templates
+//   - read/skill     -- skill SKILL.md files
+//   - read/template  -- context file templates
 package assets