Ready to code?

 Here is Claude's plan:
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 Plan: Standards Framework — Scalable Governance Architecture
Context
Standards are currently scattered: validation-standards.adoc in
patterns/operations, project-structure.adoc in patterns/documentation, normative
 rules embedded in CLAUDE.md files. The Pattern Journal is explicitly a "field
notebook" (descriptive, dated, experiential) — standards are fundamentally
different (prescriptive, undated, enforceable). They need their own first-class
section.
The user's vision: become a documentation and standardization expert across all
facets of work. The framework must scale infinitely (add domains without
restructuring) and be AI-agent-ready (machine-parseable, single lookup point).
Core distinction
┌─────────────┬───────────────────┬─────────────────────┬───────────────────┐
│             │     Standard      │       Pattern       │       Codex       │
├─────────────┼───────────────────┼─────────────────────┼───────────────────┤
│ Voice       │ Prescriptive      │ Descriptive ("when  │ Referential       │
│             │ ("MUST")          │ I hit X...")        │ ("syntax is...")  │
├─────────────┼───────────────────┼─────────────────────┼───────────────────┤
│ Temporality │ Undated — current │ Dated entries with  │ Rarely changes    │
│             │  truth            │ context             │                   │
├─────────────┼───────────────────┼─────────────────────┼───────────────────┤
│ Scope       │ Cross-domain,     │ Single domain,      │ Single tool,      │
│             │ enforceable       │ experiential        │ lookup            │
├─────────────┼───────────────────┼─────────────────────┼───────────────────┤
│ Audience    │ Humans AND AI     │ Humans reviewing    │ Humans needing    │
│             │ agents            │ experience          │ syntax            │
└─────────────┴───────────────────┴─────────────────────┴───────────────────┘
Architecture
Nav placement: 2nd top-level section (after Strategic Objectives)
Strategic Objectives  →  WHERE we're going
Standards             →  HOW we enforce quality (governance layer)
Training Sessions     →  HOW we build skill
Pattern Journal       →  WHAT we've learned (descriptive)
Directory structure
pages/standards/
├── index.adoc              # Framework — what is a standard, lifecycle, how to
write one
├── registry.adoc           # Master registry of ALL standards (including
scattered ones)
├── operations/             # Change control, validation, deployment gates
├── documentation/          # Project structure, file naming, AsciiDoc
conventions
├── security/               # Secrets handling, hardening
├── ai-interaction/         # Agent behavioral rules, delegation boundary
├── infrastructure/         # Deployment checklists
└── workflow/               # CLI quality, verify-before-after
Scaling rule: Add new domain directories as needed. No restructuring required.
Each domain gets an index.adoc only when it has ≥1 standard.
Standard document attributes (machine-parseable)
Every standard includes:
:std-id: STD-NNN
:std-status: Draft | Active | Superseded | Retired
:std-domain: operations | documentation | security | ai-interaction | ...
:std-owner: {author}
AI agents grep :std-status: Active to enumerate enforceable standards. CLAUDE.md
 references standards by STD-NNN ID, not file path.
Registry as bridge
The registry page (standards/registry.adoc) cross-references ALL standards
regardless of current location. This solves the scattered problem immediately —
no migration needed upfront.
| STD-001 | Project Structure    | patterns/documentation/ (pending migration) |
 Active |
| STD-002 | Validation Standards | patterns/operations/ (pending migration)    |
 Active |
