OCT — Option C Tools

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#

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

pip install -e .

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

oct --help

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

Quick Start#

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

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

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

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

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

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

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

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#

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

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

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

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

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

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

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

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

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

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

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

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

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#

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

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:

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

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#

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#

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#

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

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

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

CI/CD integration#

# .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:

The original file is copied to .linter_archive/<filename>.<YYYYMMDD-HHMMSS>.bak.
The new file is written with corrected headers.
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:

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

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

Complete .octrc.json example with all keys:

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

OCT — Option C Tools

Contents

OCT — Option C Tools#

Table of Contents#

Installation#

Quick Start#

Project Structure Requirements#

Global Options#

Commands Reference#

oct lint#

Flags#

What it checks#

Output#

Example#

Excluded directories#

oct format#

Flags#

What it fixes#

Safety & Archival#

Examples#

oct new#

Arguments#

Flags#

Generated file structure#

Examples#

oct scaffold#

Arguments#

Flags#

What gets created#

Generated debug_config.json#

Example#

oct docs#

Flags#

Examples#

oct test#

Single-project mode#

Meta-project mode#

oct export-source#

Arguments#

Flags#

Output structure#

Included file types#

Terminal summary (default)#

I/O error resilience#

Examples#

oct export-skeleton#

Arguments#

Flags#

What gets exported (Python files)#

What gets exported (non-Python files)#

Output structure#

Examples#

oct clean#

Flags#

Arguments#

Examples#

oct health#

Flags#

What it checks#

Examples#

oct diag#

Subcommands#

Examples#

oct git status#

oct git check#

oct git init#

oct git commit#

oct git hooks#

Option C Compliance Rules#

1. Three-line file header#

2. Module docstring#

3. _dbg import and usage#

4. Comments explain why, not what#

oc_diagnostics Integration#

Domain configuration example#

Workflows#

Start a new project from scratch#

Bring an existing project into compliance#

Review code before a commit#

Commit with quality gate#

`oct lint`#

`oct format`#

`oct new`#

`oct scaffold`#

Generated `debug_config.json`#

`oct docs`#

`oct test`#

`oct export-source`#

`oct export-skeleton`#

`oct clean`#

`oct health`#

`oct diag`#

`oct git status`#

`oct git check`#

`oct git init`#

`oct git commit`#

`oct git hooks`#

3. `_dbg` import and usage#

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

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