codecartographer-pi 0.1.0

package/.codecarto/findings/architecture/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: map-project-architecture
+description: Map a repository into layers, package boundaries, entrypoints, dependency direction, and shared abstractions. Use when you need to understand an unfamiliar codebase before porting, auditing, decomposing, or reimplementing it in another language, especially for monorepos, CLIs, SDKs, and multi-surface products.
+---
+
+# Map Project Architecture
+
+Build the map before analyzing implementation details.
+
+Read the structural sources first:
+- Root README and contribution docs.
+- Root package/workspace manifest and top-level scripts.
+- Package or module READMEs.
+- Package manifests, `bin` entries, `exports`, and top-level entrypoints.
+
+For a monorepo, create a package inventory with these columns:
+- package or module name
+- purpose
+- public entrypoints
+- key dependencies
+- runtime surface
+- likely ownership category
+
+Classify each package or major module into one primary role:
+- `core semantics`
+- `protocol or normalization layer`
+- `persistence or state`
+- `UI or rendering`
+- `integration adapter`
+- `product shell`
+
+Trace dependency direction instead of reading everything in file order:
+- Identify what depends on what.
+- Find the lowest stable layer that nothing inside the repo depends on.
+- Call out cycles explicitly.
+- Mark packages that are wrappers around shared internals rather than unique systems.
+
+Identify public surfaces early:
+- binaries and CLI commands
+- exported libraries and public types
+- network or RPC interfaces
+- file formats and persistent artifacts
+- user-facing screens or workflows
+
+Record the project's durable state:
+- config files
+- environment variables
+- auth material
+- session files
+- logs
+- caches
+- databases
+- generated artifacts
+
+Treat third-party SDKs as shaping forces, not architecture:
+- Note where vendor APIs, terminal behavior, Slack, browser APIs, or cloud services impose constraints.
+- Do not let those constraints define the port's module boundaries unless the behavior truly depends on them.
+
+Document the build and packaging pipeline:
+- Build tool(s) and scripts (make, npm, cargo, gradle, etc.).
+- Multi-target or multi-stage builds.
+- Output artifacts: binaries, containers, packages, bundles.
+- CI/CD pipeline if visible from repo files (.github/workflows, Jenkinsfile, etc.).
+- Platform-specific packaging or distribution.
+- If the build pipeline is complex, use the secondary output at `findings/build-and-deploy/build-and-deploy.md`.
+
+Document the concurrency model:
+- Threading model: single-threaded, thread pool, async/await, actor model, goroutines, etc.
+- Event loop or reactor pattern, if present.
+- Shared state and synchronization primitives.
+- Connection pooling and resource management.
+- Rate limiting or backpressure mechanisms.
+- Mark concurrency-related portability hazards explicitly — these rarely translate 1:1 across languages.
+
+Write the output in seven sections:
+1. `System intent`
+2. `Layer map`
+3. `Public surfaces`
+4. `Runtime lifecycle`
+5. `Concurrency model`
+6. `Build and packaging`
+7. `Porting priorities`
+
+Mark every conclusion with one of these evidence levels:
+- `observed fact`: direct statement from docs, tests, schemas, types, or code.
+- `strong inference`: architectural conclusion drawn from multiple facts.
+- `portability hazard`: assumption tied to the source language, runtime, terminal, OS, or third-party SDKs.
+- `open question`: missing or conflicting behavior that still needs evidence.
+
+Test for common structural patterns:
+- shared provider or protocol layer
+- shared stateful agent or execution loop
+- multiple delivery surfaces on top
+- product-specific wrappers around a shared core
+- plugin or extension architecture
+- microservice or monorepo with service boundaries
+
+Stop once the map is stable enough to explain where behavior lives. Only then move to contracts, protocols, or deep source reading.
+
+Use the output template at `templates/architecture-map.md`.
+
+The source code to analyze is in the parent directory (`../` relative to `.codecarto/`). This is the repository root.

package/.codecarto/findings/contracts/README.md

@@ -0,0 +1,3 @@
+# Contracts Findings
+
+User-visible behavior, commands, configuration semantics, defaults, edge cases, and acceptance checks.