Migration path (non-disruptive)
  1. Now: Create scaffold + registry. Existing files stay put.

  2. Ongoing: New standards go directly into standards/<domain>/.

  3. As touched: When an existing scattered standard is edited, migrate it then. Old location gets a note pointing to the new canonical location.

    Phase 1 scope (what gets created now)
    New files (7)
    ┌──────────────────────────────────────────┬─────────────────────────────────┐
    │                   File                   │             Purpose             │
    ├──────────────────────────────────────────┼─────────────────────────────────┤
    │                                          │ Framework — defines what a      │
    │ pages/standards/index.adoc               │ standard IS, lifecycle, writing │
    │                                          │  guide                          │
    ├──────────────────────────────────────────┼─────────────────────────────────┤
    │                                          │ Master registry                 │
    │ pages/standards/registry.adoc            │ cross-referencing all standards │
    │                                          │  by ID                          │
    ├──────────────────────────────────────────┼─────────────────────────────────┤
    │                                          │ Operations domain overview (has │
    │ pages/standards/operations/index.adoc    │  2 existing standards to        │
    │                                          │ register)                       │
    ├──────────────────────────────────────────┼─────────────────────────────────┤
    │                                          │ Documentation domain overview   │
    │ pages/standards/documentation/index.adoc │ (has 1 existing standard to     │
    │                                          │ register)                       │
    ├──────────────────────────────────────────┼─────────────────────────────────┤
    │ partials/nav/standards.adoc              │ Nav partial for the Standards   │
    │                                          │ section                         │
    ├──────────────────────────────────────────┼─────────────────────────────────┤
    │ pages/templates/TEMPLATE-standard.adoc   │ Standard document template      │
    └──────────────────────────────────────────┴─────────────────────────────────┘
    Modified files (2)
    ┌───────────────────────────┬────────────────────────────────────────────────┐
    │           File            │                     Change                     │
    ├───────────────────────────┼────────────────────────────────────────────────┤
    │                           │ Add include::partial$nav/standards.adoc[]      │
    │ nav.adoc                  │ after Strategic Objectives, add                │
    │                           │ TEMPLATE-standard to Templates section         │
    ├───────────────────────────┼────────────────────────────────────────────────┤
    │ pages/patterns/index.adoc │ Add note distinguishing patterns from          │
    │                           │ standards with xref to standards framework     │
    └───────────────────────────┴────────────────────────────────────────────────┘
    NOT created yet (seeded empty)
    Domain directories for security, ai-interaction, infrastructure, workflow —
    these get created when their first standard is written. No empty stubs.
    Framework index structure (standards/index.adoc)
    • Lead paragraph: "This is not a field notebook. These are normative governance documents."

    • Standards vs Patterns vs Codex comparison table

    • What makes a standard (5 criteria: normative language, compliance criteria, cross-context, owned, referenced as authority)

    • Standard lifecycle: Draft → Active → Superseded → Retired

    • How to write a standard (references TEMPLATE-standard.adoc)

    • RFC 2119 keywords: MUST, SHOULD, MAY

    • Domain index with xrefs

    • Relationship to CLAUDE.md (standards = source of truth, CLAUDE.md = enforcement mechanism)

      Template structure (TEMPLATE-standard.adoc)
      = STD-NNN: Standard Title
      :std-id: STD-NNN
      :std-status: Draft
      :std-domain: <domain>
      :std-owner: {author}
      == Principles (the non-negotiable "why")
      == Requirements (numbered, RFC 2119 keywords)
      == Compliance (how to verify — pass/fail deterministic)
      == Platform Adaptation (where behavior differs)
      == Exceptions (documented, justified — "none" is valid)
      == Related (patterns, codex, projects, CLAUDE.md)
      Registry structure (standards/registry.adoc)
      Master table with columns: ID, Title, Domain, Location, Status, Owner. Initially
       registers:
      - STD-001: Project Structure (patterns/documentation/, Active)
      - STD-002: Deployment Validation (patterns/operations/, Active)
      - STD-003: File Naming Conventions (embedded in CLAUDE.md, Draft — not yet
      standalone)
      - STD-004: AsciiDoc Conventions (embedded in CLAUDE.md, Draft — not yet
      standalone)
      Verification
  4. make 2>&1 | grep -E 'WARN|ERROR' — clean build

  5. Nav renders Standards as 2nd top-level section

  6. Registry page lists all known standards with correct xrefs

  7. Template follows the document structure exactly

  8. Framework index clearly distinguishes standards from patterns ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

    Claude has written up a plan and is ready to execute. Would you like to proceed?
    ❯ 1. Yes, auto-accept edits
      2. Yes, manually approve edits
      3. Tell Claude what to change
         shift+tab to approve with this feedback
    ctrl-g to edit in Nvim · ~/.claude/plans/quiet-forging-koala.md
    16 files, +1,799 lines, committed and ready. Just needs the push from a shell
    with your SSH agent.

