# OCT — Option C Tools

**OCT** is a development-time CLI toolkit that enforces, generates, and audits code written to the **Option C** coding standard. It provides a linter, file generator, project scaffolder, documentation validator, test runner, and source exporter — all integrated with the `oc_diagnostics` runtime package.

OCT is a *dev-tool only*. It has no runtime dependency on `oc_diagnostics`; it merely ensures that projects it manages are correctly wired to use it.

---

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Project Structure Requirements](#project-structure-requirements)
- [Global Options](#global-options)
- [Commands Reference](#commands-reference)
  - [oct lint](#oct-lint)
  - [oct format](#oct-format)
  - [oct new](#oct-new)
  - [oct scaffold](#oct-scaffold)
  - [oct docs](#oct-docs)
  - [oct test](#oct-test)
  - [oct export-source](#oct-export-source)
  - [oct export-skeleton](#oct-export-skeleton)
  - [oct clean](#oct-clean)
  - [oct health](#oct-health)
  - [oct diag](#oct-diag)
  - [oct git status](#oct-git-status)
  - [oct git check](#oct-git-check)
  - [oct git init](#oct-git-init)
  - [oct git commit](#oct-git-commit)
  - [oct git hooks](#oct-git-hooks)
- [Option C Compliance Rules](#option-c-compliance-rules)
- [oc_diagnostics Integration](#oc_diagnostics-integration)
- [Workflows](#workflows)
- [Architecture Notes](#architecture-notes)
- [Configuration](#configuration)

---

## Installation

OCT is installed as a local editable package. From the `oct/` directory:

```bash
pip install -e .
```

This registers the `oct` entry point globally in your Python environment. Confirm it works:

```bash
oct --help
```

**Requirements:** Python 3.10+, Click 8.1+, pytest 7.0+

---

## Quick Start

```bash
# 1. Create a new Option C project
oct scaffold myproject
cd myproject

# 2. Verify the project structure is valid
oct docs

# 3. Create a new compliant Python file with companion test
oct new src/data_loader.py --test

# 4. Lint the entire project for compliance
oct lint

# 5. Auto-fix all compliance violations
oct format --fix

# 6. Lint only files you've changed (fast pre-commit check)
oct lint --changed

# 7. Check project health dashboard
oct health
```

---

## Project Structure Requirements

OCT locates your project root by walking up from the current directory and finding a folder that contains **all three** of:

```
<project_root>/
├── docs/
├── tests/
└── oc_diagnostics/    ← or diagnostics/ (legacy)
```

All OCT commands can be run from **any subdirectory** of the project; root detection is automatic.

`oct scaffold` creates this structure for you (using `oc_diagnostics/` as the new standard). If you're integrating OCT into an existing project, ensure these three directories exist. Both `oc_diagnostics/` and `diagnostics/` are accepted — `oc_diagnostics/` takes priority if both are present.

---

## Global Options

These options apply to all OCT commands and must appear **before** the subcommand name.

| Option | Description |
|--------|-------------|
| `--root-dir DIR` | Override project root directory. Bypasses auto-detection, allowing OCT to run on any directory — even non-Option C projects. Useful for assessing compliance of projects being ported. |

```bash
# Run health check on an arbitrary project
oct --root-dir /path/to/any/project health

# Lint a project from outside its directory tree
oct --root-dir ../other-project lint
```

When `--root-dir` is not specified, OCT auto-detects the project root by walking up from the current directory (the default behaviour).

---

## Commands Reference

### `oct lint`

**Static compliance analysis** of all Python source files in the project. Checks every file against the Option C standard and produces a colour-coded terminal report plus a timestamped log file.

```
oct lint [--fix-headers] [--dry-run] [--json] [--jobs N] [--changed] [PATH ...]
```

#### Flags

| Flag | Description |
|------|-------------|
| `--fix-headers` | Automatically rewrite malformed shebang / encoding / path header lines. Originals are archived to `.linter_archive/<filename>.<timestamp>.bak` before modification. |
| `--dry-run` | Preview changes without modifying files. When combined with `--fix-headers`, violations are reported but no files are written. |
| `--json` | Output structured JSON results to stdout instead of the colorized terminal report. Suitable for CI pipelines, IDE integrations, and automated processing. |
| `--jobs N` / `-j N` | Number of parallel workers for file processing (default: 1). Automatically falls back to sequential when `--fix-headers` is active. |
| `--changed` | Lint only git-modified Python files (staged + unstaged). Useful for fast pre-commit checks. Overrides explicit PATH targets if both provided. |
| `PATH ...` | Files or directories to lint. Defaults to the entire project. |

#### What it checks

| Check | Description |
|-------|-------------|
| **Header block** | Lines 1–4 must be: `#!/usr/bin/env python3`, `# -*- coding: utf-8 -*-`, `# <project>/<relative/path.py>`, blank line. |
| **Docstring structure** | Module-level docstring must contain all four sections: `Purpose`, `Responsibilities`, `Diagnostics`, `Contracts`. |
| **Diagnostics profile** | The Diagnostics section must declare a `Domain` and define `L2`, `L3`, and `L4` log levels. |
| **`_dbg` usage** | Non-trivial files (> 20 lines) must contain at least one `_dbg()` call (AST-verified). |
| **`_dbg` import** | Non-trivial files must import `_dbg` via the canonical `from oc_diagnostics import _dbg` statement. Aliased imports are not accepted. |
| **`func = "..."` pattern** | Every function in a non-trivial file that calls `_dbg()` must define `func = "function_name"` before the first `_dbg()` call. Checked per-function body; nested functions supported. |
| **Syntax warnings** | Detects Python syntax warnings (e.g. invalid escape sequences like `'\.'` instead of `r'\.'`). These will become `SyntaxError` in a future Python version. |
| **Hardcoded secrets** | AST-based detection of string literals assigned to secret-like variable names (`password`, `api_key`, `token`, etc.), dict literals with secret keys, and function defaults with secret parameters. See §6b Secret Hygiene. Blocking at `compact` and `strict` profiles. |
| **Regression tests** | Heuristic check — verifies that a test file referencing the module name exists in `tests/`. |
| **Project-level files** | Checks for `docs/ARCHITECTURE.md`, `tests/Tests_README.md`, `tests/run_tests.py`, `oc_diagnostics/debug_config.json` (or `diagnostics/debug_config.json`). |

#### Output

Terminal output shows per-check pass rates as percentages plus per-file results. A detailed log is written to:

```
logs/oct_lint_output-<YYYYMMDD-HHMMSS>.txt
```

#### Example

```bash
# Basic lint run
oct lint

# Fix headers automatically, then re-check
oct lint --fix-headers
oct lint

# Lint only files you've changed (fast pre-commit check)
oct lint --changed
```

#### Excluded directories

The linter skips directories that match these patterns so it never scans generated or non-source trees:

| Type | Names |
|------|-------|
| Exact match | `data`, `data_raw`, `raw_data`, `flow_charts`, `dot_files`, `dev-tools`, `Code Reviews`, `copied_python_files`, `.git`, `Old`, `old`, `__pycache__` |
| Wildcard match (substring) | `cache`, `_source`, `logs`, `_exports`, `_build` |

---

### `oct format`

**Auto-fix Option C compliance violations.** Automatically fixes structural violations detected by `oct lint` (headers, docstrings, imports, function patterns) while preserving all code logic. Supports dry-run mode for safe preview before applying fixes.

```
oct format [--fix] [--dry-run] [--json] [--verbose]
```

#### Flags

| Flag | Description |
|------|-------------|
| `--fix` | Apply formatting changes to files. Without this flag, only reports what would change (default: dry-run). |
| `--dry-run` | Report what would change without modifying files (default behavior). Useful for preview before `--fix`. |
| `--json` | Output machine-readable JSON instead of colorized terminal report. Useful for CI/CD integration. |
| `--verbose` | Show per-file details in addition to summary. |
| `--help` | Show help message. |

#### What it fixes

| Issue | Action |
|-------|--------|
| **Malformed header block** | Rewrites shebang, encoding, file identity, and blank line to correct format. |
| **Missing module docstring** | Inserts complete docstring skeleton with all required sections (Purpose, Responsibilities, Diagnostics, Contracts). |
| **Incomplete module docstring** | Adds missing sections to existing docstrings while preserving content. |
| **Missing `_dbg` import** | Adds canonical `from oc_diagnostics import _dbg` import at module level. Removes any aliased or incorrect imports. |
| **Missing `func = "..."` pattern** | Inserts `func = "function_name"` as the first statement in functions that call `_dbg()`. |

#### Safety & Archival

- Original files are automatically backed up to `.formatter_archive/<filename>.<timestamp>.bak` before any modification.
- All code below the header block is preserved exactly as-is.
- Only structural/boilerplate issues are fixed; no code reformatting or style changes are applied.
- Files are never modified unless `--fix` is explicitly passed.
- Trivial files (< 20 lines) skip certain checks to avoid over-formatting scaffolding code.

#### Examples

```bash
# Report what would be fixed (no changes) — safe to run anytime
oct format

# Preview changes with detailed per-file breakdown
oct format --dry-run --verbose

# Actually apply formatting and show summary
oct format --fix

# Apply and save JSON report for CI pipeline
oct format --fix --json > format-report.json
```

---

### `oct new`

**Generate a new Option C-compliant Python file.** Creates the file with a correct 3-line header, the `oc_diagnostics` import, and a fully structured module docstring template — so the file is immediately linter-compliant before you write a single line of logic.

```
oct new PATH [--force] [--test] [--dry-run] [--verbose]
```

#### Arguments

| Argument | Description |
|----------|-------------|
| `PATH` | Relative or absolute path to the new file. Parent directories are created automatically. |

#### Flags

| Flag | Description |
|------|-------------|
| `--force` | Overwrite the file if it already exists. Without this flag the command refuses to clobber existing files. |
| `--test` | Also generate a companion test file at `tests/test_<name>.py` with a skeleton test and correct import path. |
| `--dry-run` | Show what would be created without writing any files. |
| `--verbose` | Show the generated file content. Works with or without `--dry-run`. |

#### Generated file structure

```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# <project_name>/<relative/path/to/file.py>

from oc_diagnostics import _dbg

"""
Purpose
-------
<describe what this module does>

Responsibilities
----------------
- <responsibility 1>
- <responsibility 2>

Diagnostics
-----------
Domain: <DOMAIN_NAME>
L2: <summary-level events>
L3: <detailed workflow events>
L4: <verbose / trace-level events>

Contracts
---------
Inputs:  <describe inputs>
Outputs: <describe outputs>
"""
```

#### Examples

```bash
# Create a new file
oct new src/api/client.py

# Create a module and its companion test file
oct new src/api/client.py --test

# Preview what would be created
oct new src/api/client.py --test --dry-run

# Preview with full file content
oct new src/api/client.py --test --dry-run --verbose

# Overwrite an existing file
oct new src/api/client.py --force

# Works from any subdirectory — project root is detected automatically
cd src/api
oct new ../../utils/helpers.py
```

---

### `oct scaffold`

**Create a complete Option C project skeleton** in a new directory.

```
oct scaffold NAME [--dry-run]
```

#### Arguments

| Argument | Description |
|----------|-------------|
| `NAME` | Name of the project directory to create (created in the current working directory). |

#### Flags

| Flag | Description |
|------|-------------|
| `--dry-run` | Show what would be created without writing any files or directories. |

#### What gets created

```
NAME/
├── docs/
│   └── ARCHITECTURE.md              # Stub — fill in your architecture decisions
├── tests/
│   ├── run_tests.py                 # Stub — wire up your test runner
│   └── Tests_README.md              # Stub — document your testing strategy
├── oc_diagnostics/
│   └── debug_config.json            # Pre-filled oc_diagnostics configuration template
└── logs/                            # Empty — receives oct lint output
```

#### Generated `debug_config.json`

```json
{
  "domains": {
    "GENERAL": { "level": 2, "color": "default" }
  },
  "global_settings": {
    "silent_mode": false,
    "enable_timestamps": true,
    "enable_colors": true,
    "include_filename": true,
    "output_mode": "both",
    "instrumentation_enabled": false,
    "max_log_files": 10,
    "max_log_size_mb": 5.0,
    "instrumentation_allow_all": false,
    "mode": "dev",
    "http_redact_headers": ["authorization", "cookie", "set-cookie", "x-api-key"]
  }
}
```

Add your project domains to the `domains` map; see the `oc_diagnostics` documentation for the full config schema.

#### Example

```bash
oct scaffold payment-service
cd payment-service
oct new src/processor.py
oct lint
```

---

### `oct docs`

**Validate, generate, or clean project documentation.**

```
oct docs [--sphinx] [--doxygen] [--all] [--clean] [--dry-run]
```

#### Flags

| Flag | Description |
|------|-------------|
| `--sphinx` | Generate Sphinx HTML documentation from Python docstrings and markdown files in `docs/`. Outputs to `docs/html/`. |
| `--doxygen` | Generate Doxygen HTML documentation. Finds `docs/doxygen_work_dir/Doxyfile`, patches the stale `INPUT` path to the actual project root, and runs `doxygen` on a temporary copy. Outputs to `docs/doxygen_output/`. |
| `--all` | Run both `--sphinx` and `--doxygen` pipelines sequentially. |
| `--clean` | Remove generated documentation artifacts (`html/`, `doctrees/`, `_api/`, `doxygen_output/`, `index.rst`, `dependencies.rst`) from `docs/`. Preserves `_sphinx/`, `_static/`, `_templates/`, `doxygen_work_dir/`, and user-authored markdown files. |
| `--dry-run` | Preview what `--clean` would remove without deleting anything. |

Without any flags, validates that required project-level documentation files exist:

| File | Purpose |
|------|---------|
| `docs/ARCHITECTURE.md` | Architecture decisions and module map |
| `tests/Tests_README.md` | Testing strategy and conventions |
| `oc_diagnostics/debug_config.json` | `oc_diagnostics` runtime configuration (falls back to `diagnostics/debug_config.json`) |

#### Examples

```bash
# Validate documentation structure
oct docs

# Generate Sphinx HTML documentation
oct docs --sphinx

# Generate Doxygen HTML documentation
oct docs --doxygen

# Generate both Sphinx and Doxygen docs
oct docs --all

# Preview what clean would remove
oct docs --clean --dry-run

# Remove generated artifacts
oct docs --clean
```

---

### `oct test`

**Run the project's test suite** via pytest.

```
oct test [ARGS ...]
```

All arguments are forwarded to pytest. Exits with the pytest return code so it integrates cleanly into CI pipelines.

#### Single-project mode

When the project root contains a `tests/` directory or a pytest configuration file (`pytest.ini`, `pyproject.toml`, `setup.cfg`, `tox.ini`), `oct test` runs `python -m pytest` from that root.

#### Meta-project mode

When the project root has **no** test suite of its own (e.g. a monorepo like `Option_C/` that contains sub-projects), `oct test` automatically discovers immediate sub-directories that have **both** a `tests/` directory and a pytest config file, then runs each sub-project's tests independently in the correct working directory. Results are aggregated and the command exits non-zero if any sub-project fails.

---

### `oct export-source`

**Consolidate all source files into readable text files** for code review, archiving, or analysis. Produces per-directory export files and one full-project rollup.

```
oct export-source [PATH] [--verbose] [--clean] [--single-dir]
```

#### Arguments

| Argument | Description |
|----------|-------------|
| `PATH` | Root directory to export from. Defaults to the auto-detected project root. |

#### Flags

| Flag | Description |
|------|-------------|
| `--verbose` | Print per-file line/word/byte statistics in the terminal summary in addition to per-directory totals. |
| `--clean` | Delete all `_source_code-*` directories under `PATH` without creating any new exports. Use this to clean up after multiple export runs. |
| `--single-dir` | Write all export files into a single `_source_code-<timestamp>/` directory at the project root instead of creating per-directory output folders. Reduces filesystem clutter on large projects. |

#### Output structure

For each included directory, a `_source_code-<YYYYMMDD-HHMM>/` folder is created inside it:

```
<root>/
└── _source_code-202602271430/
    ├── _source.<root>.txt          # All files from root directory
    ├── _source.src.txt             # All files from src/
    ├── _source.src.api.txt         # All files from src/api/
    └── _full_source.<root>.txt     # All files from entire project, grouped by directory
```

Each file starts with a header identifying the export, followed by the contents of each source file separated by clear delimiters.

#### Included file types

`.py`, `.java`, `.json`, `.css`, `.ini`, `.xml`, `.js`, `.ts`, `.tsx`, `.html`, `.md`, `.npmignore`, `.gitignore`, `.ahk`, `.yml`, `.yaml`, `.toml`, `.sh`, `.bat`, `.ps1`, `.sql`, `.rb`, `.swift`

**Note:** `.env` files are excluded by design (§6b Secret Hygiene). Additionally, files matching `NEVER_EXPORT_FILE_PATTERNS` (`.env*`, `*.pem`, `*.key`, `credentials.json`, `secrets.json`, `secrets.yaml`) are never exported regardless of extension profile.

#### Terminal summary (default)

```
========== SUMMARY ==========
Directory '.':      42 files,  5 234 lines,  68 492 words,  512.3 KB
Directory 'src':    18 files,  2 847 lines,  35 221 words,  287.6 KB
Directory 'tests':   9 files,    441 lines,   5 102 words,   38.2 KB
...
Total directories processed: 3
Total source files processed: 69
Total lines: 8 522
Total words: 108 815
Total size: 838.1 KB
Output stored under _source_code-202602271430 directories
=============================
```

If any directories could not be written (e.g. due to Windows MAX_PATH limits), they are
listed at the bottom of the summary:

```
Skipped 1 directory due to errors:
  - library/very_long_subdirectory_name/...
=============================
```

#### I/O error resilience

`oct export-source` never crashes on a recoverable I/O error. All failure modes are
handled gracefully:

| Scenario | Behaviour |
|----------|-----------|
| Output directory cannot be created (e.g. permissions, path too long) | Warning printed; directory skipped; export continues |
| Output file cannot be opened (e.g. Windows MAX_PATH exceeded) | Warning printed; directory skipped; export continues |
| Individual source file cannot be read | File skipped silently; rest of directory exported normally |
| Full-source rollup file cannot be created | Warning printed; per-directory exports are unaffected |

**Windows long-path handling:** output filenames are derived from the dotpath-encoded
directory name. If the full path would exceed 240 characters, the dotpath is truncated
and an 8-character MD5 hash is appended to guarantee uniqueness:

```
_source.myproject.library._uncategorized.very_lon...a3f8c201.txt
```

#### Examples

```bash
# Export from current directory
oct export-source

# Export with per-file breakdown
oct export-source --verbose

# Export a specific project root
oct export-source /path/to/project --verbose

# Remove all previous exports (deprecated — use 'oct clean' instead)
oct export-source --clean
```

---

### `oct export-skeleton`

**Export structural skeletons of source files** for AI inspection, code review, or project overview. Emits headers, module docstrings, and function/class signatures without implementation bodies — giving a complete API surface overview without saturating context windows.

```
oct export-skeleton [PATH] [--verbose] [--single-dir] [--no-diagnostics] [--clean]
```

#### Arguments

| Argument | Description |
|----------|-------------|
| `PATH` | Root directory to export from. Defaults to the auto-detected project root. |

#### Flags

| Flag | Description |
|------|-------------|
| `--verbose` | Print per-file line/word/byte statistics in the terminal summary. |
| `--single-dir` | Write all output into one root-level `_skeleton_code-<timestamp>/` directory. |
| `--no-diagnostics` | Omit the Diagnostics section from module docstrings (reduces noise for non-Option C reviewers). |
| `--clean` | Remove all `_skeleton_code-*` directories and exit. |

#### What gets exported (Python files)

- Lines 1-3 (shebang, encoding, file identity header)
- Module docstring (optionally filtered with `--no-diagnostics`)
- Class definitions with bases, decorators, and class docstrings
- Function/method signatures with type hints, decorators, and docstrings
- Module-level constants (`ALL_CAPS` names)
- `...` as body placeholder — no implementation code

#### What gets exported (non-Python files)

A one-line placeholder showing filename, line count, and size:

```
# [config.json] 42 lines, 1.2 KB
```

#### Output structure

Same structure as `oct export-source`: per-directory `_skeleton_code-<YYYYMMDD-HHMM>/` folders containing `_skeleton.<dotpath>.txt` files and a `_full_skeleton.<root>.txt` rollup.

#### Examples

```bash
# Export skeletons from current project
oct export-skeleton

# Export without Option C-specific Diagnostics sections
oct export-skeleton --no-diagnostics

# Consolidated output with per-file stats
oct export-skeleton --single-dir --verbose

# Clean up skeleton exports
oct export-skeleton --clean
```

---

### `oct clean`

**Remove build artifacts** from a directory tree: export directories, skeleton directories, and Python bytecode caches.

```
oct clean [--dry-run] [PATH]
```

#### Flags

| Flag | Description |
|------|-------------|
| `--dry-run` | Show what would be deleted without deleting anything. |

#### Arguments

| Argument | Description |
|----------|-------------|
| `PATH` | Directory to clean. Defaults to the current working directory. |

Removes recursively under `PATH` (or cwd):

| Artifact | Pattern |
|----------|---------|
| Source export directories | `_source_code-<timestamp>/` anywhere in the tree |
| Skeleton export directories | `_skeleton_code-<timestamp>/` anywhere in the tree |
| Python bytecode caches | `__pycache__/` anywhere in the tree |

Safe to run from **any directory** — no Option C project structure required. Only
generated artifacts are removed; source files are untouched.

#### Examples

```bash
# Clean from the current directory
oct clean

# Clean a specific directory
oct clean /path/to/project
```

---

### `oct health`

**Display a project compliance dashboard.** Aggregates lint results, fixable violations, documentation status, test results, and `oc_diagnostics` compatibility into a single report.

```
oct health [--json] [--verbose]
```

#### Flags

| Flag | Description |
|------|-------------|
| `--json` | Output machine-readable JSON instead of terminal report. |
| `--verbose` | Show per-file lint breakdown in addition to summary. |

#### What it checks

| Section | Description |
|---------|-------------|
| **Lint Compliance** | Runs all linter checks on every Python file and reports per-check pass rates and overall compliance percentage. |
| **Fixable Violations** | Counts violations that `oct format --fix` could auto-fix (headers, docstrings, imports, func patterns). |
| **Documentation** | Validates presence of required files: `ARCHITECTURE.md`, `Tests_README.md`, `run_tests.py`, `debug_config.json`. |
| **Tests** | Runs `pytest` and captures pass/fail/skip counts, timing, and actionable error details (e.g. missing modules, import errors). Detects missing pytest before running. |
| **oc_diagnostics** | Checks whether `oc_diagnostics` is installed and version-compatible. |

#### Examples

```bash
# Quick compliance overview
oct health

# Detailed per-file breakdown
oct health --verbose

# Machine-readable output for CI
oct health --json

# Parse JSON with jq
oct health --json | python -m json.tool
```

### `oct diag`

**Manage oc_diagnostics configuration** without editing JSON manually. Provides subcommands for validating, inspecting, and updating `debug_config.json`.

> **Note:** OCT does not import `oc_diagnostics` at runtime — `oct diag` operates purely on the JSON config file, preserving the dev-time/runtime architectural boundary.

```
oct diag <subcommand>
```

#### Subcommands

| Subcommand | Description |
|------------|-------------|
| `validate-config` | Validate `debug_config.json` against the expected schema. Reports errors (invalid JSON, missing required keys, bad level values) and warnings (missing optional keys). |
| `list-domains` | List all configured domains with their debug levels and colors in a formatted table. |
| `set-level DOMAIN LEVEL` | Update a domain's debug level (0–4) in `debug_config.json`. Validates level range and domain existence. |

#### Examples

```bash
# Validate your config file
oct diag validate-config

# List all domains with levels and colors
oct diag list-domains

# Set the API domain to verbose tracing
oct diag set-level API 4

# Silence a noisy domain
oct diag set-level DATABASE 0
```

---

### `oct git status`

**Show git repository state** with Option C compliance annotations.

```
oct git status [--json] [--verbose]
```

| Flag | Description |
|------|-------------|
| `--json` | Output structured JSON |
| `--verbose` | Show per-file lint status for staged files |

Displays branch name, clean/dirty state, staged/unstaged file counts, hook installation state, and protected-branch warnings.

---

### `oct git check`

**Run the unified quality gate** on staged files or the entire project.

```
oct git check [--staged-only] [--all] [--profile PROFILE] [--fix] [--include-tests] [--json]
```

| Flag | Description |
|------|-------------|
| `--staged-only` | Check only git-staged files (default) |
| `--all` | Check all Python files in the project |
| `--profile` | Override lint profile: `proto`, `compact`, `strict` |
| `--fix` | Apply auto-fixes for format violations |
| `--include-tests` | Also run the test suite |
| `--json` | Output structured JSON |

Exit codes: 0=pass, 1=lint, 2=format, 3=lint+format, 4=tests, 5=secrets.

```bash
# Quick pre-commit check
oct git check --staged-only

# Full project check with JSON for CI
oct git check --all --json
```

---

### `oct git init`

**Initialise or enhance** a git repository with Option C conventions.

```
oct git init [--force] [--skip-workflow] [--json]
```

| Flag | Description |
|------|-------------|
| `--force` | Overwrite existing configuration files |
| `--skip-workflow` | Do not generate GitHub Actions workflow |
| `--json` | Output structured JSON summary |

Creates/merges `.gitignore`, `.gitattributes`, and `.github/workflows/oct-ci.yml`.

```bash
oct git init
oct git init --force --skip-workflow
```

---

### `oct git commit`

**Commit staged changes** with quality gate enforcement and Conventional Commits validation.

```
oct git commit -m MESSAGE [--force] [--no-verify] [--profile PROFILE] [--json]
```

| Flag | Description |
|------|-------------|
| `-m MESSAGE` | **Required.** Commit message in Conventional Commits format |
| `--force` | Skip lint/format checks. **Secrets still checked.** |
| `--no-verify` | Forward `--no-verify` to git. OCT's own checks still run. |
| `--profile` | Override lint profile: `proto`, `compact`, `strict` |
| `--json` | Output structured JSON |

Exit codes: 0=committed, 1=quality/branch blocked, 2=secrets (non-bypassable), 3=bad message, 4=nothing staged.

**Conventional Commits format:** `<type>(<scope>): <subject>`

Valid types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `sec`

```bash
# Standard commit
oct git commit -m "feat(auth): add token validation"

# Force past lint (secrets still checked)
oct git commit -m "fix: hotfix" --force
```

---

### `oct git hooks`

**Manage Option C pre-commit hooks.** Subcommands: `install`, `status`, `remove`.

```bash
# Install all four hooks
oct git hooks install

# Overwrite existing config
oct git hooks install --force

# Check which hooks are installed
oct git hooks status

# Remove OCT hooks (preserves non-OCT hooks)
oct git hooks remove
```

Generates `.pre-commit-config.yaml` with: `oct-quality-gate` (pre-commit), `oct-secrets-check` (pre-commit, always_run), `oct-commit-msg` (commit-msg), `oct-pre-push` (pre-push).

After installing, run `pre-commit install` to activate the hooks.

> **Note:** `oct install-hooks` still works but prints a deprecation notice. Use `oct git hooks install` instead.

---

## Option C Compliance Rules

Every Python file in an Option C project must satisfy the following structure. OCT enforces these at lint time and generates them at `oct new` time.

### 1. Three-line file header

The first three lines of every `.py` file must be exactly:

```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# <project_name>/<path/relative/to/project/root.py>
```

Followed by a **blank line**.

### 2. Module docstring

A top-level docstring with four named sections:

```python
"""
Purpose
-------
One-paragraph description of what this module does and why it exists.

Responsibilities
----------------
- Bullet list of what this module owns and manages.
- Keep each responsibility narrow and testable.

Diagnostics
-----------
Domain: DOMAIN_NAME
L2: High-level summary events (startup, completion, key decisions).
L3: Per-operation workflow events (function entry/exit, state transitions).
L4: Verbose trace events (loop iterations, raw data, intermediate values).

Contracts
---------
Inputs:  What this module expects (types, validated state, preconditions).
Outputs: What this module guarantees (return types, side effects, postconditions).
"""
```

### 3. `_dbg` import and usage

Every non-trivial module (more than 20 lines) must:

```python
from oc_diagnostics import _dbg

def my_function(data):
    func = "my_function"
    _dbg("L3", "Processing data", domain="DOMAIN_NAME", func=func, count=len(data))
    # ... logic ...
    _dbg("L2", "Processing complete", domain="DOMAIN_NAME", func=func)
```

### 4. Comments explain *why*, not *what*

```python
# BAD: Set retries to 3
retries = 3

# GOOD: Cap at 3 retries — beyond this the upstream service is likely down,
#       and hammering it degrades recovery for all callers.
retries = 3
```

---

## oc_diagnostics Integration

OCT is tightly coupled to the `oc_diagnostics` v1.5 runtime package at scaffolding and generation time, though it never imports it directly.

| OCT action | oc_diagnostics effect |
|------------|-----------------------|
| `oct scaffold` | Generates `oc_diagnostics/debug_config.json` pre-configured for `oc_diagnostics` |
| `oct new` | Adds `from oc_diagnostics import _dbg` to every generated file |
| `oct lint` | Validates `_dbg()` call presence, Diagnostics profile block, and `debug_config.json` existence |
| `oct diag` | Validates, inspects, and updates `debug_config.json` without manual editing |
| `oct health` | Checks `oc_diagnostics` installation and version compatibility |

Install `oc_diagnostics` in your project's environment:

```bash
pip install oc_diagnostics
```

Configure it by editing `oc_diagnostics/debug_config.json` (or `diagnostics/debug_config.json` for legacy projects). The `oc_diagnostics` package reads this file at runtime (via the `OC_DIAGNOSTICS_CONFIG` env var or automatic discovery).

### Domain configuration example

Add a domain per logical subsystem:

```json
{
  "domains": {
    "API":      { "level": 3, "color": "cyan" },
    "DATABASE": { "level": 2, "color": "blue" },
    "AUTH":     { "level": 4, "color": "yellow" }
  }
}
```

Level meanings: `2` = summary, `3` = detailed, `4` = verbose/trace. Set to `0` to silence a domain entirely.

---

## Workflows

### Start a new project from scratch

```bash
oct scaffold my-service
cd my-service

# Fill in docs/ARCHITECTURE.md, tests/Tests_README.md
# Add your domains to oc_diagnostics/debug_config.json

oct git init                    # .gitignore, .gitattributes, CI workflow
oct git hooks install           # Install pre-commit hooks
pre-commit install              # Activate hooks

oct new src/core/engine.py
oct new src/api/routes.py
oct new tests/test_engine.py

oct lint         # Verify compliance before writing any logic
```

### Bring an existing project into compliance

```bash
cd existing-project

# Create the required directory structure if missing
mkdir -p docs tests oc_diagnostics logs

# Add oc_diagnostics config
# (copy template from a scaffolded project or write from scratch)

# Auto-fix all header violations first
oct lint --fix-headers

# Then address remaining failures manually
oct lint
```

### Review code before a commit

```bash
cd my-service
oct lint --changed              # Fast check on modified files only
oct test                        # Run test suite
oct health                      # Full compliance dashboard
```

### Commit with quality gate

```bash
# Stage your changes
git add src/core/engine.py

# Commit with Conventional Commits message (quality gate runs automatically)
oct git commit -m "feat(core): add engine module"

# Force past lint violations on a hotfix (secrets still checked)
oct git commit -m "fix: patch null pointer" --force
```

### Manage diagnostics configuration

```bash
# Validate your debug_config.json
oct diag validate-config

# See all domains and their current levels
oct diag list-domains

# Increase verbosity for debugging a specific subsystem
oct diag set-level API 4

# Dial it back down when done
oct diag set-level API 2
```

### Clean up export artifacts

```bash
# After a review session, remove all export directories
oct clean
```

### CI/CD integration

```yaml
# .github/workflows/ci.yml (example)
- name: Install OCT
  run: pip install -e path/to/oct

- name: Quality gate
  run: oct git check --all --json

- name: Run tests
  run: oct test
```

> **Tip:** `oct git init` generates a ready-made `.github/workflows/oct-ci.yml` workflow.

---

## Architecture Notes

### Project root detection

OCT searches upward from the current working directory for a folder containing `docs/`, `tests/`, and either `oc_diagnostics/` or `diagnostics/`. This means you can run any `oct` command from any subdirectory of your project. `oc_diagnostics/` is the modern standard; `diagnostics/` is accepted as a legacy fallback.

### Header auto-fix safety

`oct lint --fix-headers` never silently destroys content:

1. The original file is copied to `.linter_archive/<filename>.<YYYYMMDD-HHMMSS>.bak`.
2. The new file is written with corrected headers.
3. All content below the header is preserved exactly.

### Linting is purely static

The linter uses AST parsing and text analysis only. It never imports your project modules, so it is safe to run on broken or partially written code, and it imposes no runtime overhead.

### Log file retention

`oct lint` appends a timestamped file to `logs/` on every run. This directory is excluded from linting and exporting automatically. Rotate or delete old logs manually as needed.

### Source exporter exclusions

The exporter applies the same directory exclusion rules as the linter, so generated artifacts (`_source_code-*`, `logs/`, `__pycache__/`, etc.) never appear in exports.

---

## Configuration

### Per-project linter configuration (`.octrc.json`)

Place a `.octrc.json` file in your project root to customise linter behaviour. The file
supports the following keys under the `"linter"` section:

```json
{
  "linter": {
    "exclude_dirs_add": ["vendor", "generated"],
    "exclude_dirs_remove": ["data"],
    "wildcard_exclude_add": ["_temp"]
  }
}
```

| Key | Effect |
|-----|--------|
| `exclude_dirs_add` | Add directory names to the exclusion list (exact match). |
| `exclude_dirs_remove` | Remove directory names from the default exclusion list. |
| `wildcard_exclude_add` | Add substring patterns to the wildcard exclusion list. |
| `profile` | Select a named rule profile: `"strict"` (all rules), `"default"` (all rules), or `"minimal"` (header + docstring only). |
| `rules` | Per-rule overrides — set individual rules to `true` or `false`. Overrides the selected profile. |

Available rule names: `header`, `docstring`, `diagnostics_profile`, `dbg_usage`,
`dbg_import`, `func_pattern`, `no_hardcoded_secrets`, `tests_exist`.

**Example — minimal profile with func_pattern re-enabled:**

```json
{
  "linter": {
    "profile": "minimal",
    "rules": {
      "func_pattern": true
    }
  }
}
```

**Complete `.octrc.json` example with all keys:**

```json
{
  "linter": {
    "profile": "strict",
    "exclude_dirs_add": ["vendor", "generated"],
    "exclude_dirs_remove": [],
    "wildcard_exclude_add": ["_temp"],
    "rules": {
      "header": true,
      "docstring": true,
      "diagnostics_profile": true,
      "dbg_usage": true,
      "dbg_import": true,
      "func_pattern": true,
      "no_hardcoded_secrets": true,
      "tests_exist": true
    }
  }
}
```

If the file contains malformed JSON, a warning is printed to stderr and defaults are used.

> **See also:** [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) section 6.1 for detailed
> documentation of all configuration keys and profile definitions.

### Per-project exporter configuration (`_oct_exporter_config.json`)

Place a `_oct_exporter_config.json` file in your project root to customise the source
exporter. Supports add/remove/replace semantics for `include_extensions`, `exclude_dirs`,
and `wildcard_exclude_dirs`. See `oct/tools/source_exporter.py` for the full schema.

If no project-level config is found, the exporter falls back to oct's own bundled
`_oct_exporter_config.json` (with a note to stderr). This ensures comprehensive
directory exclusions (`.venv`, `.claude`, `.git`, AI tool directories, etc.) are always
applied. Built-in hardcoded defaults are used only if the bundled config is also absent.

---

## Reference

| Resource | Location |
|----------|----------|
| **OCT Reference** | **`docs/REFERENCE.md`** |
| Option C Specification (V3.4) | `docs/option_c_specs/00_Master_Option_C_Specs_Intro_V3_4.md` (entry point) + companion files (Core, Tooling, Diagnostics, AI Protocol, Changelog) |
| OCT Architecture | `docs/ARCHITECTURE.md` |
| Git Integration Guide | `docs/GIT.md` (project-level) |
| Linter internals | `docs/linter.md` |
| oc_diagnostics API | `oc_diagnostics/docs/REFERENCE.md` |
| oc_diagnostics config schema | `oc_diagnostics/docs/debug_config.example.json` |
| Integration patterns | `oc_diagnostics/docs/INTEGRATION_GUIDE.md` |