package/.codecarto/findings/contracts/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: extract-behavioral-contracts
+description: Recover user-visible behavior, commands, configuration semantics, defaults, error expectations, and feature contracts from docs, tests, examples, and code. Use when you need a language-agnostic behavior spec for later reimplementation, parity planning, or regression testing.
+---
+
+# Extract Behavioral Contracts
+
+Recover what the system does from the outside in.
+
+Prioritize sources in this order:
+1. READMEs, docs, and built-in help text
+2. examples, demos, screenshots, sample sessions
+3. tests and fixtures
+4. schemas, default settings, and changelogs
+5. source code for gaps and contradictions
+
+Split the analysis by user-facing surface:
+- CLI
+- TUI
+- web UI
+- API or SDK
+- bot or background worker
+- storage or export formats
+
+For each feature, capture a contract with these fields:
+- `feature`
+- `trigger or input`
+- `defaults`
+- `observable output`
+- `side effects`
+- `persisted state`
+- `error behavior`
+- `retry or recovery behavior`
+
+Treat tests as executable contracts:
+- Prefer them for edge cases, ordering, and failure handling.
+- Compare them against docs to detect drift.
+- Call out any doc/test conflict instead of silently picking one.
+
+Separate essential behavior from source-specific ergonomics:
+- Preserve user-visible semantics.
+- Do not overfit to exact class names, file names, or UI implementation tricks.
+- Keep keyboard shortcuts, command aliases, or display details only if they matter to parity.
+
+Pay special attention to these high-value behaviors:
+- cancellation and abort handling
+- streaming and partial output
+- queueing or follow-up behavior
+- compaction and summarization
+- persistence and resume flows
+- tool execution and validation
+
+Document the security and authorization model (if the system has one):
+- Authentication method(s): OAuth, API keys, session tokens, SSO, etc.
+- Authorization model: RBAC, ABAC, ACLs, capability-based, etc.
+- Trust boundaries: what input is trusted vs untrusted.
+- Permission checks: how and where permissions are enforced.
+- Secret management: how tokens, keys, and credentials are stored and rotated.
+- Session lifecycle: expiration, refresh, invalidation.
+- Skip this area entirely if the system has no auth model (e.g., a pure library).
+
+Document the configuration model:
+- Config sources and their precedence (env vars > config file > defaults, etc.).
+- Config file format, location, and discovery mechanism.
+- Feature flags and how they are toggled.
+- Environment-specific overrides (dev, staging, prod).
+- Config validation and error handling for malformed config.
+- If the config model is complex, use the secondary output at `findings/config-model/config-model.md`.
+
+Map every contract back to its owner:
+- package or module
+- shared core vs surface wrapper
+- platform-specific adapter, if any
+
+End with a black-box acceptance list:
+- Write scenario-style checks that another implementation can run without referencing the source.
+- Favor exact preconditions and expected outcomes over vague quality statements.
+
+Mark every finding with one of these evidence levels:
+- `observed fact`: direct statement from docs, tests, schemas, types, or code.
+- `strong inference`: behavioral conclusion drawn from multiple facts.
+- `portability hazard`: assumption tied to the source language, runtime, terminal, OS, or third-party SDKs.
+- `open question`: missing or conflicting behavior that still needs evidence.
+
+If behavior is hard to infer from docs alone, read the companion protocol skill next. Many user-visible quirks are really protocol or state-machine rules.
+
+Use the output template at `templates/behavioral-contracts.md`.
+
+The source code to analyze is in the parent directory (`../` relative to `.codecarto/`). This is the repository root.

package/.codecarto/findings/defect-scan/README.md

@@ -0,0 +1,18 @@
+# Defect Scan
+
+Multi-pass analysis of the source codebase for logic errors, error handling gaps, concurrency issues, security vulnerabilities, API contract violations, and configuration hazards.
+
+**Primary output:** `defect-report.md`
+
+**Depends on:** architecture phase (required). Optionally leverages contracts and protocols phases for spec-grounded analysis.
+
+**Analysis passes** (executed sequentially):
+
+1. Logic and correctness
+2. Error handling and resilience
+3. Concurrency and resource management
+4. Security and trust boundaries
+5. API contract violations
+6. Configuration and environment hazards
+
+See `SKILL.md` for full instructions. Pass-specific guidance is in `passes/`.