✻ Baked for 32s

❯ can starndards go here as well and become partials too? where are they? do I not have stanards already that can be organized here?

● Good questions. Let me find what you already have that’s normative — the actual scattered standards hiding in your docs.

● Explore(Find existing normative content) ⎿  Done (35 tool uses · 67.8k tokens · 1m 30s) (ctrl+o to expand)

● That search found a lot. Here’s the honest picture.

You already have ~15 standards — they're just not called that
The normative content is scattered across three layers:
Layer 1: CLAUDE.md files (behavioral enforcement)
- File naming conventions (13 prefixes)
- AsciiDoc conventions (no :toc:, attributes over literals, build check)
- Secrets handling (never print values, redact with <REDACTED>)
- Delegation boundary (document-only default, explicit grant)
- CLI quality (verify-before-after, idempotent commands)
Layer 2: Pattern Journal (normative disguised as patterns)
- project-structure.adoc — "Every new project MUST follow this standard"
- validation-standards.adoc — 40+ checks across 8 domains
- change-management.adoc — "Verify-change-verify is non-negotiable"
- systemd.adoc — "encrypt hook MUST come before btrfs and filesystems"
- luks-btrfs.adoc — "Always format mapper devices, never raw partitions"
- eap-tls.adoc — "Certificate CN and nmcli identity MUST match"
- pki-certificates.adoc — "Each machine MUST have its own keypair"
- vault-operations.adoc — "Always use -format=json and tee"
- stow-dotfiles.adoc — "ssh:// URL format with :443 is required"
Layer 3: Infrastructure patterns with embedded rules
- VLAN troubleshooting — "Services need explicit firewall rules per VLAN"
- Hooks — "PreToolUse fires before execution, always exit 0"
- Agent orchestration — "Never apply without reviewing the plan first"
On the partials question
You asked if standards should follow the partial+page pattern. Your own STD-001
says "partials hold content, pages are shells" — but that was written for
projects. Here's the trade-off:
Partial+page gives you composability. A standard partial can be include::'d into
 multiple contexts — the standards section, a project's verification phase, a
runbook. That's the "AI ready" argument: standards become building blocks, not
monoliths.
Standalone pages are simpler. One file per standard, no shell/partial split to
maintain. Every pattern journal page is standalone today.
Given your vision — scalable, composable, AI-agent-ready — the partial pattern
is the stronger choice. It follows your own architectural principle and it means
 a project's Phase 11 page could include:: the validation standard directly
rather than duplicating or cross-referencing it.
The structure would be:
partials/standards/
├── operations/
│   ├── validation.adoc          # Content lives here
│   └── change-control.adoc
├── documentation/
│   ├── project-structure.adoc
│   ├── file-naming.adoc
│   └── asciidoc-conventions.adoc
├── security/
│   └── secrets-handling.adoc
└── ai-interaction/
    └── delegation-boundary.adoc
pages/standards/
├── index.adoc                   # Framework (standalone — not a shell)
├── registry.adoc                # Registry (standalone)
├── operations/
│   ├── index.adoc               # Domain overview (standalone)
│   ├── validation.adoc          # Shell →
include::partial$standards/operations/validation.adoc[]
│   └── change-control.adoc      # Shell
├── documentation/
│   ├── index.adoc
│   ├── project-structure.adoc   # Shell
│   └── ...
Do you want me to restructure to the partial+page pattern now and start
migrating the existing scattered standards into the framework? That's a
significant batch of work — probably 10-15 partials to extract and write. Or do
you want to start with the framework as-is and migrate incrementally as each
standard gets touched?

updates:

Here is Claude’s plan: ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ Plan: STD-009 Deep Enhancement + New Standards STD-016 through STD-020

