# OCT Reference

> **Version:** 0.12.0
> **Entry point:** `oct = oct.cli:cli` (Click-based CLI)
> **Python:** 3.10+
> **Dependencies:** Click 8.1+, pytest 7.0+

OCT (Option C Tools) is a development-time CLI toolkit that enforces, generates, and audits code written to the Option C coding standard. It has **no runtime dependency** on `oc_diagnostics` — it merely ensures that projects it manages are correctly wired to use it.

---

## Table of Contents

- [1. Installation & Entry Point](#1-installation--entry-point)
- [2. Project Root Detection](#2-project-root-detection)
- [3. CLI Commands — Complete Reference](#3-cli-commands--complete-reference)
  - [3.1 oct lint](#31-oct-lint)
  - [3.2 oct format](#32-oct-format)
  - [3.3 oct new](#33-oct-new)
  - [3.4 oct scaffold](#34-oct-scaffold)
  - [3.5 oct docs](#35-oct-docs)
  - [3.6 oct test](#36-oct-test)
  - [3.7 oct export-source](#37-oct-export-source)
  - [3.8 oct export-skeleton](#38-oct-export-skeleton)
  - [3.9 oct clean](#39-oct-clean)
  - [3.10 oct health](#310-oct-health)
  - [3.11 oct diag](#311-oct-diag)
  - [3.12 oct git status](#312-oct-git-status)
  - [3.13 oct git check](#313-oct-git-check)
  - [3.14 oct git init](#314-oct-git-init)
  - [3.15 oct git commit](#315-oct-git-commit)
  - [3.16 oct git hooks](#316-oct-git-hooks)
- [4. Configuration](#4-configuration)
  - [4.1 .octrc.json — Linter Configuration](#41-octrcjson--linter-configuration)
  - [4.2 .octrc.json — Git Configuration](#42-octrcjson--git-configuration)
  - [4.3 _oct_exporter_config.json — Exporter Configuration](#43-_oct_exporter_configjson--exporter-configuration)
- [5. Option C Compliance Rules](#5-option-c-compliance-rules)
- [6. Linter Internals](#6-linter-internals)
- [7. Formatter Internals](#7-formatter-internals)
- [8. Generator Internals](#8-generator-internals)
- [9. Health Dashboard Internals](#9-health-dashboard-internals)
- [10. Diagnostics Config Tools Internals](#10-diagnostics-config-tools-internals)
- [11. Source Exporter Internals](#11-source-exporter-internals)
- [12. oc_diagnostics Integration Points](#12-oc_diagnostics-integration-points)

---

## 1. Installation & Entry Point

OCT is installed as a local editable package:

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

This registers the `oct` console script globally. The entry point is defined in `pyproject.toml`:

```toml
[project.scripts]
oct = "oct.cli:cli"
```

The version is read dynamically from package metadata via `importlib.metadata.version("oct")` in `oct/__init__.py`.

**Source:** `oct/__init__.py`, `pyproject.toml`

---

## 2. Project Root Detection

OCT locates the project root by walking upward from the current working directory. The algorithm, implemented in `find_project_root()`, is:

1. **Check for `.octrc.json` root marker** — If a `.octrc.json` file exists at the current level and contains `"root_marker": true`, that directory is the project root.

2. **Check for required directories** — A directory is the project root if it contains all three of:
   - `docs/`
   - `tests/`
   - `oc_diagnostics/` (or legacy `diagnostics/`)

3. **Legacy fallback** — If `diagnostics/` is found but `oc_diagnostics/` is not, a deprecation warning is emitted. `oc_diagnostics/` takes priority when both exist.

4. **`--root-dir` override** — The global `--root-dir DIR` flag bypasses auto-detection entirely, allowing OCT to operate on any directory.

The `get_project_root()` helper checks for the `--root-dir` Click context override first, then falls back to `find_project_root()`.

**Source:** `oct/core/project_root.py`

---

## 3. CLI Commands — Complete Reference

All commands are defined in `oct/cli.py` using Click. Global options (`--root-dir`) must appear before the subcommand name.

### 3.1 oct lint

**Static compliance analysis** of Python source files.

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

#### Flags

| Flag | Description |
|------|-------------|
| `--fix-headers` | Rewrite malformed shebang, encoding, and file identity headers. Originals archived to `.linter_archive/<name>.<timestamp>.bak`. |
| `--dry-run` | Preview changes without writing. When combined with `--fix-headers`, violations are logged but no files modified. |
| `--json` | Emit structured JSON to stdout instead of colorized terminal output. |
| `--jobs N` / `-j N` | Parallel workers (default: 1). Forced to 1 when `--fix-headers` is active. |
| `--changed` | Lint only git-modified `.py` files (staged + unstaged). Overrides explicit PATH targets. |
| `PATH ...` | Files or directories to lint. Defaults to entire project. |

#### Checks Performed

| Check | Function | Description |
|-------|----------|-------------|
| `header` | `validate_header_block()` | Lines 1–4: shebang, encoding, file identity, blank line. |
| `docstring` | `check_docstring()` | Module docstring with Purpose, Responsibilities, Diagnostics, Contracts sections. |
| `diagnostics_profile` | `check_diagnostics_profile()` | Diagnostics section has Domain, L2, L3, L4 definitions. Scoped to module docstring. |
| `dbg_usage` | `check_dbg_usage()` | Non-trivial files (>20 lines) must call `_dbg()`. AST-verified. |
| `dbg_import` | `check_dbg_import()` | Non-trivial files must have `from oc_diagnostics import _dbg`. No aliases. |
| `func_pattern` | `check_func_pattern()` | Functions calling `_dbg()` must define `func = "name"` as first non-docstring statement. |
| `syntax_warnings` | `check_syntax_warnings()` | Detects invalid escape sequences and other syntax warnings. |
| `no_hardcoded_secrets` | `check_no_hardcoded_secrets()` | AST-based detection of string literals assigned to secret-like variable names, dict literals with secret keys, and function defaults with secret parameters (§6b). Blocking at `compact`/`strict`; disabled in `proto`. |
| `tests_exist` | `check_tests_exist()` | Heuristic: `test_<stem>.py` exists or a test file imports the module. |

**Project-level checks** (always run): presence of `docs/ARCHITECTURE.md`, `tests/run_tests.py`, `tests/Tests_README.md`, `oc_diagnostics/debug_config.json`.

#### Excluded Directories

Defined in `oct/core/exclusions.py`:

**Exact match (linter):**
`.git`, `__pycache__`, `Old`, `old`, `.linter_archive`, `copied_python_files`, `data`, `data_raw`, `raw_data`, `flow_charts`, `dot_files`, `dev-tools`, `Code Reviews`

**Wildcard (substring) match:**
`cache`, `_source`, `_skeleton`, `logs`, `_exports`, `_build`

Additionally, OCT's own package directory is always excluded.

#### JSON Output Schema

```json
{
  "project": "project-name",
  "total_files": 42,
  "fully_compliant": 38,
  "compliance_pct": 90.5,
  "fixed_files": 0,
  "checks": {
    "header": {"pass": 40, "total": 42, "pct": 95.2},
    "docstring": {"pass": 39, "total": 42, "pct": 92.9},
    ...
  },
  "files": [
    {
      "path": "src/module.py",
      "checks": {
        "header": {"pass": true, "message": "OK"},
        "docstring": {"pass": false, "message": "Missing sections: Contracts"},
        ...
      },
      "compliant": false
    }
  ]
}
```

#### Rule Profiles

Configured via `.octrc.json` (see [Section 4.1](#41-octrcjson--linter-configuration)).

| Profile | header | docstring | diagnostics_profile | dbg_usage | dbg_import | func_pattern | tests_exist |
|---------|--------|-----------|---------------------|-----------|------------|--------------|-------------|
| `default` | yes | yes | yes | yes | yes | yes | yes |
| `strict` | yes | yes | yes | yes | yes | yes | yes |
| `minimal` | yes | yes | no | no | no | no | no |

Per-rule overrides in `.octrc.json` take priority over profile defaults.

#### Log Files

Every lint run writes a timestamped log to `logs/oct_lint_output-<YYYYMMDD-HHMMSS>.txt`. Old logs are rotated automatically (max 10 files kept).

**Source:** `oct/linter/oct_lint.py`

---

### 3.2 oct format

**Auto-fix Option C compliance violations** while preserving code semantics.

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

#### Flags

| Flag | Description |
|------|-------------|
| `--fix` | Apply formatting changes. Without this, only reports what would change (dry-run is default). |
| `--dry-run` | Report what would change without modifying files. Default behavior without `--fix`. |
| `--json` | Machine-readable JSON output. |
| `--verbose` | Per-file details in addition to summary. |

#### Fix Pipeline

Fixes are applied in this order:

| Step | Function | What it fixes |
|------|----------|---------------|
| 1 | `fix_header_block()` | Rewrites malformed shebang, encoding, file identity, blank line. |
| 2 | `fix_docstring()` | Inserts missing docstring skeleton or appends missing sections to existing docstrings. |
| 3 | `fix_dbg_import()` | Adds `from oc_diagnostics import _dbg`. Removes aliased/incorrect imports. |
| 4 | `fix_func_pattern()` | Inserts `func = "name"` in functions that call `_dbg()`. |

#### Safety & Archival

- Originals archived to `.formatter_archive/<name>.<timestamp>.bak` before modification.
- All code below headers is preserved exactly.
- Each fixer is idempotent (running twice produces the same result as once).
- Files are never modified unless `--fix` is explicitly passed.
- Trivial files (<20 lines) skip `dbg_import` and `func_pattern` fixes.

**Source:** `oct/formatter/oct_format.py`

---

### 3.3 oct new

**Generate a new Option C-compliant Python file.**

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

#### Arguments & Flags

| Argument/Flag | Description |
|---------------|-------------|
| `PATH` | Target file path (relative or absolute). Parent directories created automatically. Must be `.py`. |
| `--force` | Overwrite existing file. |
| `--test` | Also generate companion test file at `tests/test_<name>.py`. |
| `--dry-run` | Show what would be created without writing. |
| `--verbose` | Show the generated file content. Works with or without `--dry-run`. |

#### Generated Module File

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

from oc_diagnostics import _dbg

"""
Purpose
-------
Describe the purpose of this module.

Responsibilities
----------------
- List the responsibilities of this module.

Diagnostics
-----------
Domain: <DOMAIN>
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing

Contracts
---------
- State the contracts and guarantees of this module.
"""
```

#### Generated Test File (with `--test`)

```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/test_<name>.py

"""
Purpose
-------
Unit tests for <name>.
...
"""

from <dotted.import.path> import *


def test_<name>_placeholder():
    """Placeholder test — replace with real tests."""
    assert True
```

#### Package Markers

When creating a file in a new subdirectory, `__init__.py` files are automatically created in all intermediate directories up to the project root.

**Source:** `oct/generator/new_python_file.py`

---

### 3.4 oct scaffold

**Create a complete Option C project skeleton.**

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

#### Arguments & Flags

| Argument/Flag | Description |
|---------------|-------------|
| `NAME` | Project directory name (created in current working directory). |
| `--dry-run` | Show what would be created without writing. |

#### Created Structure

```
NAME/
├── docs/
│   ├── ARCHITECTURE.md
│   └── doxygen_work_dir/
│       └── Doxyfile                 # Copied from OCT template, PROJECT_NAME set
├── tests/
│   ├── run_tests.py                 # Executable test runner stub
│   └── Tests_README.md
├── oc_diagnostics/
│   └── debug_config.json            # Pre-configured oc_diagnostics template
├── logs/
└── docs/doxygen_output/
```

The `debug_config.json` template contains:
- Schema version `"1.5"`
- One domain: `GENERAL` at level 2
- All global settings with sensible defaults

A Doxyfile template is copied from `oct/templates/Doxyfile` (or fallback from OCT's own `docs/doxygen_work_dir/Doxyfile`) with `PROJECT_NAME` set to the scaffold name.

An `oc_diagnostics` compatibility check runs at scaffold time (warning-only).

**Source:** `oct/cli.py` (scaffold command)

---

### 3.5 oct docs

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

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

#### Flags

| Flag | Description |
|------|-------------|
| `--sphinx` | Generate Sphinx HTML documentation. Discovers markdown in `docs/`, generates API reference via `sphinx-apidoc`, writes `index.rst`, runs `sphinx-build`. Output: `docs/html/`. |
| `--doxygen` | Generate Doxygen HTML documentation. Locates `docs/doxygen_work_dir/Doxyfile`, creates a temp copy with `INPUT` patched to the actual project root, runs `doxygen`. Output: `docs/doxygen_output/`. |
| `--all` | Run both `--sphinx` and `--doxygen` pipelines sequentially. Returns 0 only if both succeed. |
| `--clean` | Remove generated documentation artifacts from `docs/`: `html/`, `doctrees/`, `_api/`, `doxygen_output/`, `index.rst`, `dependencies.rst`. Preserves `_sphinx/`, `_static/`, `_templates/`, `doxygen_work_dir/`, and user-authored `.md` files. |
| `--dry-run` | Preview what `--clean` would remove without deleting. Only meaningful with `--clean`. |

Without any flags, validates presence of required documentation files:

| File | Location |
|------|----------|
| Architecture document | `docs/ARCHITECTURE.md` |
| Test documentation | `tests/Tests_README.md` |
| Debug configuration | `oc_diagnostics/debug_config.json` (or `diagnostics/debug_config.json`) |

#### Sphinx Pipeline Details

1. Check Sphinx dependencies (`sphinx`, `sphinx_book_theme`, `myst_parser`, `sphinxcontrib.mermaid`, `sphinx_copybutton`).
2. Set up `docs/_sphinx/conf.py` from template (one-time, only if absent).
3. Discover markdown files in `docs/`, ordered by `_PRIORITY_DOCS`.
4. Generate API reference via `sphinx-apidoc` for discovered Python packages.
5. Generate dependency graph via `oct deps` (Mermaid).
6. Write `index.rst` with all discovered content.
7. Run `sphinx-build -M html`.

#### Doxygen Pipeline Details

1. Check `doxygen` is installed via `shutil.which()`.
2. Locate `docs/doxygen_work_dir/Doxyfile`.
3. Create temp copy with `INPUT` patched to project root (forward slashes for cross-platform compatibility).
4. Run `doxygen` on the temp copy.
5. Clean up temp Doxyfile.

**Source:** `oct/docs/oct_docs.py`, `oct/cli.py`

---

### 3.6 oct test

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

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

All arguments are forwarded to pytest. Exits with pytest's return code.

#### Single-project mode

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

#### Meta-project mode

When the project root has no test suite of its own (no `tests/` directory and no pytest config), `oct test` scans immediate sub-directories for those that have **both** a `tests/` directory and a pytest config file. Each qualifying sub-project's tests are run independently in the correct working directory, avoiding import collisions that would occur from running pytest across the entire tree. Results are aggregated; exits non-zero if any sub-project fails.

A sub-directory must have both `tests/` **and** a pytest config to qualify — this avoids false positives from directories that happen to contain a `tests/` folder but are not proper test suites (e.g. scaffold templates).

**Source:** `oct/cli.py` (`_run_pytest`, `test` command)

---

### 3.7 oct export-source

**Consolidate source files into readable text files** for review, archiving, or analysis.

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

#### Arguments & Flags

| Argument/Flag | Description |
|---------------|-------------|
| `PATH` | Root directory to export from. Defaults to auto-detected project root (see [§2](#2-project-root-detection)). |
| `--verbose` | Per-file line/word/byte statistics. |
| `--clean` | **Deprecated** (use `oct clean`). Remove `_source_code-*` directories. |
| `--single-dir` | Write all output into one root-level directory instead of per-directory folders. |

#### Included File Types

Organized by profile:

| Profile | Extensions |
|---------|------------|
| Python | `.py` |
| Web | `.js`, `.ts`, `.tsx`, `.css`, `.html` |
| JVM | `.java`, `.kt` |
| Systems | `.rs`, `.go`, `.cpp`, `.c`, `.h`, `.hpp` |
| Config | `.json`, `.yaml`, `.yml`, `.toml`, `.ini`, `.xml` |
| Docs | `.md` |
| Scripts | `.sh`, `.bat`, `.ps1`, `.ahk` |
| Misc | `.npmignore`, `.gitignore`, `.sql`, `.rb`, `.swift` |

#### Excluded Directories (exporter)

Same common set as linter, plus: `dataset_library`, `doxygen_work_dir`, `doxygen_output`, `logs`, `cache`, `_backup`, `old_backup`, `.venv`, `.claude`, `.git`.

#### Excluded Files (§6b Secret Hygiene)

Defined in `oct/core/exclusions.py` as `NEVER_EXPORT_FILE_PATTERNS`:

`.env`, `.env.*`, `*.pem`, `*.key`, `credentials.json`, `secrets.json`, `secrets.yaml`, `secrets.yml`

These files are excluded regardless of extension profile. See §6b of the Master Coding Style Specification.

#### Output Structure

Per-directory `_source_code-<YYYYMMDD-HHMM>/` folders containing:
- `_source.<dotpath>.txt` — files from each directory
- `_full_source.<root>.txt` — all files combined

#### I/O Error Handling

- Never crashes on recoverable I/O errors (permissions, path too long).
- Skips problematic directories/files with warnings.
- Windows long-path: truncates dotpath and appends 8-character MD5 hash when path exceeds 240 characters.

**Source:** `oct/tools/source_exporter.py`

---

### 3.8 oct export-skeleton

**Export structural skeletons** of source files for AI inspection or code review.

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

#### Arguments & Flags

| Argument/Flag | Description |
|---------------|-------------|
| `PATH` | Root directory to export from. Defaults to auto-detected project root (see [§2](#2-project-root-detection)). |
| `--verbose` | Per-file line/word/byte statistics. |
| `--single-dir` | Write all output into one root-level directory. |
| `--no-diagnostics` | Omit the Diagnostics section from module docstrings. |
| `--clean` | Remove all `_skeleton_code-*` directories and exit. |

#### Skeleton content (Python files)

- Lines 1-3 (header block)
- Module docstring (filtered if `--no-diagnostics`)
- Class definitions with bases, decorators, class docstrings
- Function/method signatures with type hints, decorators, docstrings
- Module-level constants (`ALL_CAPS` names) as `NAME = ...`
- `...` as body placeholder — no implementation bodies

#### Skeleton content (non-Python files)

One-line placeholder: `# [filename.ext] N lines, X.X KB`

#### Output Structure

Per-directory `_skeleton_code-<YYYYMMDD-HHMM>/` folders containing:
- `_skeleton.<dotpath>.txt` — skeletons from each directory
- `_full_skeleton.<root>.txt` — all skeletons combined

Uses the same config, exclusions, path safety, and I/O error handling as `oct export-source`.

**Source:** `oct/tools/skeleton_exporter.py`

---

### 3.9 oct clean

**Remove build artifacts.**

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

| Argument/Flag | Description |
|---------------|-------------|
| `PATH` | Directory to clean. Defaults to current working directory. |
| `--dry-run` | Show what would be deleted without deleting. |

Removes recursively:
- `_source_code-*` export directories
- `_skeleton_code-*` skeleton directories
- `__pycache__` directories

No Option C project structure required — works on any directory.

**Source:** `oct/tools/source_exporter.py`, `oct/tools/skeleton_exporter.py`

---

### 3.10 oct health

**Project compliance dashboard.**

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

#### Flags

| Flag | Description |
|------|-------------|
| `--json` | Machine-readable JSON output. |
| `--verbose` | Per-file lint breakdown. |

#### Sections

| Section | What it checks |
|---------|----------------|
| **Lint Compliance** | Runs all linter checks, reports per-check pass rates and overall compliance %. |
| **Fixable Violations** | Counts violations `oct format --fix` could auto-fix (header, docstring, dbg_import, func_pattern). |
| **Documentation** | Checks for `ARCHITECTURE.md`, `Tests_README.md`, `run_tests.py`, `debug_config.json`. |
| **Tests** | Runs pytest subprocess (120s timeout), captures pass/fail/skip counts and error details. |
| **oc_diagnostics** | Checks installation and version compatibility (range: >=1.5.0, <2.0.0). |

#### JSON Output Schema

```json
{
  "project": "project-name",
  "oct_version": "0.9.1",
  "timestamp": "2026-03-08T12:00:00",
  "lint": {
    "total_files": 42,
    "fully_compliant": 38,
    "compliance_pct": 90.5,
    "checks": {
      "header": {"pass": 40, "total": 42, "pct": 95.2},
      ...
    },
    "files": [...]
  },
  "fixable": {
    "header": 2, "docstring": 1, "dbg_import": 0, "func_pattern": 1, "total": 4
  },
  "docs": {
    "total_required": 4,
    "total_present": 4,
    "files": [{"name": "ARCHITECTURE.md", "present": true}, ...]
  },
  "tests": {
    "status": "pass|fail|timeout|error|not_run",
    "exit_code": 0,
    "summary": "42 passed in 1.23s",
    "details": []
  },
  "compat": {
    "installed": true,
    "version": "1.5.0",
    "compatible": true,
    "message": ""
  }
}
```

**Source:** `oct/health/oct_health.py`

---

### 3.11 oct diag

**oc_diagnostics configuration management tools.** Operates purely on the JSON config file — does **not** import `oc_diagnostics` at runtime.

```
oct diag <subcommand>
```

#### `oct diag validate-config`

Validates `debug_config.json` against expected schema. Reports:

| Check | Severity | Condition |
|-------|----------|-----------|
| File existence | ERROR | Config file not found |
| Valid JSON | ERROR | JSON parse failure |
| Root type | ERROR | Root must be a JSON object |
| `_schema_version` | WARNING | Key missing |
| `domains` | WARNING/ERROR | Missing key, or not a dict, or entries with invalid level |
| Domain levels | ERROR | Level not an integer 0–4 |
| `global_settings` | WARNING/ERROR | Missing key, or not a dict |
| `output_mode` | WARNING | Must be `terminal`/`file`/`both`/`json` |
| `mode` | WARNING | Must be `dev`/`prod` |

#### `oct diag list-domains`

Lists all configured domains in a formatted table:

```
Domain                   Level    Color
--------------------------------------------
GENERAL                  2        default
API                      3        cyan
```

#### `oct diag set-level DOMAIN LEVEL`

Updates a domain's debug level in-place:
- Validates level is 0–4
- Validates domain exists in config
- Writes back with `json.dumps(indent=2)` + trailing newline

#### Config File Location

`_find_config()` checks:
1. `<project_root>/oc_diagnostics/debug_config.json` (preferred)
2. `<project_root>/diagnostics/debug_config.json` (legacy fallback)

**Source:** `oct/diag/oct_diag.py`

---

### 3.12 oct git status

Show the current git repository state with Option C compliance annotations.

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

| Flag | Description |
|------|-------------|
| `--json` | Output structured JSON instead of colorized terminal report |
| `--verbose` | Show per-file lint status for staged files |

Displays branch name, clean/dirty state, staged/unstaged file counts with OCT lint status annotations. Includes hook installation state and protected-branch warnings.

**Source:** `oct/git/oct_git.py`

---

### 3.13 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 when in a git repo) |
| `--all` | Check all Python files in the project |
| `--profile` | Override lint profile: `proto`, `compact` (default), `strict` |
| `--fix` | Apply auto-fixes for format violations |
| `--include-tests` | Also run the test suite as part of the gate |
| `--json` | Output structured JSON with counts and exit code |

#### Exit codes

| Code | Meaning |
|------|---------|
| 0 | All checks passed |
| 1 | Lint violations |
| 2 | Format violations |
| 3 | Lint + format violations |
| 4 | Test failures |
| 5 | Secrets detected |

**Source:** `oct/git/oct_git.py`, `oct/git/quality_gate.py`

---

### 3.14 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 |

Actions performed:

- Creates or merges `.gitignore` with Option C patterns (bounded by `# --- Option C START ---` / `# --- Option C END ---` markers)
- Creates `.gitattributes` with sane defaults (line endings, binary detection, diff drivers)
- Generates `.github/workflows/oct-ci.yml` GitHub Actions workflow (unless `--skip-workflow`)

**Source:** `oct/git/oct_git.py`

---

### 3.15 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 are still checked (non-bypassable).** |
| `--no-verify` | Forward `--no-verify` to git (skip git hooks). OCT's own checks still run. |
| `--profile` | Override lint profile: `proto`, `compact`, `strict` |
| `--json` | Output structured JSON with exit code, message, branch, errors |

#### Exit codes

| Code | Meaning |
|------|---------|
| 0 | Commit succeeded |
| 1 | Quality check violations (aborted) or protected-branch blocked |
| 2 | Secrets detected (aborted, **non-bypassable**) |
| 3 | Commit message validation failed |
| 4 | Nothing to commit (no staged files) or git commit failed |

#### Pre-flight checks (in order)

1. **Message validation** — Validates Conventional Commits format (type, scope, subject rules)
2. **Staged file check** — Verifies at least one file is staged
3. **Protected-branch guard** — On `main`/`master`, forces strict profile; blocks direct commits in strict mode
4. **Quality gate** — Runs lint + format + secrets on staged files
5. **Secrets enforcement (G-D4)** — Secrets findings always exit 2, regardless of `--force` or `--no-verify`
6. **Large-file advisory** — Files > 10 MB trigger a warning (non-blocking)
7. **Advisory checks** — Warns if ARCHITECTURE.md or CHANGELOG.md not staged when relevant

#### Conventional Commits format

```
<type>(<scope>): <subject>
```

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

Rules:
- Subject must start with lowercase letter
- Subject must not end with period
- First line must be <= 72 characters
- `!` after scope indicates breaking change (e.g., `feat!: remove old API`)

**Source:** `oct/git/oct_git.py`, `oct/git/conventional.py`

---

### 3.16 oct git hooks

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

#### `oct git hooks install`

```
oct git hooks install [--force]
```

| Flag | Description |
|------|-------------|
| `--force` | Overwrite existing `.pre-commit-config.yaml` |

Generates `.pre-commit-config.yaml` with four hooks:

| Hook ID | Stage | Description |
|---------|-------|-------------|
| `oct-quality-gate` | pre-commit | Runs `oct git check --staged-only` |
| `oct-secrets-check` | pre-commit | Runs secrets detection (`always_run: true`) |
| `oct-commit-msg` | commit-msg | Validates Conventional Commits format |
| `oct-pre-push` | pre-push | Runs full quality gate including tests |

#### `oct git hooks status`

```
oct git hooks status
```

Reports `[INSTALLED]` or `[MISSING]` for each of the four hook types.

#### `oct git hooks remove`

```
oct git hooks remove
```

Removes OCT hooks from `.pre-commit-config.yaml`. Preserves any non-OCT hooks. Deletes the file entirely if only OCT hooks were present.

**Deprecation note:** The legacy `oct install-hooks` command still works but prints a deprecation notice and delegates to `oct git hooks install`.

**Source:** `oct/git/oct_git.py`

---

## 4. Configuration

### 4.1 .octrc.json — Linter Configuration

Place a `.octrc.json` file in the project root to customize linter behavior.

#### Full Schema

```json
{
  "root_marker": false,
  "linter": {
    "profile": "default",
    "exclude_dirs_add": [],
    "exclude_dirs_remove": [],
    "wildcard_exclude_add": [],
    "rules": {
      "header": true,
      "docstring": true,
      "diagnostics_profile": true,
      "dbg_usage": true,
      "dbg_import": true,
      "func_pattern": true,
      "tests_exist": true
    }
  }
}
```

| Key | Type | Description |
|-----|------|-------------|
| `root_marker` | bool | If `true`, this directory is treated as the project root (bypasses docs/tests/oc_diagnostics detection). |
| `linter.profile` | string | Rule profile: `"default"`, `"strict"`, or `"minimal"`. |
| `linter.exclude_dirs_add` | list[str] | Add directory names to exact-match exclusion list. |
| `linter.exclude_dirs_remove` | list[str] | Remove directory names from default exclusion list. |
| `linter.wildcard_exclude_add` | list[str] | Add substring patterns to wildcard exclusion list. |
| `linter.rules` | dict[str, bool] | Per-rule overrides. Takes priority over profile. |

#### Available Rule Names

`header`, `docstring`, `diagnostics_profile`, `dbg_usage`, `dbg_import`, `func_pattern`, `tests_exist`

#### Profiles

- **`default`** / **`strict`**: All rules enabled.
- **`minimal`**: Only `header` and `docstring` enabled.

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

### 4.2 .octrc.json — Git Configuration

The `.octrc.json` file also supports git-related settings:

```json
{
  "git": {
    "protected_branches": ["main", "master", "release/*"],
    "large_file_threshold_mb": 10
  }
}
```

| Key | Default | Description |
|-----|---------|-------------|
| `git.protected_branches` | `["main", "master"]` | Branch patterns where strict profile is enforced and direct commits are blocked |
| `git.large_file_threshold_mb` | `10` | Size threshold (MB) for large-file advisory warnings during `oct git commit` |

### 4.3 _oct_exporter_config.json — Exporter Configuration

Place a `_oct_exporter_config.json` file in the project root to customize the source exporter. Supports add/remove/replace semantics for:
- `include_extensions`
- `exclude_dirs`
- `wildcard_exclude_dirs`

#### Config Resolution Order

The exporter searches for `_oct_exporter_config.json` in three tiers:

1. **Project root** — A config file in the auto-detected project root (or explicit `PATH` argument) takes highest priority.
2. **OCT bundled default** — If no project-level config is found, the exporter falls back to oct's own `_oct_exporter_config.json` (located in the oct package root). A note is printed to stderr when this fallback is used.
3. **Built-in defaults** — If neither file exists (e.g. oct is installed as a standalone package without the bundled config), hardcoded defaults from `oct/core/exclusions.py` are used. A warning is printed to stderr.

This ensures that oct's comprehensive exclusion list (`.venv`, `.claude`, `.git`, AI tool directories, etc.) is always applied even when a project does not ship its own config file.

**Source:** `oct/tools/source_exporter.py`

---

## 5. Option C Compliance Rules

Every Python file in an Option C project must satisfy these rules, enforced by `oct lint` and auto-fixable by `oct format`.

### 5.1 Header Block (3-line + blank)

Lines 1–4 of every `.py` file:

```python
#!/usr/bin/env python3          # Line 1: shebang
# -*- coding: utf-8 -*-         # Line 2: encoding declaration
# relative/path/to/file.py     # Line 3: file identity (relative to project root)
                                # Line 4: mandatory blank line
```

The file identity path is computed by `expected_path_header()`: the file's path relative to the project root, in POSIX format.

### 5.2 Module Docstring (4 sections)

A top-level `"""..."""` docstring with four named sections:

1. **Purpose** — What this module does and why it exists.
2. **Responsibilities** — Bullet list of what this module owns.
3. **Diagnostics** — Domain name and L2/L3/L4 level definitions.
4. **Contracts** — Inputs, outputs, preconditions, postconditions.

### 5.3 Diagnostics Profile

Within the module docstring's Diagnostics section:

```
Diagnostics
-----------
Domain: DOMAIN_NAME
Levels:
    L2 — summary-level events
    L3 — detailed workflow events
    L4 — verbose trace events
```

Must contain the keywords: `Diagnostics`, `Domain:`, `L2`, `L3`, `L4`.

### 5.4 `_dbg` Import and Usage

Non-trivial files (>20 lines) must:

1. Import: `from oc_diagnostics import _dbg` (canonical form, no aliases)
2. Usage: At least one `_dbg()` call (verified via AST)

### 5.5 `func = "..."` Pattern

Every function that calls `_dbg()` must define `func = "function_name"` as its first non-docstring statement:

```python
def process_data(items):
    func = "process_data"
    _dbg("L2", "Processing started", domain="CORE", func=func)
```

Checked per-function body; nested functions are checked independently.

### 5.6 Syntax Warnings

Detects Python syntax warnings (e.g., invalid escape sequences like `'\.'` instead of `r'\.'`). These will become `SyntaxError` in a future Python version.

### 5.7 Regression Tests Heuristic

Two-stage check:
1. **Naming convention** — `test_<stem>.py` exists anywhere under `tests/`.
2. **Import statement** — Any `.py` file in `tests/` contains a whole-word import of the module stem.

### 5.8 Project-Level Files

Required files checked at project level:
- `docs/ARCHITECTURE.md`
- `tests/run_tests.py`
- `tests/Tests_README.md`
- `oc_diagnostics/debug_config.json` (or `diagnostics/debug_config.json`)

---

## 6. Linter Internals

### 6.1 LinterContext

```python
@dataclass
class LinterContext:
    project_root: Path        # Resolved project root
    project_name: str         # project_root.name
    diagnostics_dir: Path     # oc_diagnostics/ or diagnostics/
    tests_dir: Path           # <root>/tests
    docs_dir: Path            # <root>/docs
    log_handle: Any = None    # Open log file handle
    log_path: Path | None     # Path to current log file
    log_lock: Lock            # Thread lock for parallel logging
```

### 6.2 Check Functions

All check functions return `(ok: bool, message: str)` tuples.

| Function | What it validates |
|----------|-------------------|
| `validate_header_block(lines, path, ctx)` | 4-line header block correctness |
| `check_docstring(text)` | Module docstring with 4 required sections |
| `check_diagnostics_profile(text)` | Domain + L2/L3/L4 in module docstring |
| `check_dbg_usage(text, tree=None)` | At least one `_dbg()` call (AST-verified) |
| `check_dbg_import(text, tree=None)` | Canonical `from oc_diagnostics import _dbg` |
| `check_func_pattern(text, tree=None)` | `func = "name"` before `_dbg()` in each function |
| `check_syntax_warnings(text, warnings_list=None)` | Python syntax warnings |
| `check_no_hardcoded_secrets(text, tree=None)` | String literals assigned to secret-like variable names, dict keys, or function defaults (§6b) |
| `check_tests_exist(module_path, ctx)` | Regression test presence (naming + import) |

### 6.3 Header Auto-Fix

`fix_header_block(path, text, ctx)`:
1. Archives original to `.linter_archive/<name>.<YYYYMMDD-HHMMSS>.bak`
2. Computes header boundary via `_header_boundary()` (scans shebang, encoding, identity, blank line in strict order)
3. Writes corrected 4-line header + remaining content

`preview_header_fix(path, ctx)` returns the corrected header without writing.

### 6.4 File Discovery

`find_python_files(root, exclude_dirs, wildcard_exclude_dirs)`:
- Yields all `.py` files under root via `rglob("*.py")`
- Excludes OCT's own package directory
- Excludes directories matching exact or wildcard patterns

`is_excluded_dir(path, exclude_dirs, wildcard_exclude_dirs)`:
- Returns `True` if directory name is in exact-match set OR contains any wildcard substring.

`_git_changed_files(root)`:
- Uses `git diff --name-only --diff-filter=ACMR HEAD` for unstaged changes
- Uses `git diff --name-only --diff-filter=ACMR --cached` for staged changes
- Falls back to `git status --porcelain -uall` for fresh repos with no HEAD
- Returns combined, deduplicated list of `.py` paths
- Returns empty list on timeout (10s) or if git is not available

### 6.5 Output Formats

**Terminal:** Colorized output with ANSI codes (auto-detected on Windows). Per-check pass rates as percentages, per-file results.

**JSON:** Structured output with project name, total files, per-check statistics, and per-file check results.

**Log file:** Plain text written to `logs/oct_lint_output-<YYYYMMDD-HHMMSS>.txt`. Max 10 log files retained.

### 6.6 Parallel Processing

`--jobs N` uses `concurrent.futures.ThreadPoolExecutor`. Each file is processed by `_lint_single_file()` which is thread-safe (uses `ctx.log_lock` for log writes). Forced to sequential (`jobs=1`) when `--fix-headers` is active.

**Source:** `oct/linter/oct_lint.py`

---

## 7. Formatter Internals

### 7.1 FormatterContext

```python
@dataclass
class FormatterContext:
    project_root: Path
    project_name: str
    diagnostics_dir: Path
    tests_dir: Path
    docs_dir: Path
    fix_mode: bool          # Actually apply changes
    dry_run_mode: bool      # Report-only mode
    json_mode: bool         # JSON output
    verbose: bool           # Per-file details
```

### 7.2 Fix Functions

All fix functions return `(changed: bool, new_text: str, messages: list[str])`.

| Function | Action |
|----------|--------|
| `fix_header_block()` | Reconstructs correct 4-line header, preserving content below. |
| `fix_docstring()` | Inserts complete skeleton if missing; appends missing sections if incomplete. |
| `fix_dbg_import()` | Adds canonical import after header. Removes incorrect/aliased imports. |
| `fix_func_pattern()` | Inserts `func = "name"` before first statement in functions with `_dbg()` calls. |

### 7.3 Processing Pipeline

1. For each `.py` file, apply fixers in sequence: header → docstring → import → func_pattern.
2. If any fixer changed the text and `fix_mode` is True, archive original and write new text.
3. Collect per-file results for summary/JSON output.

### 7.4 Template Constants

```python
SHEBANG = "#!/usr/bin/env python3"
ENCODING = "# -*- coding: utf-8 -*-"
IMPORT_BLOCK = "from oc_diagnostics import _dbg\n"
DOCSTRING_SKELETON = '"""\nPurpose\n-------\n...\n"""'
```

Missing section templates: `MISSING_DOCSTRING_SECTIONS` dict with text for Purpose, Responsibilities, Diagnostics, Contracts.

**Source:** `oct/formatter/oct_format.py`

---

## 8. Generator Internals

### 8.1 Template Constants

```python
SHEBANG = "#!/usr/bin/env python3"
ENCODING = "# -*- coding: utf-8 -*-"
IMPORT_BLOCK = "from oc_diagnostics import _dbg\n\n"
```

**`DOCSTRING_TEMPLATE`** — Standard module docstring with Purpose, Responsibilities, Diagnostics (Domain + L2/L3/L4), Contracts.

**`TEST_DOCSTRING_TEMPLATE`** — Test module docstring with Domain: TESTS.

**`TEST_BODY_TEMPLATE`** — Import line + placeholder test function.

### 8.2 Helper Functions

`_make_header(rel_posix)`: Builds the 4-line header block from a relative POSIX path.

`_derive_import_path(rel_posix)`: Converts `path/to/module.py` → `path.to.module` for import statements.

### 8.3 File Generation Logic

`create_new_file(project_root, path, force, dry_run, test)`:
1. Resolves target path (absolute or relative to project root).
2. Validates `.py` extension and target is inside project root.
3. Checks for existing files (refuses without `--force`).
4. Creates parent directories and `__init__.py` package markers.
5. Writes header + import block + docstring template.
6. If `test=True`: generates companion test file at `tests/test_<stem>.py` with header, docstring, import, and placeholder test.

**Source:** `oct/generator/new_python_file.py`

---

## 9. Health Dashboard Internals

### 9.1 Check Functions

| Function | Returns |
|----------|---------|
| `check_lint_health(project_root, ctx, verbose)` | Dict with total_files, fully_compliant, compliance_pct, per-check counters, optional file details |
| `check_fixable_health(project_root, ctx)` | Dict with fixable counts per category (header, docstring, dbg_import, func_pattern, total) |
| `check_docs_health(project_root)` | Dict with total_required, total_present, per-file status |
| `check_test_health(project_root)` | Dict with status, exit_code, summary, details. Runs pytest subprocess with 120s timeout |
| `check_compat_health()` | Dict with installed, version, compatible, message |

### 9.2 oc_diagnostics Compatibility

Defined in `oct/core/compat.py`:

```python
_OC_DIAGNOSTICS_COMPAT = {"min": "1.5.0", "max": "2.0.0"}
```

Uses `importlib.metadata.version("oc_diagnostics")` to check installed version. Tuple-based comparison (no `packaging` dependency required).

**Source:** `oct/health/oct_health.py`, `oct/core/compat.py`

---

## 10. Diagnostics Config Tools Internals

### 10.1 Constants

```python
VALID_LEVELS = {0, 1, 2, 3, 4}

EXPECTED_GLOBAL_KEYS = {
    "silent_mode", "enable_timestamps", "enable_colors", "include_filename",
    "output_mode", "instrumentation_enabled", "max_log_files", "max_log_size_mb",
    "instrumentation_allow_all", "mode", "http_redact_headers",
    "ui_event_properties", "structural_id_prefixes", "structural_id_exact",
}
```

### 10.2 Config Location

`_find_config(project_root)`:
1. Check `<root>/oc_diagnostics/debug_config.json`
2. Fall back to `<root>/diagnostics/debug_config.json`
3. Return oc_diagnostics path as default (for error messages)

### 10.3 Validation Rules

`validate_config()` checks:
- File exists and is readable
- Valid JSON
- Root is a dict
- `_schema_version` key present
- `domains` is a dict, each entry is a dict with integer level 0–4
- `global_settings` is a dict
- `output_mode` is one of: `terminal`, `file`, `both`, `json`
- `mode` is one of: `dev`, `prod`

### 10.4 set-level Behavior

`set_level(project_root, domain, level)`:
- Validates level 0–4
- Verifies domain exists in config
- Updates level in-place
- Writes back with `json.dumps(config, indent=2) + "\n"`

**Source:** `oct/diag/oct_diag.py`

---

## 11. Source Exporter Internals

### 11.1 Export Algorithm

1. Walk directory tree, collect source files matching included extensions.
2. Group files by directory.
3. For each directory, create `_source_code-<timestamp>/` and write `_source.<dotpath>.txt`.
4. Write `_full_source.<root>.txt` combining all directories.
5. Print summary with per-directory statistics.

### 11.2 Clean Functions

`clean_source_dirs(target, dry_run)`: Removes all `_source_code-*` directories recursively.

`clean_pycache_dirs(target, dry_run)`: Removes all `__pycache__` directories recursively.

### 11.3 Excluded Directories (exporter)

Defined in `oct/core/exclusions.py` as `EXPORTER_EXCLUDE_DIRS`:

Common set plus: `Code Reviews`, `dataset_library`, `doxygen_work_dir`, `doxygen_output`, `logs`, `cache`, `_backup`, `old_backup`.

### 11.4 Excluded Files (§6b Secret Hygiene)

Defined in `oct/core/exclusions.py` as `NEVER_EXPORT_FILE_PATTERNS`:

`.env`, `.env.*`, `*.pem`, `*.key`, `credentials.json`, `secrets.json`, `secrets.yaml`, `secrets.yml`

These file patterns are checked via `fnmatch` against every filename before inclusion. This is Layer 2 of the three-layer secret defence (DD-05). `.env` was also removed from the `config` extension profile to provide defence-in-depth at the extension level.

**Source:** `oct/tools/source_exporter.py`, `oct/core/exclusions.py`

---

## 12. oc_diagnostics Integration Points

OCT integrates with `oc_diagnostics` at multiple levels while maintaining a strict dev-time/runtime boundary — OCT never imports `oc_diagnostics` at runtime.

| OCT Command | Integration |
|-------------|-------------|
| `oct scaffold` | Generates `oc_diagnostics/debug_config.json` with a valid starter template |
| `oct new` | Adds `from oc_diagnostics import _dbg` to every generated file |
| `oct lint` | Checks for `_dbg()` usage, canonical import, diagnostics profile, and `debug_config.json` existence |
| `oct format` | Auto-fixes missing `_dbg` import and `func = "..."` pattern |
| `oct health` | Checks `oc_diagnostics` installation and version compatibility (>=1.5.0, <2.0.0) |
| `oct diag` | Validates, inspects, and updates `debug_config.json` (JSON-only, no imports) |

### oc_diagnostics Version Compatibility

OCT validates the installed `oc_diagnostics` version at lint and scaffold time:

- **Minimum:** 1.5.0
- **Maximum (exclusive):** 2.0.0

If `oc_diagnostics` is not installed, an informational message is shown (not an error — OCT itself does not require it).