package/.codecarto/findings/defect-scan/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: scan-for-defects
+description: Run a multi-pass defect scan across the source codebase, checking for logic errors, error handling gaps, concurrency bugs, security issues, API contract violations, and configuration hazards. Use after the architecture phase is complete. Optionally leverages contracts and protocols outputs for spec-grounded analysis.
+---
+
+# Scan For Defects
+
+This phase runs **six sequential analysis passes**, each focused on one category of defect. Read and execute the passes in the order listed below. Do not try to cover all categories at once — complete each pass before starting the next.
+
+The source code to analyze is in the parent directory (`../` relative to `.codecarto/`). This is the repository root.
+
+## Prerequisites
+
+**Required:** Read `findings/architecture/architecture-map.md` before starting. You need the layer map, public surfaces, and concurrency model to know where to focus.
+
+**Optional but valuable:** If the following files exist, read them before starting passes 5 and 4 respectively. They provide the behavioral spec to compare code against:
+- `findings/contracts/behavioral-contracts.md` — enables spec-grounded analysis in passes 4 and 5.
+- `findings/protocols/protocols-and-state.md` — enables state machine violation detection in pass 5.
+
+If these files do not exist, the passes still work — they fall back to comparing code against its own documentation (docstrings, type signatures, comments, README).
+
+## Pass Execution Order
+
+Run these passes sequentially. Read the pass file, scan the source, record findings, then move to the next pass.
+
+| Pass | File | Focus |
+|------|------|-------|
+| 1 | `findings/defect-scan/passes/01-logic-and-correctness.md` | Dead code, boundary errors, null handling, boolean logic, control flow |
+| 2 | `findings/defect-scan/passes/02-error-handling.md` | Swallowed errors, missing cleanup, uncaught exceptions, retry gaps |
+| 3 | `findings/defect-scan/passes/03-concurrency-and-resources.md` | Race conditions, lock issues, async pitfalls, resource leaks |
+| 4 | `findings/defect-scan/passes/04-security-and-trust.md` | Input validation, auth gaps, secrets in code, trust boundaries |
+| 5 | `findings/defect-scan/passes/05-api-contract-violations.md` | Spec vs. implementation drift, return type mismatches, state machine violations |
+| 6 | `findings/defect-scan/passes/06-config-and-environment.md` | Hardcoded values, missing validation, dangerous defaults, OS assumptions |
+
+## Prioritization
+
+Not every pass applies to every codebase. Use the architecture map to decide emphasis:
+- **No concurrency model?** Skim pass 3, focus elsewhere.
+- **No auth system?** Skip the auth sections of pass 4, still check input validation.
+- **Pure library with no config?** Skim pass 6.
+- **Heavy protocol/state machine system?** Spend extra time on pass 5.
+
+## Evidence Classification
+
+Mark every finding with one of these evidence levels:
+- `observed fact`: the defect is directly visible in the code.
+- `strong inference`: the defect is highly likely based on multiple code observations.
+- `open question`: the code is suspicious but would need runtime testing to confirm.
+
+## Severity Classification
+
+Assign one severity per finding:
+- `critical`: causes wrong results, data loss, or security exposure in normal operation.
+- `high`: causes wrong results or failures in edge cases or under specific conditions.
+- `medium`: latent risk, dead code, defense-in-depth gap, or poor error handling.
+- `low`: style issue with correctness implications, stale docs, or minor inconsistency.
+
+## Action Classification
+
+Tag each finding with a recommended action. Use the set that matches your pipeline:
+
+**Pre-porting pipelines** (full-with-audit, full-with-deep-audit):
+- `fix before porting`: the defect would carry into a new implementation if not addressed first.
+- `port differently`: the new implementation should handle this case differently by design.
+- `leave behind`: the defect is specific to the source implementation and won't survive porting.
+
+**Maintenance pipelines** (defect-scan):
+- `fix now`: the defect is actively causing or risking problems.
+- `track`: the defect is real but low-urgency; add to backlog.
+- `accept`: the defect is known and the team has decided to live with it.
+- `investigate`: needs runtime testing or deeper analysis to confirm.
+
+Determine which action set to use by checking the `pipeline` field in `workflow/status.yaml`.
+
+## Output
+
+Write findings to the primary output using the template at `templates/defect-report.md`.
+
+Organize findings by pass (one section per pass), then by severity within each section.
+
+End with a summary table counting findings by severity and category, and a prioritized list of the top findings across all passes.
+
+Use the output template at `templates/defect-report.md`.
+
+## Fix Tracking
+
+After the defect report is complete, a fix tracker template is available at `templates/defect-fix-tracker.md`. Use it to track remediation progress when fixing the defects found in this scan. The tracker uses the same defect IDs from the report (D{pass}.{number}) so fixes map directly back to findings.

