@mod-computer/cli 0.1.0

package/README.md

@@ -0,0 +1,125 @@
+# mod-cli
+
+## Intro
+
+mod-cli is the local sync agent for Mod, a collaboration layer for teams working with coding agents.
+
+Coding agents operate on local filesystems. They read specs, write code, and generate metadata (traces, reasoning, todos). But collaboration happens elsewhere: in GitHub PRs, Notion docs, Slack threads. The result: context lives in silos. Agents can't access specs being discussed in the browser. Teammates can't see agent reasoning. Reviews happen without the full picture.
+
+mod-cli bridges local and collaborative workflows. It syncs the local filesystem to Mod workspaces in real-time, making local changes visible to collaborators and remote edits available to agents. The CLI turns a directory into a distributed, collaborative filesystem.
+
+## Conceptual Overview
+
+**Workspaces**: A workspace is a container for files, branches, and metadata. Create workspaces with `mod workspace create`, list them with `mod workspace list`, switch with `mod workspace switch`. Each workspace has its own history, collaborators, and sync state. A directory connects to one workspace at a time.
+
+**Local-First Sync**: `mod sync start` launches a daemon that watches the local directory and syncs to the connected workspace. File edits, new files, deletions propagate automatically. Remote changes from collaborators sync back to local files. The daemon runs in the background; coding agents work locally as normal. Multiple collaborators can sync to the same workspace from different machines.
+
+**Branching**: Mod branches are lightweight isolation scopes for work-in-progress. Unlike git branches, they don't require commits or staging. Create a branch, start working, and all changes are tracked automatically. When integrated with git, Mod branches map to git branches. Without git, Mod branches provide standalone isolation.
+
+**Changelog**: Every file change on a branch is recorded automatically with timestamp, diff, and context. No manual commits required. The changelog captures what changed, when, and alongside what other activity (agent conversations, spec edits, collaborator comments). View at branch level or filter to a specific file.
+
+**Reversion**: Restore to any point in the changelog. Revert an entire branch to a previous state, or revert a single file while keeping other files at their current state. Fine-grained reversion without needing explicit commits as restore points.
+
+**Merge**: Combine branches by merging their changes. Mod detects conflicts at the file level and surfaces them for resolution. Metadata (comments, traces) merges automatically. After merge, the target branch contains changes from both branches with full history preserved.
+
+**Git Integration**: In git repositories, sync respects git branch scope. Changes on a git branch sync to the corresponding Mod branch. Switching git branches switches sync context automatically. For non-git directories, Mod branches work independently. The CLI integrates with git workflows but doesn't require git.
+
+**Metadata Layer**: Workspaces and files carry metadata: comments, notes, and traces. The CLI provides commands to read and write metadata locally. Agents can query file context before making changes and write traces linking code to requirements. Teams see the same metadata in the web app. This shared context layer makes agent reasoning visible and lets teams annotate code without changing source files.
+
+**File Import**: For existing projects, `mod sync import` brings current files into the workspace. In git repos, import can pull from git history. Preview first with `--preview` to see what will sync. After import, changes sync automatically.
+
+## Example
+
+A developer is implementing an authentication feature using Claude Code.
+
+**1. Initialize**: The developer runs `mod init` in their project directory. They sign in (or are prompted to create an account), then select an existing workspace or create a new one. The directory is now connected to the workspace.
+
+**2. Start sync**: They run `mod sync start`. The daemon launches in the background, watching for file changes and syncing to the workspace.
+
+**3. Create branch**: They run `mod branch create add-auth`. A new branch is created. The spec file `specs/auth.md` was collaboratively edited in the web app and is already synced locally.
+
+**4. Work with agent**: They prompt Claude Code to implement the spec. Claude reads `specs/auth.md` from the filesystem, checks existing comments with `mod comment list`, implements the requirements, and adds traces with `mod trace add src/auth.ts REQ-AUTH-1`. Every file change and metadata update syncs automatically.
+
+**5. Review changelog**: Running `mod changelog` shows all file changes with timestamps and diffs. The developer sees implementation progress alongside agent conversation context.
+
+**6. Collaborate**: A teammate edits the spec in the web app, adding a section on rate limiting. The edit syncs to the local file. The developer prompts Claude again, and new changes sync back.
+
+**7. Ready for review**: Running `mod branch status` shows all changed files. The developer opens the web app to the review view, where teammates see file changes alongside traces and agent reasoning.
+
+## How It Works
+
+**Sync Daemon**: `mod sync start` launches a background daemon that watches the directory. File system events trigger sync operations. The daemon maintains a WebSocket connection to the sync server for real-time updates.
+
+**Automerge Storage**: Local workspace state uses Automerge, a CRDT library for conflict-free replication. Changes merge automatically without coordination. The CLI stores Automerge documents in `~/.mod/` at the device root, shared across all connected repos.
+
+**Bidirectional Sync**: Local file changes update Automerge documents and propagate to the server. Server changes (from collaborators or the web app) update local Automerge state and write back to files. The sync is continuous and automatic.
+
+**Branch State**: Each branch maintains independent file states in Automerge. Switching branches updates local files to match. Branch metadata and change history sync alongside file content.
+
+**Changelog**: The CLI records every file change with timestamp, diff, and surrounding context. The changelog is queryable and connects code changes to concurrent activity like agent conversations and collaborator edits.
+
+## Commands Reference
+
+### Core Commands
+
+```bash
+mod init                    # Initialize workspace and install Claude commands
+mod sync start              # Start background sync daemon
+mod sync stop               # Stop sync daemon
+mod sync status             # Show sync health and connection status
+mod sync import             # Import existing files to workspace
+```
+
+### Branch Management
+
+```bash
+mod branch create <name>    # Create new branch
+mod branch switch <name>    # Switch to branch
+mod branch list             # List all branches
+mod branch status           # Show current branch and changes
+mod branch changelog        # Show automatic changelog
+mod branch tree             # Display directory tree
+```
+
+### Workspace Management
+
+```bash
+mod workspace create <name> # Create new workspace
+mod workspace list          # List workspaces
+mod workspace switch <name> # Switch active workspace
+mod workspace info          # Show workspace details
+```
+
+### Metadata
+
+```bash
+mod comment add <file> <text>   # Add comment to file
+mod comment list [file]         # List comments (all or per file)
+mod note set <file> <text>      # Set note on file
+mod note get <file>             # Get note for file
+mod trace add <file> <req-id>   # Add trace linking file to requirement
+mod trace list [file]           # List traces (all or per file)
+```
+
+## Development
+
+```bash
+pnpm install    # Install dependencies
+pnpm build      # Build CLI
+pnpm dev        # Watch mode
+pnpm test       # Run tests
+```
+
+## Thoughts
+
+**Daemon architecture**: The sync daemon runs as a background process rather than requiring an active terminal. This lets developers work normally while sync happens invisibly. The daemon writes logs to `~/.mod/logs/sync.log` for debugging.
+
+**CRDT trade-offs**: Automerge handles conflicts automatically, but the resulting merges aren't always what users expect for text files. Currently optimizing for metadata sync; file content sync may need smarter merge strategies.
+
+**Git integration**: In git repos, sync is branch-aware: git branch switches trigger Mod branch switches. Mod adds real-time collaboration and agent context on top of git. In non-git directories, Mod provides standalone change tracking and sync.
+
+**Device-level storage**: All state lives in `~/.mod/` at the device root rather than per-repo. Sign in once, use across all repos. Single daemon can sync multiple connected directories. No per-repo config to gitignore.
+
+**Metadata commands**: Specific commands for comments, notes, and traces rather than a generic `mod meta` interface. Agents benefit from semantic clarity. Each metadata type has different workflows: comments are threaded, notes are single per file, traces link to requirement IDs. Keeping them separate makes intent clear for both agents and humans.
+
+**Offline handling**: The daemon queues changes when offline and syncs when reconnected. Local edits always work; sync catches up when possible. Conflict resolution happens through Automerge's CRDT properties.

