Classes
class	OcStatus

Functions
Path	option_c_dir (Path project_root)
Path	resolve_octrc (Path project_root)
Path	resolve_debug_config (Path project_root)
Path	resolve_logs_dir (Path project_root)
OcStatus\|None	load_oc_status (Path project_root)
None	write_oc_status (Path project_root, OcStatus status)

Variables
str	OPTION_C_DIRNAME = ".option_c"
str	OC_STATUS_FILENAME = "oc_status.json"
str	OC_STATUS_SCHEMA_VERSION = "1.0"
tuple	VALID_STAGES = ("bootstrap", "migrating", "compliant")
	Stage = Literal["bootstrap", "migrating", "compliant"]

Detailed Description

Purpose
-------
FS-539 - single source of truth for resolving paths to the canonical
``.option_c/`` project dotdir (introduced in v0.19.0) with a read-only
compat shim so projects that haven't run ``oct migrate .option_c``
keep working through the legacy layout:

  * ``.octrc.json``                      (legacy) → ``.option_c/octrc.json``
  * ``oc_diagnostics/debug_config.json`` (legacy) → ``.option_c/debug_config.json``
  * ``logs/``                            (legacy) → ``.option_c/logs/``

The resolvers always prefer the modern path when present and fall back
to the legacy path otherwise. They never raise on a missing file;
callers are expected to handle absent configs themselves (every OCT
config loader already does).

Responsibilities
----------------
- Define :data:`OPTION_C_DIRNAME`, :data:`OC_STATUS_FILENAME`, and
  :data:`VALID_STAGES` - the canonical names consumed across OCT.
- Provide pure path helpers (:func:`option_c_dir`,
  :func:`resolve_octrc`, :func:`resolve_debug_config`,
  :func:`resolve_logs_dir`) that never touch file contents beyond an
  ``is_file`` / ``is_dir`` existence check.
- Expose :class:`OcStatus` + :func:`load_oc_status` /
  :func:`write_oc_status` for the migration-state file
  (``oc_status.json``) that ``oct migrate``, ``oct audit``, and
  ``CLAUDE.md``'s compliance probe consume.

Diagnostics
-----------
Domain: OCT-CORE
Levels:
    L2 - (none) callers decide how to react to a missing path
    L3 - oc_status read and write entry, naming the project root
    L4 - octrc and debug-config path resolution

Contracts
---------
- All public helpers are pure: no network, no mutation outside of
  :func:`write_oc_status` which is explicitly a writer.
- Resolvers only stat the filesystem; they never read config contents,
  so they are safe to call during root discovery.
- :class:`OcStatus` validates ``stage`` at construction; other fields
  are stored as-is to keep the dataclass forwards-compatible with
  future schema extensions.

Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)

Function Documentation

◆ load_oc_status()

OcStatus | None option_c_dir.load_oc_status ( Path project_root )

Return the parsed ``oc_status.json`` or ``None`` if missing/invalid.

Missing-file, OSError, JSONDecodeError, and invalid-stage all
collapse to ``None`` so callers (``oct audit``, CLAUDE.md probe,
etc.) can treat "unmigrated" and "corrupt" identically - both
require the user to re-run ``oct migrate .option_c``.

Definition at line 190 of file option_c_dir.py.

◆ option_c_dir()

Path option_c_dir.option_c_dir ( Path project_root )

Return ``<project_root>/.option_c`` (existence not checked).

Definition at line 81 of file option_c_dir.py.

◆ resolve_debug_config()

Path option_c_dir.resolve_debug_config ( Path project_root )

Return the path to ``debug_config.json`` for *project_root*.

Preference order:
  1. ``.option_c/debug_config.json`` (post-FS-539)
  2. ``oc_diagnostics/debug_config.json`` (v0.17+)
  3. ``diagnostics/debug_config.json`` (pre-v0.17 legacy)

When nothing exists, the ``oc_diagnostics/`` path is returned so
callers get the most-commonly-expected missing-file location.

Definition at line 103 of file option_c_dir.py.

◆ resolve_logs_dir()

Path option_c_dir.resolve_logs_dir ( Path project_root )

Return the directory where OCT writes audit / run logs.

Prefers ``.option_c/logs`` when present (i.e. on a migrated or
freshly-scaffolded v0.19.0+ project where
``.option_c/`` already exists on disk), otherwise falls back to
``<project_root>/logs``. When neither exists, the legacy path is
returned so that ad-hoc invocations from an unmigrated working tree
don't spontaneously create a ``.option_c/`` side-effect - that
creation is reserved for ``oct scaffold`` and ``oct migrate``.

Definition at line 128 of file option_c_dir.py.

◆ resolve_octrc()

Path option_c_dir.resolve_octrc ( Path project_root )

Return the path to ``.octrc.json``-equivalent for *project_root*.

Prefers ``.option_c/octrc.json`` when present, else
``<project_root>/.octrc.json`` (legacy). The legacy path is also
returned when neither file exists so the error message points the
user at the file they're most likely looking for on an unmigrated
project.

Definition at line 86 of file option_c_dir.py.

◆ write_oc_status()

None option_c_dir.write_oc_status	(	Path	project_root,
		OcStatus	status )

Write *status* to ``<project_root>/.option_c/oc_status.json``.

Creates ``.option_c/`` if it does not already exist. The on-disk
JSON is pretty-printed (2-space indent) and prefixed with the
``_schema_version`` sentinel used elsewhere in OCT for
forward-compatible schema evolution.

Definition at line 224 of file option_c_dir.py.

Variable Documentation

◆ OC_STATUS_FILENAME

str option_c_dir.OC_STATUS_FILENAME = "oc_status.json"

Definition at line 68 of file option_c_dir.py.

◆ OC_STATUS_SCHEMA_VERSION

str option_c_dir.OC_STATUS_SCHEMA_VERSION = "1.0"

Definition at line 69 of file option_c_dir.py.

◆ OPTION_C_DIRNAME

str option_c_dir.OPTION_C_DIRNAME = ".option_c"

Definition at line 67 of file option_c_dir.py.

◆ Stage

option_c_dir.Stage = Literal["bootstrap", "migrating", "compliant"]

Definition at line 73 of file option_c_dir.py.

◆ VALID_STAGES

tuple option_c_dir.VALID_STAGES = ("bootstrap", "migrating", "compliant")

Definition at line 71 of file option_c_dir.py.

Classes

Functions

Variables