package/.codecarto/findings/defect-scan/passes/01-logic-and-correctness.md

@@ -0,0 +1,50 @@
+# Pass 1: Logic and Correctness
+
+Scan for structural logic defects that produce wrong results, unreachable behavior, or silent failures.
+
+## What to look for
+
+**Dead and unreachable code:**
+- Functions or branches that no call path reaches.
+- Feature flags or config gates that are always true/false.
+- Catch blocks or error handlers for exceptions that are never thrown.
+- Enum values or switch cases that are defined but never matched.
+
+**Off-by-one and boundary errors:**
+- Loop bounds that skip the first or last element.
+- Slice/substring ranges that are off by one.
+- Comparison operators that should be `<=` instead of `<` (or vice versa).
+- Array/index access without bounds checking.
+
+**Null, undefined, and type coercion hazards:**
+- Variables used before assignment or after conditional nulling.
+- Optional values unwrapped without a nil/null check.
+- Implicit type coercion that changes behavior (e.g., string-to-number, falsy values).
+- Functions that sometimes return a value and sometimes return nothing.
+
+**Boolean and conditional logic:**
+- Conditions that are always true or always false.
+- Negation errors (e.g., `!a || !b` vs `!(a && b)` misuse).
+- Short-circuit evaluation that skips necessary side effects.
+- Nested conditionals where branches overlap or have gaps.
+
+**Return and control flow:**
+- Missing return statements in branches.
+- Early returns that skip cleanup or finalization.
+- Fall-through in switch/match without explicit intent.
+- Functions with inconsistent return types across branches.
+
+## How to report
+
+For each finding, record:
+- **Location**: file path and function/method name.
+- **Defect**: what is wrong, in one sentence.
+- **Evidence**: what you observed that proves or strongly suggests the defect.
+- **Severity**: critical (incorrect results in normal use), high (incorrect results in edge cases), medium (dead code or latent risk), low (style issue with correctness implications).
+- **Evidence level**: observed fact / strong inference / open question.
+
+## What to skip
+
+- Style preferences (naming, formatting, comment density).
+- Performance concerns (covered in other passes).
+- Anything that requires runtime testing to confirm — mark those as open questions instead.

package/.codecarto/findings/defect-scan/passes/02-error-handling.md

@@ -0,0 +1,55 @@
+# Pass 2: Error Handling and Resilience
+
+Scan for gaps in how the system detects, propagates, and recovers from errors.
+
+## What to look for
+
+**Swallowed errors:**
+- Empty catch/except blocks.
+- Catch blocks that log but don't re-raise or propagate.
+- Error callbacks that are registered but do nothing.
+- Promise/future chains with missing `.catch` or error handlers.
+
+**Inconsistent error propagation:**
+- Functions that throw in some error paths but return error codes in others.
+- Mixed error strategies within the same module (exceptions vs. result types vs. error codes).
+- Error types that lose context when re-wrapped (original cause discarded).
+- Errors that silently convert to default values instead of surfacing.
+
+**Missing cleanup in error paths:**
+- Resources (files, connections, locks) opened before a try block but not closed in the finally/error path.
+- Temporary state mutations that aren't rolled back on failure.
+- Partial writes that leave data in an inconsistent state.
+- Transaction-like operations without rollback on failure.
+
+**Uncaught exception paths:**
+- Async operations without error handlers.
+- Background tasks or worker threads with no top-level catch.
+- Event handlers that can throw but aren't wrapped.
+- Constructors or init methods that throw without cleanup.
+
+**Retry and recovery gaps:**
+- Network or I/O operations with no retry logic where transient failures are expected.
+- Retry loops with no backoff, no jitter, or no max-attempts cap.
+- Recovery paths that retry the exact same operation without fixing the underlying condition.
+- Circuit breaker patterns that are partially implemented (open state but no half-open recovery).
+
+**Error reporting and observability:**
+- Errors that are caught but not logged anywhere.
+- Log messages that omit the error type, message, or stack trace.
+- Errors that surface to users as generic "something went wrong" without actionable detail.
+- Health checks or monitoring that don't cover known failure modes.
+
+## How to report
+
+For each finding, record:
+- **Location**: file path and function/method name.
+- **Defect**: what error scenario is mishandled.
+- **Evidence**: the specific code pattern or path that demonstrates the gap.
+- **Severity**: critical (data loss or corruption on failure), high (silent failure in normal operations), medium (poor error messages or missing cleanup), low (observability gap).
+- **Evidence level**: observed fact / strong inference / open question.
+
+## What to skip
+
+- Error handling style preferences (exceptions vs. result types) — unless the inconsistency within a module creates actual bugs.
+- Logging format choices — unless errors are genuinely unobservable.