package/commands/execute.md

@@ -0,0 +1,156 @@
+---
+version: 2.0.0
+updated: 2026-01-03
+description: Execute specification with complete traceability implementation
+---
+
+# Specification Execution with Complete Traceability
+
+Given this specification file: ".mod/specs/<optional-folder>/$ARGUMENTS"
+
+## Branch Context and Specification Setup
+
+**Automatic Branch Detection and Context Gathering:**
+
+**If no specification argument provided:**
+1. **Check active branch** for linked specification:
+   ```bash
+   mod branch status
+   # Should show active branch and linked specification
+   ```
+2. **Error handling** for lightweight branches:
+   ```bash
+   # If current branch has no specification:
+   # > Current branch "fix-auth-timeout" is a lightweight branch with no specification
+   # > Options:
+   # > 1. Link specification: mod branch spec-link <spec-file>
+   # > 2. Create specification branch: mod branch create feature-<name> --spec <spec-file>
+   # > 3. Switch to specification branch: mod branch switch <spec-branch>
+   ```
+
+**If specification argument provided (e.g., `branching-cli.spec.md`):**
+1. **Auto-switch to specification branch**:
+   ```bash
+   # Check if corresponding branch exists
+   mod branch list | grep "feature-.*branching-cli"
+
+   # If exists, switch to it
+   mod branch switch feature-mod-cli-branching-cli
+
+   # If doesn't exist, create it
+   mod branch create feature-mod-cli-branching-cli --spec mod-cli/branching-cli.spec.md
+   ```
+2. **Verify branch setup**:
+   ```bash
+   mod branch status
+   # Should confirm specification branch is active and linked
+   ```
+
+**Context Gathering (Automatic):**
+1. **Implementation Progress**: `mod branch status` shows current implementation changes
+2. **Specification Requirements**: `mod status <spec-name>.spec.md` shows requirements and traceability
+3. **Coverage Analysis**: `glassware` shows which code has implementation traces
+
+## Pre-Execution Analysis
+
+**BEFORE implementation:**
+1. Read and fully understand the complete specification, including all sub-requirements
+2. Parse all ARCH-*, BEH-*, DATA-*, and TEST-* requirements for dependency analysis
+3. Identify numbered sub-requirements (e.g., BEH-AUTH-1.1, BEH-AUTH-1.2) for granular execution
+4. Create implementation plan prioritizing ARCH → DATA → BEH → TEST requirements
+
+**Understanding existing code changes:**
+5. Use `mod branch status` to see what code changes have already been made on this branch
+6. Run `glassware` to understand spec traceability coverage of existing code on branch
+
+## Mandatory Traceability Implementation
+
+**CRITICAL: Use glassware annotations for all traceability**
+
+### Glassware Annotation Format
+
+**In Markdown specs/requirements:**
+```markdown
+The system must validate user credentials. <glassware type="requirement" id="REQ-AUTH-1" />
+```
+
+**In TypeScript implementations:**
+```typescript
+// glassware[type=implementation, id=unique-impl-id, requirements=REQ-ID]
+```
+
+### Complexity-Based Traceability Standards
+- **Method-Level (Default)**: Single glassware comment for simple functions (<10 lines, no branching)
+- **Line-Level (Complex)**: Detailed glassware comments for complex logic (>10 lines, branching, error handling)
+- **Business Logic Priority**: Always use line-level traces for business logic patterns regardless of complexity
+
+### Granularity Decision Rules
+**For each function, analyze and apply:**
+
+1. **Business Logic Check** - Does function name/purpose include: validate, auth, pay, charge, encrypt, save, persist?
+   → If YES: Always use **line-level** traces
+
+2. **Complexity Check** - Count lines of actual code (exclude comments/whitespace):
+   → If >10 lines OR has conditionals (if/switch/try/for/while): Use **line-level** traces
+   → If ≤10 lines AND no conditionals: Use **method-level** traces
+
+3. **Error Handling Check** - Does function have try-catch or multiple return paths?
+   → If YES: Use **line-level** traces
+
+### Method-Level Example (Simple Function)
+```typescript
+// glassware[type=implementation, id=validate-user, requirements=REQ-AUTH-1]
+function validateUser(email: string, password: string): boolean {
+  return bcrypt.compare(password, getStoredHash(email));
+}
+```
+
+### Line-Level Example (Complex Function)
+```typescript
+function processPayment(order: Order, card: CreditCard): PaymentResult {
+  // glassware[type=implementation, id=validate-order, requirements=REQ-PAY-1]
+  if (order.amount <= 0 || !SUPPORTED_CURRENCIES.includes(order.currency)) {
+    throw new ValidationError("Invalid order parameters");
+  }
+
+  // glassware[type=implementation, id=fraud-check, requirements=REQ-PAY-2]
+  const fraudScore = await fraudDetection.analyze(card, order);
+  if (fraudScore > FRAUD_THRESHOLD) {
+    // glassware[type=implementation, id=fraud-logging, requirements=REQ-PAY-3]
+    await auditLog.record('fraud_detected', { order: order.id, score: fraudScore });
+    throw new FraudError("Transaction blocked by fraud detection");
+  }
+
+  // glassware[type=implementation, id=process-charge, requirements=REQ-PAY-4]
+  return await paymentGateway.charge(card, order.amount);
+}
+```
+
+## Execution Workflow
+
+**For each implementation cycle, MUST apply this process:**
+1. **Analyze Complexity**: Count lines, branches, and business logic patterns
+2. **Apply Granularity Rules**: Use method-level for simple functions, line-level for complex
+3. **Business Logic Override**: Always apply line-level traces for business logic patterns
+4. **Embed During Generation**: Add glassware traces as code is generated, not afterward
+5. **Test Progress**: Run `glassware` to verify traceability coverage
+6. **Iterate**: Continue implementing and tracing until all requirements show as implemented
+
+## Real-Time Quality Gates
+
+**Execution agents MUST enforce these standards:**
+- **Specification Coverage**: ≥90% of sub-requirements implemented
+- **Appropriate Granularity**: Complex functions have line-level traces, simple functions have method-level
+- **Business Logic Traceability**: All business logic has detailed line-level glassware traces
+- **Invalid References**: 0 glassware comments pointing to non-existent requirements
+
+## Success Criteria
+
+✅ **Complete Implementation**: All numbered sub-requirements implemented and working
+✅ **Full Traceability**: Every implementation decision traced to specific sub-requirement
+✅ **Status Verification**: `glassware` shows all requirements as implemented
+✅ **Quality Gates Passed**: Coverage and traceability thresholds met
+✅ **Test Coverage**: All TEST-* requirements implemented with glassware traces
+✅ **Zero Orphaned Code**: All new code has valid glassware requirement references
+
+**CRITICAL**: Run `glassware` before and after each implementation phase to verify progress. Additionally, use `mod branch status` to understand what code changes were made for the spec. Do not mark tasks complete until glassware shows all requirements implemented.

