OCT Reference

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#

OCT is installed as a local editable package:

pip install -e .

This registers the oct console script globally. The entry point is defined in pyproject.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:

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.
Check for required directories — A directory is the project root if it contains all three of:
- docs/
- tests/
- oc_diagnostics/ (or legacy diagnostics/)
Legacy fallback — If diagnostics/ is found but oc_diagnostics/ is not, a deprecation warning is emitted. oc_diagnostics/ takes priority when both exist.
--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#

{
  "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).

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#

#!/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`)#

#!/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#

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

Doxygen Pipeline Details#

Check doxygen is installed via shutil.which().
Locate docs/doxygen_work_dir/Doxyfile.
Create temp copy with INPUT patched to project root (forward slashes for cross-platform compatibility).
Run doxygen on the temp copy.
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).
`--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).
`--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#

{
  "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:

<project_root>/oc_diagnostics/debug_config.json (preferred)
<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)#

Message validation — Validates Conventional Commits format (type, scope, subject rules)
Staged file check — Verifies at least one file is staged
Protected-branch guard — On main/master, forces strict profile; blocks direct commits in strict mode
Quality gate — Runs lint + format + secrets on staged files
Secrets enforcement (G-D4) — Secrets findings always exit 2, regardless of --force or --no-verify
Large-file advisory — Files > 10 MB trigger a warning (non-blocking)
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#

{
  "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:

{
  "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:

Project root — A config file in the auto-detected project root (or explicit PATH argument) takes highest priority.
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.
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:

#!/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:

Purpose — What this module does and why it exists.
Responsibilities — Bullet list of what this module owns.
Diagnostics — Domain name and L2/L3/L4 level definitions.
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:

Import: from oc_diagnostics import _dbg (canonical form, no aliases)
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:

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:

Naming convention — test_<stem>.py exists anywhere under tests/.
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#

@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):

Archives original to .linter_archive/<name>.<YYYYMMDD-HHMMSS>.bak
Computes header boundary via _header_boundary() (scans shebang, encoding, identity, blank line in strict order)
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#

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

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

7.4 Template Constants#

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#

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):

Resolves target path (absolute or relative to project root).
Validates .py extension and target is inside project root.
Checks for existing files (refuses without --force).
Creates parent directories and __init__.py package markers.
Writes header + import block + docstring template.
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:

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

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):

Check <root>/oc_diagnostics/debug_config.json
Fall back to <root>/diagnostics/debug_config.json
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#

Walk directory tree, collect source files matching included extensions.
Group files by directory.
For each directory, create _source_code-<timestamp>/ and write _source.<dotpath>.txt.
Write _full_source.<root>.txt combining all directories.
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).

OCT Reference

Contents

OCT Reference#

Table of Contents#

1. Installation & Entry Point#

2. Project Root Detection#

3. CLI Commands — Complete Reference#

3.1 oct lint#

Flags#

Checks Performed#

Excluded Directories#

JSON Output Schema#

Rule Profiles#

Log Files#

3.2 oct format#

Flags#

Fix Pipeline#

Safety & Archival#

3.3 oct new#

Arguments & Flags#

Generated Module File#

Generated Test File (with --test)#

Package Markers#

3.4 oct scaffold#

Arguments & Flags#

Created Structure#

3.5 oct docs#

Flags#

Sphinx Pipeline Details#

Doxygen Pipeline Details#

3.6 oct test#

Single-project mode#

Meta-project mode#

3.7 oct export-source#

Arguments & Flags#

Included File Types#

Excluded Directories (exporter)#

Excluded Files (§6b Secret Hygiene)#

Output Structure#

I/O Error Handling#

3.8 oct export-skeleton#

Arguments & Flags#

Skeleton content (Python files)#

Skeleton content (non-Python files)#

Output Structure#

3.9 oct clean#

3.10 oct health#

Flags#

Sections#

JSON Output Schema#

3.11 oct diag#

oct diag validate-config#

oct diag list-domains#

oct diag set-level DOMAIN LEVEL#

Config File Location#

3.12 oct git status#

3.13 oct git check#

Exit codes#

3.14 oct git init#

3.15 oct git commit#

Exit codes#

Pre-flight checks (in order)#

Conventional Commits format#

3.16 oct git hooks#

oct git hooks install#

oct git hooks status#

oct git hooks remove#

4. Configuration#

4.1 .octrc.json — Linter Configuration#

Full Schema#

Available Rule Names#

Profiles#

4.2 .octrc.json — Git Configuration#

4.3 _oct_exporter_config.json — Exporter Configuration#

Config Resolution Order#

5. Option C Compliance Rules#

5.1 Header Block (3-line + blank)#

5.2 Module Docstring (4 sections)#

5.3 Diagnostics Profile#

5.4 _dbg Import and Usage#

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

`oct diag validate-config`#

`oct diag list-domains`#

`oct diag set-level DOMAIN LEVEL`#

`oct git hooks install`#

`oct git hooks status`#

`oct git hooks remove`#

5.4 `_dbg` Import and Usage#

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