package/.codecarto/findings/defect-scan/passes/03-concurrency-and-resources.md

@@ -0,0 +1,54 @@
+# Pass 3: Concurrency and Resource Management
+
+Scan for race conditions, synchronization gaps, and resource leaks.
+
+Read the concurrency model section from `findings/architecture/architecture-map.md` first to understand the system's threading model, async patterns, and synchronization approach.
+
+## What to look for
+
+**Race conditions and data races:**
+- Shared mutable state accessed from multiple threads/goroutines/tasks without synchronization.
+- Read-modify-write sequences that aren't atomic.
+- Check-then-act patterns where the condition can change between the check and the action.
+- Event handlers that mutate shared state without coordination.
+- Counters or accumulators updated from concurrent contexts without atomic operations.
+
+**Lock and synchronization issues:**
+- Lock acquisition order that differs across call sites (deadlock risk).
+- Locks held across I/O operations or await points (starvation risk).
+- Missing locks on data structures documented as shared.
+- Locks that protect the wrong scope (too narrow or too broad).
+
+**Async and event-loop pitfalls:**
+- Blocking calls inside async functions (blocking the event loop).
+- `await` on operations that can hang indefinitely without timeout.
+- Fire-and-forget async operations with no error handling.
+- Callback-based APIs mixed with promise/async-await without proper bridging.
+- Unbounded task/goroutine spawning without backpressure.
+
+**Resource leaks:**
+- File handles, sockets, or database connections opened without corresponding close.
+- Resources acquired in constructors but not released in destructors/finalizers.
+- Connection pools that grow without bounds or don't return connections on error.
+- Temporary files created but not cleaned up on exit or failure.
+- Event listeners or subscriptions registered but never unregistered.
+
+**Timeout and cancellation:**
+- Network or I/O operations with no timeout.
+- Long-running operations with no cancellation mechanism.
+- Cancellation tokens or contexts that are passed through but never checked.
+- Graceful shutdown paths that don't drain in-flight work.
+
+## How to report
+
+For each finding, record:
+- **Location**: file path and function/method name.
+- **Defect**: what concurrent or resource scenario is mishandled.
+- **Evidence**: the specific shared state, missing synchronization, or unclosed resource.
+- **Severity**: critical (data corruption or deadlock in normal operation), high (race condition in common paths), medium (resource leak under error conditions), low (theoretical race in rarely-exercised path).
+- **Evidence level**: observed fact / strong inference / open question.
+
+## What to skip
+
+- Single-threaded code with no async — this pass is irrelevant if the architecture has no concurrency.
+- Performance-only concerns (slow locks, suboptimal pool sizes) — unless they cause correctness issues.

package/.codecarto/findings/defect-scan/passes/04-security-and-trust.md

