docs: resolve 11 documentation inconsistencies from audit report

[nextlevelshit]

Summary

• Resolved 11 of 12 documentation inconsistencies identified in the audit report (docs: documentation consistency report #303)
• Added missing CLI command documentation for wave doctor, wave forge, and wave suggest
• Implemented non_empty_file contract validator in Go with comprehensive test coverage
• Updated architecture docs with correct workspace paths, contract types, and adapter status
• Fixed CLI reference: added global flags, --model flag, removed duplicate wave chat entry

Closes #303

Changes

• docs/reference/cli.md — Added 3 missing CLI commands (DOC-001), global flags --json/--quiet/--no-color (DOC-003), --model flag for run/do/meta (DOC-004), removed duplicate wave chat entry (DOC-010)
• internal/contract/non_empty_file.go — New non_empty_file contract validator implementation (DOC-002)
• internal/contract/non_empty_file_test.go — Table-driven tests for the new validator
• internal/contract/contract.go — Registered non_empty_file in contract type registry
• docs/concepts/architecture.md — Fixed workspace path, updated OpenCode adapter status, added missing contract types (DOC-005, DOC-006, DOC-007)
• docs/concepts/contracts.md — Aligned max_retries default documentation (DOC-009)
• docs/reference/contract-types.md — Added non_empty_file type documentation, aligned max_retries default (DOC-002, DOC-009)
• docs/reference/environment.md — Clarified CLAUDE_CODE_MODEL requires env_passthrough (DOC-011)
• docs/guide/quick-start.md — Updated wave init output example and sample config (DOC-012)
• specs/303-docs-consistency/ — Spec, plan, and task artifacts

Test Plan

• go test ./internal/contract/... validates the new non_empty_file contract validator
• go test -race ./... passes all tests
• Manual review of all 11 documentation changes against the audit checklist

[nextlevelshit]

Code Review (Wave Pipeline)

Verdict: REQUEST_CHANGES

The non_empty_file validator implementation is clean and follows existing patterns well. The documentation fixes are thorough and verified against the actual codebase. However, there are test coverage gaps that should be addressed before merge, and the behavioral change affecting 16+ default pipelines needs explicit acknowledgment.

---

Critical Issues

1. TestNewValidator table not updated — internal/contract/contract_test.go:478-499

The exhaustive factory dispatch test covers json_schema, typescript_interface, test_suite, unknown, and empty type — but does not include non_empty_file. If the case "non_empty_file" is accidentally removed in a future refactor, only the standalone test catches it, not the centralized registry test. Both reviewers flagged this independently.

Add to the table:

{"non_empty_file", ContractConfig{Type: "non_empty_file"}, false, "*contract.nonEmptyFileValidator"},

While you're there, consider adding the also-missing markdown_spec and format entries.

2. Validator silently passes for directories — internal/contract/nonEmptyFile.go:29-42

os.Stat succeeds on directories and fi.Size() returns non-zero metadata size on most filesystems. A source pointing to a directory will pass validation even though non_empty_file semantically requires a regular file. Add an fi.IsDir() guard before the size check.

3. Behavioral change needs documentation — internal/contract/contract.go:83-84

Previously NewValidator() returned nil for non_empty_file, causing validation to silently pass. After this PR, 18 contract references across 16+ default pipelines will actually enforce file existence and non-emptiness. This is the correct fix, but any pipeline step whose persona doesn't write the expected output will now fail where it previously succeeded. The PR description should explicitly call out this intentional behavioral change.

---

Suggested Improvements

Path traversal outside workspace boundary — internal/contract/non_empty_file.go:22-26 (HIGH from security review)

The validator resolves source against the workspace path via filepath.Join without constraining the result to the workspace directory. A source of ../../etc/passwd resolves outside the workspace, and absolute paths bypass resolution entirely. While os.Stat only leaks existence/size (not content), this is a concern in meta-pipeline scenarios where AI personas generate pipeline YAML.

This is a systemic gap — all existing validators have the identical pattern. The project's internal/security/path.go already has PathValidator with traversal detection, but it isn't wired into contract validation. Not blocking this PR since it's pre-existing, but worth tracking as a follow-up.

Error messages expose full filesystem paths — internal/contract/non_empty_file.go:33,41,50

Error messages include the resolved absolute path (e.g., /home/user/.wave/workspaces/...), which surfaces in logs and UI. Use the original user-supplied sourceFile in error messages; log the resolved path at debug level only.

File naming convention — nonEmptyFile.go / nonEmptyFile_test.go

The package uses either underscore-separated (format_validator.go, json_cleaner.go) or all-lowercase (jsonschema.go, markdownspec.go). No other file uses camelCase. Consider renaming to non_empty_file.go to match the dominant convention.

Add missing test cases — internal/contract/nonEmptyFile_test.go

The test suite covers happy paths well but is missing: directory-as-source, path traversal inputs (../../etc/passwd), and symlink-following behavior. At minimum, add the directory test to pair with the IsDir() guard.

---

Positive Observations

• The validator implementation is straightforward and correct for the intended use case, matching the structure of existing validators
• Documentation changes are extensive (7 files) and independently verified against the codebase — CLI flags, architecture diagrams, contract types, and environment variables all checked out
• The max_retries default was correctly identified and fixed to match EffectiveMaxAttempts() = 1 across both doc pages
• All contract tests pass with no race conditions detected
• No new dependencies introduced
• The Retryable field is correctly set: true for missing/empty files (transient — persona may not have written yet), false for missing config (structural error)

---

Generated by Wave gh-pr-review pipeline