feat: add side-effect taxonomy, data models, and file discovery

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ on:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
 
 permissions:
   contents: read

.gitignore

@@ -45,6 +45,7 @@ htmlcov/
 .cache
 nosetests.xml
 coverage.xml
+coverage.json
 *.cover
 *.py.cover
 .hypothesis/

.opencode/commands/uf.finale.md

@@ -54,13 +54,13 @@ step. This checklist survives context compression and
 serves as the source of truth for workflow state.
 
 ```
-BRANCH=<set when known>
+BRANCH=opsx/taxonomy-and-discovery
 COMMIT=<set when known>
 PR_NUMBER=<set when known>
 PR_URL=<set when known>
 CONFLICT_OPTION=<set when known>
 
-[ ] Step 1 — Branch Safety Gate
+[x] Step 1 — Branch Safety Gate
 [ ] Step 2 — Check for Changes to Commit
 [ ] Step 3 — Generate and Confirm Commit Message
 [ ] Step 4 — Push to Remote

.opencode/commands/uf.review-council.md

@@ -21,21 +21,21 @@ description: Run the reviewer governance council to audit codebase or spec compl
 > **EXECUTION CHECKLIST** — Update each item using the
 > Edit tool as you complete it. Mark `[x]` when done.
 >
-> - [ ] Phase 1a: Pre-flight checks
-> - [ ] Phase 1b: Gaze quality analysis
-> - [ ] Phase 1c: Review context discovery
-> - [ ] Step 2: Divisor agent delegation (full branch diff)
-> - [ ] Step 3: Finding consolidation
-> - [ ] Step 4: Fix loop (iteration: _/3)
-> - [ ] Step 5: Iteration limit check
-> - [ ] Step 6: Final report
-> - [ ] Step 7a: PR detection
-> - [ ] Step 7b: Review state fetching
-> - [ ] Step 7c: Pre-posting checks
-> - [ ] Step 7d: Finding aggregation
-> - [ ] Step 7e: Inline comment preparation
-> - [ ] Step 7f: Human confirmation (MANDATORY GATE)
-> - [ ] Step 7g: Post review
+> - [x] Phase 1a: Pre-flight checks
+> - [x] Phase 1b: Gaze quality analysis
+> - [x] Phase 1c: Review context discovery
+> - [x] Step 2: Divisor agent delegation (full branch diff)
+> - [x] Step 3: Finding consolidation
+> - [x] Step 4: Fix loop (iteration: 1/3)
+> - [x] Step 5: Iteration limit check
+> - [x] Step 6: Final report
+> - [x] Step 7a: PR detection — no open PR found, skipping 7b-7g
+> - [ ] Step 7b: Review state fetching (skipped)
+> - [ ] Step 7c: Pre-posting checks (skipped)
+> - [ ] Step 7d: Finding aggregation (skipped)
+> - [ ] Step 7e: Inline comment preparation (skipped)
+> - [ ] Step 7f: Human confirmation (MANDATORY GATE) (skipped)
+> - [ ] Step 7g: Post review (skipped)
 
 
 ## User Input

.specify/memory/constitution.md

@@ -1,5 +1,46 @@
+<!--
+SYNC IMPACT REPORT
+Version change: 1.0.0 → 1.1.0
+Amendment date: 2026-08-27
+Feature: Constitution alignment with org patterns
+
+Added sections:
+- parent_constitution declaration (org v1.2.0)
+- Principle V: Analysis Safety (new principle)
+- Determinism MUST rules under Principle I
+- Protocol version pin (v1.1.0) in upgraded Upstream Alignment
+- Conflict Resolution clause in Governance
+- Org supremacy clause in Governance
+- This Sync Impact Report
+
+Modified sections:
+- Principle I: Protocol Fidelity (added determinism rules)
+- Governance: Upstream Alignment (upgraded with version pin
+  and conformance-suite requirement)
+
+Unchanged sections:
+- Principle II: Detection Accuracy
+- Principle III: Python-Native Analysis
+- Principle IV: Testability
+- Development Workflow
+
+Org alignment check: ALIGNED
+- All five existing principles are compatible with org v1.2.0
+- Principle V: Analysis Safety derives from org Principle V
+  (Security by Default) adapted for static analysis context
+
+Template compatibility: constitution v1 template
+
+Version history:
+- 1.0.0 (2026-05-17): Initial ratification. Four principles
+  (Protocol Fidelity, Detection Accuracy, Python-Native
+  Analysis, Testability). Upstream Alignment clause.
+-->
+
 # Snake Eyes Constitution
 
+**parent_constitution**: unbound-force/unbound-force v1.2.0
+
 ## Core Principles
 
 ### I. Protocol Fidelity
@@ -17,6 +58,12 @@ every language analyzer -- deviations break the platform.
 - When the protocol evolves (new methods, new fields),
   Snake Eyes MUST maintain backward compatibility with
   older Gaze versions through capability negotiation.
+- Analysis of the same input tree with the same Snake Eyes
+  version and the same protocol version MUST produce
+  byte-identical JSON-RPC output. Responses MUST NOT
+  contain timestamps, random values, hostnames, or any
+  other environment-dependent data. JSON serialization
+  MUST be deterministic (stable key ordering).
 
 **Rationale**: Snake Eyes is not a standalone tool. It is
 one half of a two-process system. If the protocol contract
@@ -103,6 +150,36 @@ a practical necessity: the JSON-RPC boundary provides a
 clean seam for integration testing without requiring a
 running Gaze process.
 
+### V. Analysis Safety
+
+Snake Eyes analyzes arbitrary Python codebases. Analyzed
+source code is untrusted input and MUST be treated as such.
+
+- Analysis MUST be strictly static. Snake Eyes MUST NOT
+  execute, import, or otherwise run analyzed code. All
+  inspection MUST use parse-level tools (`ast.parse`,
+  `symtable.symtable`, Astroid's AST inference) that do
+  not trigger code execution.
+- Inputs MUST be validated and bounded. File paths MUST be
+  resolved and checked for traversal. Resource limits
+  (file size, AST depth, recursion budget) MUST prevent
+  analyzed code from causing denial of service.
+- Every dependency is attack surface. The default answer
+  to adding a dependency is "do not add." Current
+  dependencies (astroid, radon, coverage.py) are justified
+  as established, maintained libraries that provide
+  capabilities impractical to reimplement. New dependencies
+  MUST be justified against this standard.
+- CI actions MUST be pinned by commit SHA, not by mutable
+  tag. Supply-chain integrity is a structural property,
+  not a per-change review item.
+
+**Rationale**: Snake Eyes runs in developer and CI
+environments on codebases it does not control. A
+compromised or malicious project must not achieve code
+execution through the analyzer. Static-only analysis is
+not a limitation -- it is the security boundary.
+
 ## Development Workflow
 
 - **Spec-First Development**: All changes that modify
@@ -136,6 +213,11 @@ running Gaze process.
 
 ## Governance
 
+This constitution extends the unbound-force org constitution
+(v1.2.0). On matters where this document and the org
+constitution conflict, the org constitution prevails and
+this constitution MUST be amended to resolve the conflict.
+
 This constitution is the highest-authority document for the
 Snake Eyes project. All development practices, pull request
 reviews, and architectural decisions MUST be consistent with
@@ -155,9 +237,18 @@ the principles defined above.
   plan, tasks), the Constitution Check gate MUST verify
   that the proposed work aligns with all active principles.
 - **Upstream Alignment**: This constitution is subordinate
-  to Gaze's analyzer protocol specification. If a
-  constitutional principle conflicts with the protocol
-  spec, the protocol spec takes precedence and the
-  constitution MUST be amended.
-
-**Version**: 1.0.0 | **Ratified**: 2026-05-17 | **Last Amended**: 2026-05-17
+  to Gaze's analyzer protocol specification. Snake Eyes
+  implements **protocol v1.1.0** (defined at
+  `unbound-force/gaze/docs/protocol.md`). Protocol
+  conformance MUST be verified by an automated conformance
+  suite (canned request/response pairs validated against
+  the protocol schema). When Gaze bumps the protocol
+  version, Snake Eyes MUST open an alignment issue within
+  one release cycle.
+- **Conflict Resolution**: When two principles appear to
+  conflict in a specific scenario, the tradeoff MUST be
+  explicitly documented in the relevant spec or plan. No
+  principle has implicit priority over another; resolution
+  is context-dependent and requires written justification.
+
+**Version**: 1.1.0 | **Ratified**: 2026-05-17 | **Last Amended**: 2026-08-27

AGENTS.md

@@ -18,6 +18,33 @@ when analyzing Python projects.
 - **Parent project**: [Gaze](https://github.com/unbound-force/gaze) (unbound-force)
 - **Organization**: [zero-dot-force](https://github.com/zero-dot-force) (labs incubator for unbound-force)
 
+## Constitution (Highest Authority)
+
+The Snake Eyes constitution
+(`.specify/memory/constitution.md`) is the highest-authority
+document for this project. It extends the unbound-force org
+constitution (v1.2.0) and pins Gaze protocol v1.1.0.
+Constitution violations are CRITICAL severity and
+non-negotiable.
+
+**Five principles:**
+
+1. **Protocol Fidelity** -- implement the Gaze analyzer
+   protocol precisely; deterministic output; deviations are
+   bugs
+2. **Detection Accuracy** -- correctly identify all
+   observable side effects; ambiguity over omission; false
+   positives and false negatives are bugs
+3. **Python-Native Analysis** -- use Python's own parsing
+   infrastructure (ast, symtable, astroid); do not
+   reimplement Python semantics
+4. **Testability** -- every function testable in isolation;
+   coverage strategy required in every spec; protocol
+   conformance suites required
+5. **Analysis Safety** -- analyzed source is untrusted
+   input; static analysis only; never execute analyzed
+   code; dependency necessity justified
+
 ## Architecture
 
 Snake Eyes is a JSON-RPC server that Gaze spawns as a
@@ -45,11 +72,11 @@ subprocess. The division of responsibility:
   AST analysis
 - **Scope analysis**: Python `symtable` module (stdlib) for
   global/nonlocal detection
-- **Inference**: [Astroid](https://github.com/pylint-dev/astroid)
+- **Inference** (planned): [Astroid](https://github.com/pylint-dev/astroid)
   for name resolution, type inference, cross-module imports
-- **Complexity**: [radon](https://github.com/rubik/radon)
+- **Complexity** (planned): [radon](https://github.com/rubik/radon)
   for cyclomatic complexity
-- **Coverage**: [coverage.py](https://github.com/nedbat/coveragepy)
+- **Coverage** (planned): [coverage.py](https://github.com/nedbat/coveragepy)
   for parsing coverage data
 - **Project management**: [uv](https://docs.astral.sh/uv/)
 - **Testing**: [pytest](https://docs.pytest.org/)
@@ -62,7 +89,12 @@ snake-eyes/
 │   ├── __init__.py
 │   ├── __main__.py          # Entry point (snake-eyes --stdio)
 │   ├── server.py            # JSON-RPC server (stdin/stdout)
-│   └── protocol.py          # Request/response types
+│   ├── protocol.py          # Request/response types
+│   ├── discovery.py         # File discovery (os.walk)
+│   └── analysis/
+│       ├── __init__.py
+│       ├── effects.py       # 48-type SideEffectType taxonomy
+│       └── models.py        # Effect / FunctionRecord data models
 ├── tests/
 ├── .github/workflows/       # CI: ruff, mypy, pytest gates
 ├── pyproject.toml
@@ -71,33 +103,39 @@ snake-eyes/
 ├── LICENSE
 └── NOTICE
 ```