@@ -0,0 +1,62 @@
+# Pass 4: Security and Trust Boundaries
+
+Scan for vulnerabilities in input validation, authentication, authorization, secret handling, and trust boundary enforcement.
+
+If `findings/contracts/behavioral-contracts.md` exists, read the Security and Authorization section first — it documents the intended auth model. Compare what you find in code against what the contracts say should happen.
+
+## What to look for
+
+**Input validation gaps:**
+- User input passed to database queries, shell commands, file paths, or template engines without sanitization.
+- Missing length limits on string inputs (buffer-adjacent risks, DoS vectors).
+- File upload paths without extension/type/size validation.
+- URL or redirect parameters that accept arbitrary destinations (open redirect).
+- Deserialization of untrusted input without schema validation.
+
+**Authentication weaknesses:**
+- Endpoints or functions that should require authentication but don't check.
+- Token validation that checks expiry but not signature (or vice versa).
+- Password comparison using non-constant-time equality.
+- Session tokens with insufficient entropy or predictable generation.
+- Auth bypass via parameter manipulation (e.g., changing user ID in request).
+
+**Authorization gaps:**
+- Actions that check "is user logged in" but not "is user allowed to do this."
+- Horizontal privilege escalation: user A can access user B's resources by changing an ID.
+- Vertical privilege escalation: non-admin can reach admin-only functionality.
+- Missing authorization checks on state-changing operations (writes, deletes) even when reads are protected.
+- Role or permission checks that happen in the UI but not in the backend.
+
+**Secret management issues:**
+- API keys, tokens, passwords, or connection strings hardcoded in source.
+- Secrets logged in plaintext (in log statements, error messages, or debug output).
+- Secrets passed via URL query parameters (visible in logs, referrer headers, browser history).
+- `.env` files, credential files, or key files not in `.gitignore`.
+- Secrets with no rotation mechanism or expiry.
+
+**Trust boundary violations:**
+- Internal APIs that accept data from external sources without re-validation.
+- Client-side validation without server-side enforcement.
+- Inter-service communication without mutual authentication.
+- Data from one tenant accessible to another (multi-tenancy isolation failures).
+
+**Web security (if applicable):**
+- Missing CORS restrictions or overly permissive CORS headers.
+- Missing Content-Security-Policy headers.
+- Cross-site scripting (XSS) via unescaped user content in HTML output.
+- Cross-site request forgery (CSRF) on state-changing endpoints without token verification.
+- Missing rate limiting on authentication endpoints.
+
+## How to report
+
+For each finding, record:
+- **Location**: file path and function/method name.
+- **Defect**: what security property is violated.
+- **Evidence**: the specific code path, missing check, or exposed secret.
+- **Severity**: critical (actively exploitable, data exposure, auth bypass), high (exploitable with some effort or preconditions), medium (defense-in-depth gap, hardcoded non-production secret), low (missing header, informational disclosure).
+- **Evidence level**: observed fact / strong inference / open question.
+
+## What to skip
+
+- Dependency vulnerability scanning (CVEs in third-party packages) — that's a tooling concern, not a code analysis task.
+- Cryptographic algorithm choices — unless they're demonstrably broken (e.g., MD5 for password hashing).

package/.codecarto/findings/defect-scan/passes/05-api-contract-violations.md

@@ -0,0 +1,57 @@
+# Pass 5: API Contract Violations
+
+Scan for functions, endpoints, and interfaces whose implementation doesn't match their documented or declared behavior.
+
+This pass is most powerful when `findings/contracts/behavioral-contracts.md` and `findings/protocols/protocols-and-state.md` exist. If available, read them first and use them as the spec to compare against. If not available, use the code's own documentation (docstrings, comments, type signatures, README) as the spec.
+
+## What to look for
+
+**Return type inconsistencies:**
+- Functions whose docstring or type signature says they return X, but some branches return Y or nothing.
+- APIs documented to return a specific shape, but error cases return a different shape.
+- Nullable returns from functions not marked as nullable/optional.
+- Collection-returning functions that sometimes return null instead of empty.
+
+**Documented behavior vs. actual behavior:**
+- Parameters documented as required that have silent defaults in implementation.
+- Side effects (writes, network calls, state mutations) not mentioned in docs or type signatures.
+- Functions documented as pure/idempotent that actually mutate state.
+- Default values documented in one place but implemented differently.
+- Error behavior documented as "throws X" but actually throws Y or returns an error code.
+
+**Interface contract breaks:**
+- Classes or modules that implement an interface but skip or stub required methods.
+- Event emitters that document events but never emit some of them.
+- Callback signatures that don't match what callers pass.
+- Middleware or plugin hooks with undocumented ordering dependencies.
+
+**State machine violations (spec-grounded):**
+- If protocols phase output is available: transitions that the implementation allows but the state machine says shouldn't happen.
+- State that can be entered but has no exit transition.
+- Guards documented as required but not enforced in code.
+- Side effects that should only fire on specific transitions but fire unconditionally.
+
+**Behavioral contract drift:**
+- If contracts phase output is available: features whose trigger/defaults/output/error-behavior in code differs from what the contracts document.
+- Black-box acceptance scenarios from the contracts that the code would fail.
+- Features documented as available on a surface (CLI, API, etc.) but missing or broken in the implementation for that surface.
+
+**Version and compatibility:**
+- APIs that changed behavior between versions without documentation.
+- Deprecation warnings that reference alternatives that don't exist yet.
+- Backward-compatibility promises broken by recent changes.
+
+## How to report
+
+For each finding, record:
+- **Location**: file path and function/method name.
+- **Defect**: what contract is violated and how.
+- **Spec source**: where the expected behavior is documented (docstring, type signature, contracts phase, protocols phase, README).
+- **Evidence**: the specific divergence between spec and implementation.
+- **Severity**: critical (public API returns wrong results), high (documented behavior incorrect in edge cases), medium (internal API inconsistency), low (stale docs, minor parameter mismatch).
+- **Evidence level**: observed fact / strong inference / open question.
+
+## What to skip
+
+- Style-level doc issues (typos, formatting) — unless they make the documented behavior ambiguous.
+- Test coverage gaps — unless a specific contract has no tests AND the implementation looks suspicious.