package/commands/overview.md

@@ -0,0 +1,233 @@
+---
+version: 2.0.0
+updated: 2026-01-03
+description: Generate workspace specification scaffolding and overview
+---
+
+# Workspace Specification Scaffolding
+
+## Command Modes
+
+**Two-Step Process:**
+
+1. **Overview Mode** (no arguments): `workspace-spec`
+   - Performs full codebase analysis
+   - Generates overview of current architecture  
+   - Plans specification structure
+   - Outputs proposed organization without creating files
+
+2. **Implementation Mode** (with argument): `workspace-spec <workspace-name>` or `workspace-spec overview.spec.md`
+   - Creates the planned specification directory structure
+   - Generates template files based on analysis from overview mode
+   - Implements the full scaffolding process
+
+---
+
+### Overview Mode (No Arguments)
+
+When no arguments are provided, perform analysis and planning only:
+
+**ANALYSIS TASKS:**
+1. Analyze existing codebase architecture and component organization
+2. Scan `.mod/specs/` (or existing spec directories) for current specification structure and patterns  
+3. Identify feature domains from component names and folder hierarchy
+4. Detect specification gaps where components exist but specifications are missing
+5. Generate hierarchical specification organization plan
+
+**OUTPUT OVERVIEW:**
+- Current codebase architecture summary
+- Identified components and their organization
+- Existing specification coverage analysis
+- Project directory hierarchy map with key ownership notes
+- Recommendation for workspace name and organization
+
+**NO FILES CREATED** - This mode only analyzes and plans.
+
+---
+
+### Implementation Mode (With Arguments)
+
+When arguments are provided (`workspace-spec <workspace-name>` or `workspace-spec overview.spec.md`):
+
+**Argument Handling:**
+- If argument is "overview.spec.md" → Use default workspace name based on project directory
+- If argument is a custom name → Use provided workspace name: "$ARGUMENTS"
+- Both cases proceed with full scaffolding implementation
+
+## Workspace Scaffolding Process
+
+### 1. Codebase Architecture Discovery
+
+**Project Structure Analysis**:
+- Scan project directory for all components/modules and their organization
+- Identify core components (main application logic, shared libraries)
+- Categorize feature components (domain-specific functionality, user-facing features)
+- Discover infrastructure components (utilities, services, configuration, deployment)
+
+**Existing Specification Audit**:
+- List all current `.mod/specs/` folders and specification files (or detect existing spec directories)
+- Identify coverage gaps where components have no specifications
+- Analyze specification quality and completion status
+- Map specification relationships and dependencies
+
+### 2. Project Hierarchy Mapping
+
+**Project Organization Deliverable**:
+- Enumerate the actual workspace directories (packages, apps, services, docs, tooling)
+- Highlight the major subdirectories under the focus package (e.g., `source/commands`, `source/services`, `tests/containers`)
+- Note ownership and responsibility per directory so downstream specs know where behavior lives
+
+**Suggested Output Format**:
+```
+packages/
+└── [workspace-name]/
+    ├── source/
+    │   ├── app.tsx
+    │   ├── cli.tsx
+    │   ├── commands/               # Headless commands
+    │   ├── containers/             # Ink UI views
+    │   ├── services/               # Shared domain logic
+    │   ├── components/             # Reusable Ink components
+    │   ├── stores/                 # Zustand state
+    │   └── shims/                  # Polyfills/adapters
+    ├── tests/
+    │   ├── services/
+    │   ├── containers/
+    │   └── _harness/
+    ├── docs/
+    ├── dist/
+    ├── README.md
+    ├── package.json
+    └── vitest.config.ts
+```
+
+Use this hierarchy to anchor the overview narrative, tie directories to functionality, and call out gaps (e.g., missing tests folder, duplicated services). This replaces the previous "proposed spec tree" so the overview focuses on the real project layout before any scaffolding occurs.
+
+### 3. Template Population System
+
+**Generic Specification Template Structure for Each Specification**:
+```markdown
+---
+title: [feature-name]
+type: specification
+---
+# [Feature Name] Specification
+
+## Abstract
+[One-sentence system summary with key capabilities and scale targets]
+
+## Motivation
+### Current Problems
+- [Specific problem this feature solves]
+
+### Business Impact  
+- [Value delivered and success metrics]
+
+## Approach
+[High-level solution architecture and key technical decisions]
+
+## UX Requirements (UX-*)
+[UI components, user flows, and accessibility]
+
+## Application Requirements (APP-*)  
+[Business logic, workflows, and validation rules]
+
+## Integration Requirements (INT-*)
+[APIs, external services, and data exchange]
+
+## Infrastructure Requirements (INFRA-*)
+[System architecture, deployment, and scaling]
+
+## Quality Requirements (QUAL-*)
+[Testing, performance, and security criteria]
+
+## Expected Glassware Trace Formats
+**Method-Level**: `// glassware[type=implementation, id=unique-id, requirements=REQ-CATEGORY-N]`
+**Line-Level**: Same format, placed above specific logic blocks
+```
+
+### 4. Intelligent Content Generation
+
+**For Each Component**:
+1. **Analyze project files** (package.json, pyproject.toml, Cargo.toml, etc.) for dependencies and scripts to understand functionality
+2. **Scan source code** for main classes, services, and architectural patterns
+3. **Identify integration points** through import analysis and API usage
+4. **Generate initial requirements** based on discovered functionality patterns
+5. **Create placeholder specifications** with discovered structure and TODO sections
+
+**Business Logic Pattern Detection**:
+- Authentication/authorization functions → Security specification requirements
+- Data persistence operations → Data management specification requirements  
+- External API integrations → Integration specification requirements
+- UI components and workflows → UX specification requirements
+
+### 5. Cross-Component Dependency Mapping
+
+**Integration Analysis**:
+- Map import relationships between components to identify integration specifications needed
+- Identify shared types and interfaces requiring API contract specifications
+- Discover common patterns requiring cross-cutting concern specifications
+- Generate integration requirement matrix for multi-component features
+
+**Dependency Documentation**:
+- Create visual dependency graph in `requirements-matrix.md`
+- Document shared service contracts in `integration-points.md`
+- Identify specification completion priorities based on dependency criticality
+
+## Scaffolding Execution Workflow
+
+### Phase 1: Discovery and Planning
+1. Run codebase analysis to understand current architecture
+2. Generate proposed specification folder structure
+3. Display plan to user with component coverage analysis
+4. Identify critical specification gaps requiring immediate attention
+
+### Phase 2: Structure Creation  
+1. Detect existing specification directory structure (`.mod/specs/`) or create `.mod/specs/` if none exists
+2. Create hierarchical folder structure within the specification directory
+3. Generate template specification files with component-specific content
+4. Populate initial requirements based on code analysis
+5. Create cross-reference documentation and dependency matrix
+
+### Phase 3: Integration Setup
+1. Update existing specifications with cross-component integration requirements  
+2. Generate shared specification files for cross-cutting concerns
+3. Create workspace overview documentation linking all specifications
+4. Establish specification completion roadmap with priorities
+
+### Phase 4: Validation and Reporting
+1. Validate all generated specification files for template compliance
+2. Check cross-reference integrity between specifications
+3. Generate workspace specification summary report
+4. Provide next steps for specification completion and implementation
+
+## Quality Standards
+
+**Template Compliance**:
+- All specifications include complete template structure with all required sections
+- Requirement numbering follows category prefix standards (UX-*, APP-*, INT-*, INFRA-*, QUAL-*)
+- Expected glassware trace formats defined for optimal traceability integration
+- Cross-component dependencies properly documented and referenced
+
+**Scaffolding Completeness**:
+- 100% component coverage - every significant component has at least one specification
+- Critical integration points identified and documented
+- Shared concerns extracted into cross-cutting specifications
+- Specification priorities established based on dependency analysis
+
+**Integration Readiness**:
+- Generated specifications ready for `/execute` command implementation
+- Clear requirement traceability paths established
+- Component boundaries and contracts clearly defined
+- Cross-component workflows properly specified
+
+## Success Criteria
+
+✅ **Complete Component Coverage**: Every significant component in workspace has specification structure
+✅ **Hierarchical Organization**: Logical folder structure mirrors codebase architecture  
+✅ **Template Consistency**: All specifications follow generic template standards
+✅ **Integration Documentation**: Cross-component dependencies and contracts specified
+✅ **Implementation Ready**: Generated specifications contain actionable requirements ready for `/execute`
+✅ **Quality Foundation**: Specification quality standards established for workspace
+
+**Result**: Complete workspace specification scaffolding with hierarchical organization, template consistency, and integration documentation ready for systematic implementation via `/execute` commands.

package/commands/review.md

@@ -0,0 +1,151 @@
+---
+version: 2.0.0
+updated: 2026-01-03
+description: Review specification and add traceability comments
+---
+
+# Specification Review & Traceability Agent
+
+Given this specification file: ".mod/specs/<optional-folder>/$ARGUMENTS"
+
+## Branch Context and Specification Setup
+
+**Automatic Branch Detection and Context Gathering:**
+
+**If no specification argument provided:**
+1. **Check active branch** for linked specification:
+   ```bash
+   mod branch status
+   # Should show active branch and linked specification
+   ```
+2. **Error handling** for lightweight branches:
+   ```bash
+   # If current branch has no specification:
+   # > Current branch "fix-auth-timeout" is a lightweight branch with no specification
+   # > Options:
+   # > 1. Link specification: mod branch spec-link <spec-file>
+   # > 2. Create specification branch: mod branch create feature-<name> --spec <spec-file>
+   # > 3. Switch to specification branch: mod branch switch <spec-branch>
+   ```
+
+**If specification argument provided (e.g., `branching-cli.spec.md`):**
+1. **Auto-switch to specification branch**:
+   ```bash
+   # Check if corresponding branch exists
+   mod branch list | grep "feature-.*branching-cli"
+
+   # If exists, switch to it
+   mod branch switch feature-mod-cli-branching-cli
+
+   # If doesn't exist, create it
+   mod branch create feature-mod-cli-branching-cli --spec mod-cli/branching-cli.spec.md
+   ```
+2. **Verify branch setup**:
+   ```bash
+   mod branch status
+   # Should confirm specification branch is active and linked
+   ```
+
+**Review Context Gathering (Automatic):**
+1. **Implementation Progress**: `mod branch status` shows current implementation changes
+2. **Specification Requirements**: `mod status <spec-name>.spec.md` shows requirements and traceability
+3. **Coverage Analysis**: `glassware` shows detailed traceability information
+4. **Code Structure**: Analyzes functions, classes, and existing glassware traces per file
+
+### Trace Writing Instructions
+- Use **glassware annotations** for all traceability
+- Every implementation trace must use: `// glassware[type=implementation, id=unique-id, requirements=REQ-ID]`
+- Add traces directly in the implementation files that satisfy the requirement
+- Do **not** invent requirement IDs; only use ones defined in the provided spec
+- Each implementation must have a unique `id` attribute
+
+## Review Process
+
+**Automated review agent that analyzes implementation against specification:**
+
+1. **Read and parse the complete specification** including all requirements
+2. **Run initial status check**: `glassware` to assess current traceability
+3. **Understand branch changes**: Use `mod branch status` to see what code changes exist on this branch
+4. **Scan all implementation files** in the codebase for related code
+5. **Add missing glassware traces** where implementation matches requirements
+6. **Update specification** where implementation has diverged but makes sense
+7. **Verify progress**: Re-run `glassware` to confirm improvements
+8. **Leave untraced code** that doesn't match any requirements (for IDE flagging)
+
+## Primary Tasks
+
+### 1. Audit Spec Coverage Granularity
+- **Analyze function complexity** using automated detection (lines, conditionals, business logic patterns)
+- **Flag under-specified complex functions** that need line-level traces but only have method-level
+- **Flag over-specified simple functions** that have line-level traces when method-level is appropriate
+- **Verify business logic traceability** - ensure all business logic has detailed line-level traces
+
+### 2. Add Missing Traceability
+- **Scan implementation files** for code that fulfills spec requirements but lacks glassware traces
+- **Add appropriate glassware references** with correct granularity based on complexity analysis
+- **Use confidence thresholds** - only add traces where match is ≥95% certain
+
+### 3. Specification Updates
+- **Identify implementation patterns** that extend beyond original requirements
+- **Update specifications** to include discovered functionality that makes sense (including if implementation means parts of spec are no longer relevant)
+- **Add new sub-requirements** (e.g., BEH-AUTH-1.1a) for legitimate extensions
+- **Document rationale** for each specification update
+
+### 4. Flag Non-Compliant Code
+- **Leave code without glassware traces** when it doesn't match any requirement
+- **Identify implementation gaps** where spec requirements have no code
+- **Report architectural violations** where code contradicts spec patterns
+
+## Output Actions
+
+**File Updates:**
+- **Implementation files**: Add glassware traces with appropriate granularity where code matches requirements
+- **Specification files**: Update specs to reflect legitimate implementation extensions
+- **Summary report**: List of granularity improvements, changes made, and issues flagged
+
+**Quality Standards:**
+- **Appropriate Granularity**: Apply method-level traces to simple functions, line-level to complex functions
+- **Business Logic Priority**: Always ensure business logic has detailed line-level traceability
+- **Conservative tracing**: Only add glassware traces with high confidence
+- **Sensible spec updates**: Only update specs for logical extensions, not violations
+- **Clear flagging**: Leave obvious gaps and violations untraced for developer attention
+
+### Spec Granularity Review Rules
+**For each function, assess current glassware traces:**
+
+1. **Count Current Traces**:
+   - 1 glassware comment = method-level coverage
+   - 2+ glassware comments = line-level coverage
+
+2. **Apply Complexity Rules**:
+   - **Business Logic** (validate/auth/pay/charge/encrypt/save/persist): MUST have line-level traces
+   - **Complex Functions** (>10 lines OR conditionals): SHOULD have line-level traces
+   - **Simple Functions** (≤10 lines, no conditionals): Method-level traces OK
+
+3. **Review Actions**:
+   - **Under-specified**: Complex function with only method-level trace → Add line-level traces
+   - **Over-specified**: Simple function with line-level traces → Consider consolidating to method-level
+   - **Missing Business Logic**: Business function without detailed traces → Flag as critical gap
+
+### Glassware Format Reference
+
+**In Markdown specs (requirements):**
+```markdown
+The system must validate user credentials. <glassware type="requirement" id="REQ-AUTH-1" />
+```
+
+**In TypeScript (implementations):**
+```typescript
+// glassware[type=implementation, id=auth-login, requirements=REQ-AUTH-1]
+export function login(email: string, password: string) { ... }
+```
+
+## Review Completion Validation
+
+**Before completing review, run final verification:**
+- Execute `glassware` to verify improved traceability coverage
+- Use `mod branch status` to verify what code changes exist on branch
+- Ensure all requirements show as "implemented" when code is properly traced
+- Document coverage improvements achieved
+
+**Result**: Complete bidirectional traceability with updated specifications that reflect actual implementation while flagging non-compliant code.