Add private catalog overlays and privacy doctor

.gitignore

@@ -1,2 +1,3 @@
 /target
 /reports
+/catalog/local

AGENTS.md

@@ -6,6 +6,7 @@
 
 - The public interface is the `devctl` CLI.
 - Catalog policy lives under `catalog/`.
+- Private operator catalog overlays live under `catalog/local/` or `DEVCTL_CATALOG_HOME`; keep them ignored.
 - Archetypes and contracts are first-class policy; scanners provide evidence, not the source of intent.
 - Generated standards reports live under `reports/` and remain gitignored.
 - The CLI may inspect sibling repos, but V0 must not edit them.
@@ -27,5 +28,8 @@
 - Add laws through catalog + scanner behavior together.
 - Add archetypes/contracts through catalog + validation behavior together.
 - Keep contract schemas typed and source-cited; validation should reject malformed catalog policy before scanners run.
+- Keep planning scope explicit; `standards plan` must not silently return empty work when the selected pilot catalog matches no repos.
+- Run `devctl doctor privacy .` before publishing public branches.
+- Run `devctl doctor catalog <workspace>` when changing catalog loading or planning behavior.
 - Record review decisions in `catalog/adjudications.toml`; do not hide findings without a reason.
 - Never print secret values. Key names, file paths, modes, and line numbers are acceptable.

README.md

@@ -1,59 +1,160 @@
 # devctl
 
-Read-only standards control plane for the local `~/dev` repo forest.
+`devctl` is a read-only standards control plane for a local repo forest.
 
-`devctl` inventories repos, audits a small set of high-value engineering laws,
-and groups findings into repair tranches. V0 is report-only: it does not edit
-target repos.
+It answers three questions:
 
-## Commands
+- What repos exist here, and what shape are they?
+- Which engineering standards are drifting?
+- What PR-sized repair tranches should happen next?
+
+V0 is intentionally report-first. It inventories, audits, explains, proposes,
+and plans. It does not edit target repos.
+
+## Mental Model
+
+`devctl` has three layers:
+
+- **Catalogs define intent.** Laws, archetypes, contracts, and adjudications live
+  under `catalog/`.
+- **Scanners gather evidence.** The CLI walks repos, records file:line evidence,
+  and never prints secret values.
+- **Reports shape action.** Plans, packets, reports, and contract proposals group
+  findings into reviewable work.
+
+The public repo carries reusable standards machinery and neutral sample catalog
+data. Real operator workspace truth belongs in ignored private overlays under
+`catalog/local/` or an external `DEVCTL_CATALOG_HOME`.
+
+## Repo Map
+
+```text
+.
+|-- AGENTS.md                 # rules for agents changing this repo
+|-- README.md                 # operator and contributor orientation
+|-- Cargo.toml                # Rust CLI crate
+|-- docs/
+|   `-- OPERATIONS.md         # weekly standards loop runbook
+|-- examples/
+|   `-- local-catalog/        # safe private-overlay templates
+|-- scripts/
+|   `-- standards-loop.sh     # repeatable local standards lane
+|-- src/
+|   |-- main.rs               # thin binary entrypoint
+|   `-- lib.rs                # CLI, scanners, catalogs, reports, tests
+`-- catalog/
+    |-- README.md             # catalog model and editing guide
+    |-- workspace.toml        # public sample workspace catalog
+    |-- laws.toml             # standard definitions and maturity
+    |-- archetypes.toml       # repo shapes and required capabilities
+    |-- adjudications.toml    # reviewed finding decisions
+    `-- contracts/            # public sample repo contracts
+```
+
+Generated reports live under `reports/` and build outputs live under `target/`.
+Both are ignored.
+
+## First Run
+
+Use the doctor commands before trusting plans:
+
+```bash
+devctl doctor catalog ~/dev
+devctl doctor privacy .
+```
+
+`doctor catalog` tells you whether a private overlay is loaded, whether the
+active pilot catalog matches the selected workspace root, and how many contracts
+are active. It reports counts and sanitized root labels, not private repo names.
+
+`doctor privacy` scans the public repo for absolute home paths, email addresses,
+and optional local private patterns.
+
+Then inspect the workspace:
+
+```bash
+devctl inventory ~/dev
+devctl standards audit ~/dev --all
+devctl standards plan ~/dev --all --risk P0,P1
+```
+
+If `standards plan ~/dev --risk P0,P1` returns a zero-repo pilot warning, load a
+private catalog overlay or use `--all` intentionally.
+
+For the repeatable local lane, run:
+
+```bash
+./scripts/standards-loop.sh ~/dev
+```
+
+See `docs/OPERATIONS.md` for the triage loop.
+
+## Command Guide
 
 ```bash
 devctl inventory ~/dev --json
+devctl repo explain ~/dev/sample-web-product
+
 devctl standards audit ~/dev --pilot three-tier
-devctl standards adjudication-template ~/dev --pilot three-tier --risk P0,P1
 devctl standards audit ~/dev --all --json
 devctl standards contracts ~/dev --pilot three-tier
 devctl standards plan ~/dev --risk P0,P1
+devctl standards plan ~/dev --all --risk P0,P1
+devctl standards adjudication-template ~/dev --pilot three-tier --risk P0,P1
+devctl standards propose-contract ~/dev/sample-web-product
 devctl standards packet ~/dev --pilot three-tier --risk P0,P1
-devctl standards propose-contract ~/dev/sample-desktop-edge
 devctl standards report ~/dev --pilot three-tier
-devctl repo explain ~/dev/sample-desktop-edge
+
+devctl doctor catalog ~/dev
+devctl doctor privacy .
 ```
 