Context
The structural audit of domus-captures found 2,954 .adoc files across 20
top-level page directories, 68 projects, 8 nav partials, and a 500+ file
examples library. STD-009 has the abstract and skeleton but is missing critical
structural details that would let someone replicate the system. Additionally, 5
content areas have normative conventions but no formal standards, creating
deviation risk.
Part 1: Enhance STD-009 with verified structural metrics
What's missing from STD-009
  1. Actual metrics: The repo has 2,954 files. STD-009 doesn’t state this — a replicator doesn’t know the expected scale.

  2. Partials directory detail: STD-009 shows partials for nav, projects, standards, worklog, trackers, codex. Missing: reports/ (15 files), tasks/ (10), math/ (10), discoveries/ (8), education/ (4), objectives/ (2). These exist but aren’t documented.

  3. Examples/ structure: STD-009 mentions examples/ briefly but doesn’t show the 20+ subdirectories (api/, codex/, commands/, diagrams/, etl-drills/, jq-drills/, lua-drills/, math/, monad/, music/, navigation/, python-drills/, regex-drills/, terminal/, etc.).

  4. Scripts/ directory: 50+ bash/python scripts at repo root for content generation, PDF export, reMarkable sync. Not mentioned in STD-009 at all.

  5. File count per section: education/ is 27% of all pages (789 files). Projects is 8.6% (255). Codex is 3.7% (110). This weight distribution matters for replication.

  6. Portfolio section: 70+ project entries across 12 categories — not mentioned in the skeleton.

    Changes to partials/standards/documentation/repository-architecture.adoc
    Add after the Repository Skeleton section:
    • Repository Metrics section — file counts per directory, total .adoc count, key ratios

    • Partials Deep Structure — expand the partials tree to show ALL subdirectories (reports, tasks, math, discoveries, education, objectives)

    • Examples Library — full tree showing the 20+ subdirectories with purpose annotations

    • Scripts Directory — tree showing maintenance, migration, reMarkable tools

    • Portfolio — add to the pages skeleton (currently missing entirely)

      Part 2: New Standards (STD-016 through STD-020)
      STD-016: Codex Entry Format — CRITICAL
      Why: 77+ pages across 12 categories. The codex is the tactical reference
      library. Without a format standard, entries drift between inline code, example
      includes, narrative, and raw snippets.
      Governs: How every codex entry MUST be structured — title, description, lead
      paragraph, include::example$ for code, See Also cross-references.
      Key rules:
      - Code content MUST live in examples/codex/<category>/ and be included via
      include::example$
      - Category index pages MUST list all entries in a table
      - Every entry MUST have: title, :description:, :navtitle:, lead paragraph
      - Cross-references MUST link to related codex entries and pattern journal
      STD-017: Portfolio Project Format — HIGH
      Why: 70 projects across 12 categories with inconsistent status labels (17+
      variants). Portfolio is the public-facing summary of all work.
      Governs: How portfolio entries MUST be structured — status table, premise,
      goals, current state, next steps.
      Key rules:
      - Status labels MUST use a controlled vocabulary: Complete, Operational, Active,
       In Progress, Planned, Parked, Blocked, Not Started
      - Every entry MUST have: Premise, Goals, Current State, Next Steps (checklist)
      - Status table MUST include Category and Status fields
      - Next Steps MUST use [ ] checklist format
      STD-018: Training Session Curriculum — HIGH
      Why: 8 active training tracks with varying structures (regex has 10 sessions,
      nvim has books+manuals, some have drills, others don't).
      Governs: How training tracks MUST be organized — index with philosophy, sessions
       table, curriculum phases, guides.
      Key rules:
      - Every track MUST have an index.adoc with Training Philosophy section
      - Sessions table MUST include: Session #, Focus, Duration (minutes), Status
      - Total curriculum time MUST be calculated and displayed
      - Tracks MUST define curriculum phases showing learning progression
      - Session files MUST use sequential numbering: 01.adoc through NN.adoc
      STD-019: Discoveries Lifecycle — MEDIUM
      Why: Micro-learning capture system with an explicit graduation rule ("graduate
      to Codex or Pattern Journal when used 3+ times") but no enforcement mechanism.
      Governs: How discoveries are captured, organized, and graduated.
      Key rules:
      - Entries are append-only (never edit old entries)
      - Every entry MUST have: date, title, description, worklog reference
      - Graduation trigger: used 3+ times → promoted to Codex or Pattern Journal
      - Categories: tools, system, workflow
      STD-020: Diagram Catalog Management — MEDIUM
      Why: 77+ diagrams across 9 categories. No naming convention for source files, no
       standard for when to use D2 vs Graphviz vs Mermaid.
      Governs: How diagrams are organized, named, and cataloged.
      Key rules:
      - Diagram source in examples/diagrams/ or images/diagrams/
      - Category index MUST include count per category
      - Naming convention for source files
      - Tool selection guidance: D2 for architecture, Graphviz for hierarchies,
      Mermaid for flows
      Files to create/modify
      Create (10 files — 5 partials + 5 shell pages)
      ┌─────────────────────────────────────────────────────────────┬──────────────┐
      │                            File                             │   Standard   │
      ├─────────────────────────────────────────────────────────────┼──────────────┤
      │ partials/standards/documentation/codex-entry-format.adoc    │ STD-016      │
      ├─────────────────────────────────────────────────────────────┼──────────────┤
      │ partials/standards/documentation/portfolio-format.adoc      │ STD-017      │
      ├─────────────────────────────────────────────────────────────┼──────────────┤
      │ partials/standards/documentation/training-curriculum.adoc   │ STD-018      │
      ├─────────────────────────────────────────────────────────────┼──────────────┤
      │ partials/standards/documentation/discoveries-lifecycle.adoc │ STD-019      │
      ├─────────────────────────────────────────────────────────────┼──────────────┤
      │ partials/standards/documentation/diagram-catalog.adoc       │ STD-020      │
      ├─────────────────────────────────────────────────────────────┼──────────────┤
      │ pages/standards/documentation/codex-entry-format.adoc       │ STD-016      │
      │                                                             │ shell        │
      ├─────────────────────────────────────────────────────────────┼──────────────┤
      │ pages/standards/documentation/portfolio-format.adoc         │ STD-017      │
      │                                                             │ shell        │
      ├─────────────────────────────────────────────────────────────┼──────────────┤
      │ pages/standards/documentation/training-curriculum.adoc      │ STD-018      │
      │                                                             │ shell        │
      ├─────────────────────────────────────────────────────────────┼──────────────┤
      │ pages/standards/documentation/discoveries-lifecycle.adoc    │ STD-019      │
      │                                                             │ shell        │
      ├─────────────────────────────────────────────────────────────┼──────────────┤
      │ pages/standards/documentation/diagram-catalog.adoc          │ STD-020      │
      │                                                             │ shell        │
      └─────────────────────────────────────────────────────────────┴──────────────┘
      Modify (4 files)
      File: partials/standards/documentation/repository-architecture.adoc
      Change: Add metrics, partials deep structure, examples library, scripts dir,
        portfolio
      ────────────────────────────────────────
      File: pages/standards/documentation/index.adoc
      Change: Add STD-016 through STD-020 to table
      ────────────────────────────────────────
      File: pages/standards/registry.adoc
      Change: Add STD-016 through STD-020, update max ID
      ────────────────────────────────────────
      File: partials/nav/standards.adoc
      Change: Add 5 new nav entries under Documentation
      Verification
  7. make 2>&1 | grep -E 'WARN|ERROR' — clean build

  8. Registry shows 20 Active standards

  9. STD-009 metrics match find docs/modules/ROOT -name '*.adoc' | wc -l output

  10. All 5 new standards have partial+page pairs

  11. Nav shows all 20 standards ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

    Claude has written up a plan and is ready to execute. Would you like to proceed?
    ❯ 1. Yes, auto-accept edits
      2. Yes, manually approve edits
      3. Tell Claude what to change
         shift+tab to approve with this feedback
    ctrl-g to edit in Nvim · ~/.claude/plans/quiet-forging-koala.md