-Planned later: `discovery.py`, `analysis/`, `complexity.py`, `coverage.py` (issues #3–#6).
+Planned later: `complexity.py`, `coverage.py` (issues #5–#6).
 
 ## Shell Commands
 
+Commands are derived from `.github/workflows/ci.yml`.
+Do not rely on memory -- check the workflow file for the
+current gates.
+
 ```bash
-# Install dependencies
-uv sync
+# Install dependencies (CI uses --locked)
+uv sync --locked
 
-# Run tests
-uv run pytest
+# Linting
+uv run ruff check src/ tests/
 
-# Run tests with coverage
-uv run pytest --cov=snake_eyes --cov-report=term-missing
+# Format check (CI runs --check, not auto-format)
+uv run ruff format --check src/ tests/
 
 # Type checking
 uv run mypy src/
 
-# Linting
-uv run ruff check src/ tests/
-
-# Formatting
-uv run ruff format src/ tests/
+# Run tests with coverage (85% is the protected gate)
+uv run pytest --cov=snake_eyes --cov-report=term-missing --cov-fail-under=85
 
 # Run snake-eyes in stdio mode (for testing with gaze)
 uv run snake-eyes --stdio
 ```
 
+**Protected gates** (agents MUST NOT lower these):
+- `--cov-fail-under=85` -- minimum coverage percentage
+- `ruff format --check` -- formatting must pass, not auto-fix
+- `uv sync --locked` -- lockfile integrity
+
 ## Core Mission
 
 - **Protocol fidelity**: Snake Eyes implements Gaze's
@@ -165,9 +203,56 @@ Agents MUST NOT cross workflow phase boundaries:
   agents MUST run the same checks CI runs. Derive commands
   from workflow files, not memory.
 
+## Spec Organization
+
+Snake Eyes uses two spec pipelines. Choose based on scope:
+
+| Criterion | Speckit (`specs/NNN-*/`) | OpenSpec (`openspec/changes/`) |
+|---|---|---|
+| **Scope** | Strategic: ≥3 tasks or cross-cutting | Tactical: 1–2 tasks, focused |
+| **Artifacts** | spec, plan, tasks, checklists | proposal, design, tasks |
+| **When to use** | New analysis capabilities, protocol changes, architecture | Bug fixes, small features, docs |
+| **Example** | `specs/001-jsonrpc-prototype/` | `openspec/changes/fix-parse-error/` |
+
+**Ordering constraints**: spec artifacts MUST be committed
+before implementation begins. Implementation commits MUST
+NOT be in the same commit as spec changes.
+
+**Task Completion Bookkeeping**: When completing a task
+from a tasks file, mark the checkbox `- [x]` immediately
+-- not in a batch at the end.
+
+## Workflow Gates
+
+### Constitution Check
+
+Before implementation, verify alignment with all five
+constitution principles. The check MUST name each principle
+and give a PASS/FAIL verdict:
+
+1. Protocol Fidelity
+2. Detection Accuracy
+3. Python-Native Analysis
+4. Testability
+5. Analysis Safety
+
+### Review Council Gate
+
+Run `uf.review-council` before creating a PR. All
+reviewers MUST APPROVE before the PR is eligible for
+merge. Exempt: constitution amendments, docs-only changes,
+emergency hotfixes.
+
+### CI Parity Gate
+
+Before marking any task complete, agents MUST run the same
+checks CI runs. Derive commands from
+`.github/workflows/ci.yml`, not from memory.
+
 <!-- SPECKIT START -->
 For additional context about technologies to be used, project structure,
 shell commands, and other important information, read the current plan
+under `specs/` or `openspec/changes/`.
 <!-- SPECKIT END -->
 
 ## Convention Packs
@@ -181,3 +266,7 @@ before writing or reviewing code.
 - `.opencode/uf/packs/severity.md`
 - `.opencode/uf/packs/content.md`
 - `.opencode/uf/packs/content-custom.md`
+- `.opencode/uf/packs/python.md`
+- `.opencode/uf/packs/python-custom.md`
+- `.opencode/uf/packs/ci.md`
+- `.opencode/uf/packs/ci-custom.md`