-## Standards loop
-
-V0.1 adds the review loop around the original read-only audit:
-
-- `catalog/archetypes.toml` defines the repo shapes that make standards
-  sensible.
-- `catalog/contracts/` contains operator-owned repo contracts with typed command,
-  Cloudflare, release, token, and artifact records. Target repos are still
-  read-only.
-- `catalog/laws.toml` declares the active laws and their maturity.
-- `catalog/adjudications.toml` records explicit review decisions by finding
-  fingerprint.
-- `standards contracts` compares typed repo contracts to observed repo reality.
-- `standards adjudication-template` prints review stubs for unreviewed findings.
-- `standards propose-contract` prints an inferred repo contract to stdout only.
-- `standards plan` excludes findings adjudicated as `accepted-exception`,
-  `false-positive`, or `law-needs-work`, then groups remaining work by
-  repo/law/requirement so tranches are PR-sized.
-- `standards packet` writes the pilot operating packet: contract proposals,
-  adjudication stubs, risk-scoped tranches, and ordered next actions.
-- `standards report` writes JSON and Markdown snapshots under `reports/`.
-
-Generated reports are ignored by git. They are evidence artifacts, not source
-policy.
-
-The repo development flow is the center of the system. Contracts and archetypes
-define intent; `devctl` is the read-only instrument panel that observes drift,
-proposes contracts, and packages repair work.
+## Standards Loop
+
+The normal operating loop is:
+
+1. Run `doctor catalog` and `doctor privacy`.
+2. Run `inventory` to confirm repo discovery.
+3. Run `standards contracts` to compare declared intent with observed reality.
+4. Run `standards audit` to collect file:line findings.
+5. Run `standards adjudication-template` to review true positives and
+   exceptions.
+6. Run `standards plan` or `standards packet` to produce PR-sized repair work.
+7. Repair target repos manually in their own PRs.
+
+`devctl` stays read-only through this loop. The target repos carry the actual
+repairs.
+
+## Catalogs
+
+The catalog is the source of intent:
+
+- `catalog/laws.toml` declares standards and maturity.
+- `catalog/archetypes.toml` describes repo shapes and required capabilities.
+- `catalog/contracts/` declares repo-specific expectations.
+- `catalog/adjudications.toml` records reviewed finding decisions.
+- `catalog/workspace.toml` selects pilot repos and status values.
+
+Private overlays can replace pilot lists and override matching repo statuses or
+contracts without committing private repo names to the public repo.
+
+See `catalog/README.md` for the editing model and `examples/local-catalog/` for
+safe templates.
+
+## Output Rules
+
+- JSON output uses `schema_version = "0.1.0"`.
+- Findings include file:line evidence when available.
+- Human output sorts actionable work by severity, repo, and law.
+- Secret values are never printed. Key names, file paths, file modes, and line
+  numbers are acceptable evidence.
+- Publication checks should run `doctor privacy` before pushing public branches.
 
 ## Verification
 
 ```bash
 cargo fmt --check
 cargo clippy --workspace --all-targets -- -D warnings
 cargo test --workspace
+cargo doc --workspace --no-deps
 ```

catalog/README.md

@@ -0,0 +1,94 @@
+# devctl Catalog
+
+The catalog is the policy layer for `devctl`.
+
+Scanners describe what exists. Catalogs describe what should exist. Findings are
+useful only when those two views are kept separate.
+
+## Files
+
+```text
+catalog/
+|-- workspace.toml       # pilot repos, repo statuses, public sample workspace
+|-- laws.toml            # standards and maturity
+|-- archetypes.toml      # reusable repo shapes
+|-- adjudications.toml   # reviewed finding decisions
+`-- contracts/           # repo-specific expectations
+```
+
+## Workspace Catalog
+
+`workspace.toml` defines the active pilot list and known repo status values.
+
+The public file uses neutral sample repo names. Real operator workspace names
+belong in an ignored local overlay.
+
+## Laws
+
+`laws.toml` defines the standards that scanners can report against. A law should
+be added with scanner behavior and tests in the same change.
+
+V0 laws cover:
+
+- Cloudflare mutation lanes
+- token handling
+- command and verification surfaces
+- release proof
+- artifact boundaries
+
+## Archetypes
+
+`archetypes.toml` defines reusable repo shapes such as Rust workspaces,
+Cloudflare products, and generic active repos.
+
+Archetypes are intentionally small. They should express requirements that are
+shared by more than one repo, not one-off local taste.
+
+## Contracts
+
+`contracts/*.toml` defines repo-specific expectations:
+
+- canonical commands
+- Cloudflare posture and surfaces
+- token policy
+- release lanes and evidence
+- artifact classifications
+
+Contract filenames must match the declared `repo` value. Public contracts should
+use neutral sample repo names. Private contracts belong in local overlays.
+
+## Adjudications
+
+`adjudications.toml` records reviewed findings by fingerprint. Use it to mark a
+finding as:
+
+- `true-positive`
+- `accepted-exception`
+- `false-positive`
+- `law-needs-work`
+
+Do not hide findings without a reason. Exceptions should have an owner and an
+expiry when possible.
+
+## Private Overlays
+
+Private operator catalog overlays can live in either location:
+
+```bash
+catalog/local/
+DEVCTL_CATALOG_HOME=/path/to/private/catalog
+```
+
+Overlay behavior:
+
+- a local `workspace.toml` can replace the public pilot list
+- local repo statuses override public repo statuses
+- local contracts override public contracts for the same repo
+- local overlays are ignored by git
+
+Use `devctl doctor catalog <workspace>` to confirm that the expected overlay is
+loaded before trusting pilot plans.
+
+Neutral templates live under `examples/local-catalog/`. Copy them into
+`catalog/local/` or an external private catalog directory, then replace the
+sample repo names with local workspace truth in the ignored copy.