package/.codecarto/findings/defect-scan/passes/06-config-and-environment.md

@@ -0,0 +1,58 @@
+# Pass 6: Configuration and Environment Hazards
+
+Scan for hardcoded values, missing validation, dangerous defaults, and environment assumptions that cause failures in deployment or operation.
+
+If `findings/contracts/behavioral-contracts.md` exists, read the Configuration Model section first.
+
+## What to look for
+
+**Hardcoded values that should be configurable:**
+- URLs, hostnames, ports, or IP addresses embedded in source code.
+- Timeouts, retry counts, or buffer sizes that are magic numbers.
+- Feature behavior gated on string comparisons against environment names (e.g., `if env == "production"`).
+- File paths that assume a specific OS or directory structure.
+- Locale, timezone, or encoding assumptions baked into code.
+
+**Missing configuration validation:**
+- Config loaded at startup with no schema validation (malformed config silently produces wrong behavior).
+- Numeric config values with no range checks (negative timeouts, zero-size pools).
+- String config values used in security-sensitive contexts without sanitization (e.g., config-driven SQL, file paths).
+- Required config keys that are silently absent, falling back to dangerous defaults.
+
+**Dangerous defaults:**
+- Debug mode, verbose logging, or development-only features enabled by default.
+- Security features (auth, TLS, rate limiting) disabled unless explicitly turned on.
+- Default credentials or tokens that ship with the code.
+- Default config that works in development but fails or is unsafe in production.
+
+**Environment coupling:**
+- Code that assumes a specific OS (path separators, shell commands, temp directories).
+- Network assumptions (localhost availability, DNS resolution, specific ports being free).
+- Filesystem assumptions (case sensitivity, symlink support, file locking behavior).
+- Runtime version assumptions not enforced by manifests or checks.
+
+**Configuration propagation issues:**
+- Config changes that require a restart but aren't documented as such.
+- Config values read once at startup and cached, ignoring later changes.
+- Environment variables that override config files in undocumented ways.
+- Config inheritance chains where a middle layer silently drops values.
+
+**Deployment and operational hazards:**
+- Migrations or schema changes that run automatically without confirmation.
+- Startup sequences that fail silently if a dependency is unavailable.
+- Health checks that report healthy when critical subsystems are down.
+- Log output that contains sensitive config values (secrets, connection strings).
+
+## How to report
+
+For each finding, record:
+- **Location**: file path and function/method name.
+- **Defect**: what configuration or environment hazard exists.
+- **Evidence**: the specific hardcoded value, missing validation, or dangerous default.
+- **Severity**: critical (security exposure in default config, data loss on misconfiguration), high (production failure from missing validation), medium (hardcoded value that will break in a different environment), low (undocumented config behavior).
+- **Evidence level**: observed fact / strong inference / open question.
+
+## What to skip
+
+- Config file format preferences (YAML vs TOML vs JSON) — unless the format causes actual parsing ambiguity.
+- Deployment orchestration choices (Docker vs bare metal) — unless the code assumes one and breaks on the other.