@ahmed-g-gad/apothem 0.1.1

package/src/apothem/rules/tool-use-discipline.md

@@ -0,0 +1,48 @@
+---
+name: "tool-use-discipline"
+description: "Ordinary tool use runs as a disciplined loop: independent tool calls go in one turn, never sequentially; the agent works an observe → decide → act cadence; the loop iterates until a verifiable exit condition is met, never a fixed count. Generalizes the agent-tier single-message parallel-launch discipline down to every tool call. Harness-agnostic; advisory under the agnostic posture."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Tool-Use Discipline — Parallel Calls, the Observe → Decide → Act Loop
+
+## Purpose
+
+Every tool an agent reaches for is a step in a loop, not an isolated act. This rule names that loop and binds two disciplines on it: independent calls run together in one turn, and the loop runs until a verifiable condition closes it. The agent-orchestration rules carry the same discipline at the agent-team tier; this rule states it for ordinary tool use, below the team threshold.
+
+## Obligations
+
+### 1. Parallel Tool Execution
+
+Independent tool calls — calls whose inputs do not depend on each other's outputs — MUST be issued together in a single turn, never one-per-turn in sequence. Reading three files, grepping two patterns, and listing a directory to answer one question is one batch, not five turns. This generalizes the single-message parallel-launch invariant `rules/agent-orchestration.md` §3 binds at the agent-dispatch tier down to the ordinary-tool tier: the same latency and context gain applies whether the parallel unit is an agent or a `Read`.
+
+Sequence only on a genuine dependency — when call B's input is call A's output, A precedes B. A dependency the agent cannot name is not a dependency; batch the calls.
+
+### 2. The Observe → Decide → Act Loop
+
+The agent's canonical working cadence is **observe → decide → act**: observe the current state (read context, run a tool, inspect a result), decide the next move from what was observed, act, then observe again. Naming the loop makes the cadence explicit. The lineage is loop-engineering; the vocabulary is apothem's own.
+
+A turn that acts without first observing — edits a file it has not read this loop, asserts a result it has not checked — has skipped the observe step. Read-before-edit, locate-before-read per `rules/large-file-reading.md`, and check-before-claim are the same discipline at the tool tier.
+
+### 3. Iterate to a Verifiable Exit, Never a Fixed Count
+
+The loop continues until a **verifiable exit condition** is true — a gate passes, a test goes green, a build succeeds, a read confirms the expected state — never until a fixed iteration count elapses, never on the agent's unchecked sense that it is "probably done." When no machine-checkable exit exists, the loop closes on an explicit stated criterion the operator can audit, not a silent stop. This is the tool-tier form of the open-loop discipline `rules/multi-agent-workflow.md` §1 declares for multi-agent waves; a bounded retry with a defined retreat per `rules/context-management.md` §8 bounds the loop when the exit resists convergence.
+
+## Failure tells
+
+Three `Read` calls across three turns to answer one question (sequential where parallel was correct). An `Edit` to a file the agent has not read in the current loop (act without observe). A "done" claimed on no checked condition (no verifiable exit). A loop that stops after N tries with the exit condition still false and no retreat stated (fixed-count stop). A dependency asserted between two calls that share no input/output edge (false-sequencing).
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every ordinary tool-call batch (independent calls issued together per §1). ● Every agent working cadence (the observe → decide → act loop per §2). ● Every loop's exit decision (verifiable condition, never fixed count, per §3).
+- **Satisfies →** ● The tool-tier generalization of the single-message parallel-launch discipline. ● The named canonical agent-loop vocabulary the ecosystem references.
+- **Established by ↑** ● `rules/agent-orchestration.md` §3 (the agent-tier single-message parallel-launch invariant this rule generalizes down to ordinary tool calls). ● `rules/multi-agent-workflow.md` §1 (the open-loop verifiable-exit discipline this rule states at the tool tier).
+- **Gated by ←** ● `CLAUDE.md` always-loaded preamble. ● `rules/agnostic-posture.md` §2 (this rule is advisory, not a blocking gate).
+- **Cross-bound with ↔** ↔ `rules/agent-orchestration.md` (§3 single-message parallel-launch — this rule is its ordinary-tool-tier generalization; the team-tier mechanics are owned there). ↔ `rules/context-management.md` (§7.2 demand-loading and §8 bounded-retry-with-retreat — the observe step preserves context budget and the loop's retreat path is owned there). ↔ `rules/large-file-reading.md` (locate-before-read is the observe-step discipline at the file tier). ↔ `rules/multi-agent-workflow.md` (§1 open-loop verifiable-exit — this rule states the same exit discipline at the tool tier, below the multi-agent threshold).
+
+## Recommended Next Step
+
+**Batch the next set of independent tool calls into one turn** and name the loop's verifiable exit condition before acting, per §1 and §3 of this rule.

package/src/apothem/rules/visual-leverage.md

@@ -0,0 +1,102 @@
+---
+name: "visual-leverage"
+description: "Structural subject matter — architecture, control flow, data flow, dependency graph, state machine, sequence, decision tree, hierarchy, precedence stack, lifecycle, permission matrix — carries a current-reality diagram alongside its prose, with provenance and a verification date. Mermaid is the recommended default for Markdown-centric ecosystems; the host's existing notation is honored per M1 host-discovery."
+pathFilter: "**/*.md, **/docs/**, **/CLAUDE.md, **/rules/**, **/skills/**, **/agents/**, **/commands/**, **/adr/**, **/rfcs/**, **/architecture*, **/design*"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Visual Leverage — Diagrams Where Structure Is the Subject
+
+## What this rule enforces
+
+This rule binds **M9 — Visual Leverage**. Where the host-project artifact's subject matter is **structural** — architecture, control flow, data flow, dependency graph, state machine, sequence, decision tree, hierarchy, precedence stack, lifecycle, permission matrix — the agent MUST produce a **diagram** alongside the prose: never a substitute (the prose carries semantics the diagram cannot) but a **co-equal first-class artifact**. Prose-only structural documentation is systematic under-utilization of the medium and a structural failure, not a style choice. Every diagram MUST carry provenance (hand-authored / generated / extracted), a **verification date**, and a back-binding to the artifact it abstracts. Diagrams reflect **current reality** — never historical or aspirational state — and a patch that changes a structure updates its diagram in the same change.
+
+## Pre-conditions
+
+Applies whenever a host-project artifact's subject matter is structural in any sense enumerated above. Diagrams are NOT required for narrative prose, declarative configuration, prose-only how-to guides, or single-function code comments — the trigger is structural subject matter, not Markdown presence. A trivial-scope structural surface (a four-line pipeline described in one unambiguous paragraph) is exempt; the diagram becomes mandatory the moment the structure exceeds what one paragraph carries without ambiguity.
+
+## Required behavior
+
+### 1. Trigger Catalog — When a Diagram Is Mandatory
+
+| Subject matter | Diagram class (recommended) | Why a diagram |
+|---|---|---|
+| Architecture (component layout, layering, integration boundaries) | Architecture sketch (Mermaid `graph TD` / `flowchart`) | Spatial relationships between components are illegible in linear prose |
+| Control flow (decision trees, branching pipelines, retry loops) | Decision tree (`flowchart`) | Branch coverage and termination conditions are auditable visually |
+| Data flow (records, tokens, sizes through stages) | Data-flow diagram (`flowchart` with edge annotations) | Stage-to-stage transformations and back-pressure points become explicit |
+| State machine (lifecycle states, transition triggers) | State diagram (`stateDiagram-v2`) | Reachability and dead-end states are inspectable |
+| Sequence (ordered interactions across actors) | Sequence diagram (`sequenceDiagram`) | Message ordering and concurrency are unambiguous |
+| Dependency graph (modules, packages, services) | Dependency graph (`graph LR`) | Cycles and orphans are visible at a glance |
+| Hierarchy (taxonomies, inheritance, organizational structure) | Tree (`graph TD`) | Depth and sibling counts are readable |
+| Precedence stack (rule precedence, deny-overrides-allow, override chains) | Vertical stack (`graph TD` ordered top-down) | Override semantics need spatial ordering |
+| Permission matrix (actor × resource × verdict) | Heatmap or table | Sparse / dense regions are legible in two dimensions |
+
+Subject matter fitting one row MUST emit the corresponding diagram class (or its host-discovered equivalent per §3). Subject matter fitting two or more rows emits one diagram per row — a state machine that ALSO carries a permission matrix emits both.
+
+### 2. Diagram Provenance — Required Metadata
+
+Every diagram MUST carry a metadata header (Mermaid `%%` comments, or the host's diagram-notation comment syntax) with all three fields:
+
+- **`provenance: <hand-authored | generated-from <source> | extracted-from <source>>`** — how the diagram was produced. Generated diagrams cite the generator (script path, command, tool); extracted diagrams cite the source artifact (file path, line range).
+- **`verified: <ISO-8601 date>`** — when the diagram was last verified against current reality. Updated **in the same change** that touches the abstracted structure (per §4).
+- **`cross-reference: <peer artifact>`** — the artifact the diagram binds back to (prose section, code module, spec). This is the M10 reciprocal-binding surface (`rules/bidirectional-binding.md`).
+
+A diagram missing any field is non-conformant. A diagram whose `verified` date precedes the structure it abstracts is **stale** (per §4).
+
+### 3. Notation Discipline — Mermaid Default, Host Override
+
+**Mermaid is the recommended default** for Markdown-centric ecosystems (concrete drivers per `rules/interactive-questions-canonical-shapes.md` §3.2.1):
+
+- **Class 5 rule citation** — the hooks pipeline hooks pipeline uses Mermaid decision-tree diagrams; sibling `rules/` use Mermaid for decision-trees and sequence diagrams.
+- **Class 6 observed-state** — Mermaid renders inline in GitHub, GitLab, Bitbucket, Markdown editors (VS Code, Obsidian), and most doc generators (Fumadocs, Docusaurus, Sphinx via `myst-parser`); it diffs cleanly in version control and covers the full §1 diagram family.
+
+**Host override (M1 discipline).** Where the host has ratified a different notation — PlantUML, draw.io, Graphviz dot, ASCII-art, mermaid-py, or vendor-specific (Lucidchart, Miro, Excalidraw) — honor it per `rules/host-discovery.md`: walk the host's structural-artifact corpus (`docs/`, `architecture/`, `adr/`, `rfcs/`), count notation occurrences, adopt the dominant one. Where the host is silent, surface the choice as an inquiry per `rules/authority-inquiry.md` with Mermaid as the **Recommended** option per `rules/option-annotation.md`.
+
+### 4. Fidelity & Staleness — Current Reality Only
+
+Every diagram reflects **current reality**, never historical or aspirational state. Three fidelity invariants:
+
+1. **Same-change update.** A patch changing a structure (add a component, rename a state, reorder a precedence stack, add a permission row) updates the corresponding diagram in the same change. Splitting structure-change and diagram-update across two commits / PRs leaves the diagram stale at the boundary — non-conformant even when transient.
+2. **Staleness check.** Compare the `verified:` date against the modification date of the abstracted structure; when the structure is newer, the diagram is **stale**. The `diagram-staleness-grep` mechanical matcher flags stale diagrams at the pre-emission gate.
+3. **Aspirational-state declaration.** A diagram describing what the system *will* or *should* do (a target architecture, a future state) MUST carry the literal label `[Aspirational — target: <name>; date: <ISO-8601>]` in its metadata header AND as visible prose adjacent to it. An unlabelled aspirational diagram is non-conformant.
+
+### 5. Surface Imposition — Where Diagrams Land
+
+| Surface | Diagram obligation |
+|---|---|
+| `CLAUDE.md` | Carries the standing directive that structural subject matter draws (M9 row in §8 fifteen-mandate registry). |
+| `rules/*.md` | Decision-tree-bearing rules emit Mermaid `flowchart TD` per §1 row "Control flow". Architectural-discipline rules emit Mermaid `graph TD` per §1 row "Architecture". |
+| `skills/*/SKILL.md` | Multi-step procedures whose subject matter is structural emit a sequence diagram or flowchart in the procedure body. |
+| `agents/*.md` | Architectural-remit agents emit diagrams in their return format per `rules/canonical-layout.md`. |
+| `commands/*.md` | Pipeline-shaped commands emit a flowchart of the pipeline's decision-tree (every `commands/plan-*.md` carries a Mermaid `flowchart TD` of its workflow). |
+| `output-styles/*.md` | Preserve diagram blocks rather than flattening them — a concise output style does not collapse a Mermaid `flowchart` to a bulleted list. |
+| `hooks/messages/*.md` | Carry diagrams when the hook's subject matter is structural (the dispatcher's flow, the precedence stack of overlapping matchers). |
+| `conformity/*-grep.py` headers | Carry no diagrams (single-purpose scripts; structural surface is the dispatch tree at `conformity/gate.py`). |
+
+### 6. Failure Recovery — When a Diagram Is Missing or Stale
+
+- **Missing diagram on structural subject matter.** Author the diagram in the same change as the prose; never emit the prose-only artifact and defer the diagram — it is non-conformant at emission. Where the diagram needs data the agent lacks (e.g., a permission matrix depending on host-discovered scope), surface the gap as an inquiry per `rules/authority-inquiry.md` and mark the missing diagram a `<USER-CONFIRM:diagram-needs-data>` placeholder — which blocks emission per the pre-emission gate.
+- **Stale diagram detected.** Update the diagram and its `verified:` date in the same change that touched the structure. On a substantial rewrite, update `provenance:` to reflect it (`generated-from <source>` → `hand-authored` for a manual rewrite).
+- **Notation drift.** Convert a diagram in a non-ratified notation (e.g., Mermaid in a PlantUML-host project) at next touch. Mixed-notation corpora are a finding per M14 systemic participation.
+
+## Disclosure surface
+
+Every diagram emission, update, or staleness recovery is recorded in the disclosure ledger per `rules/disclosure-ledger.md`:
+
+- `[Diagram — emitted: <path>; class: <architecture | flowchart | sequence | state | dependency | hierarchy | precedence | matrix>; provenance: <provenance-form>; verified: <ISO-8601>]` for new diagrams.
+- `[Diagram — refreshed: <path>; reason: <staleness | structure-change | notation-conversion>; verified: <ISO-8601>]` for updates.
+- `[Diagram — deferred: subject matter is structural but the diagram requires <missing-data>; tracking: <USER-CONFIRM:id> | inquiry-id]` for cases where the diagram cannot be authored without further input.
+
+## Failure tells
+
+A 2,000-word architectural description with no diagram. An ADR that says "the new flow is …" in prose for ten paragraphs without an accompanying state diagram. A permission rule documented as a bulleted list of `(tool, scope, verdict)` triples instead of a matrix. A migration guide that lists steps in prose but draws no state machine of the migration's lifecycle. A diagram with no `verified:` date. A diagram whose `verified:` date precedes the latest modification of the structure it abstracts. A diagram in PlantUML in a host project where every other diagram is Mermaid (notation drift). An aspirational diagram presented as current reality without the `[Aspirational — …]` label. A "before / after" architecture comparison where only the "before" sketch is current and the "after" is undated. Multiple diagrams of the same subject matter scattered across the artifact corpus with conflicting depictions (no single source of truth).
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every structural-artifact emission across the ecosystem (every rule decision-tree, every command flowchart, every skill sequence diagram). ● The `diagram-staleness-grep` mechanical matcher at `conformity/diagram_staleness_grep.py` — operationalizes the §4 staleness check. ● Every Mermaid `%%` comment header carrying `provenance: …` + `verified: …` + `cross-reference: …`. ● The `verified:` date discipline at every `rules/*.md` Mermaid block. ◐ The aspirational-state declaration at every target-architecture diagram.
+- **Satisfies →** ● the fifteen-mandate registry row **M9 — Visual Leverage**. ● the Pre-Emission Gate row 9 (M9 visual leverage check).
+- **Established by ↑** ● the fifteen-mandate registry (ratifies M9). ● the Pre-Emission Gate row 9.
+- **Gated by ←** ● The trivial-vs-non-trivial threshold (trivial structural surfaces with unambiguous prose are exempt). ● `CLAUDE.md` always-loaded preamble. ● The path-filter declared in this rule's frontmatter (Markdown / docs / structural-artifact directories).
+- **Cross-bound with ↔** ↔ `rules/host-discovery.md` (M1 — host's existing notation overrides Mermaid default). ↔ `rules/authority-inquiry.md` (M5 — silent host on notation routes through inquiry surface). ↔ `rules/option-annotation.md` (M7 — every notation choice carries the Recommended marker plus concrete-driver rationale). ↔ `rules/bidirectional-binding.md` (M10 — diagram `cross-reference:` metadata is the M10 reciprocal-binding surface). ↔ `rules/pre-emission-gate.md` (M4 — bar 9 of the gate enforces this rule's diagram-presence check on structural subject matter). ↔ `rules/disclosure-ledger.md` (M2 — diagram emissions / refreshes / deferrals are recorded in the ledger).

package/src/apothem/schemas/NOTICE.md

@@ -0,0 +1,9 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# schemas/ — provenance notice
+
+The `.json`, `.yaml`, and `.txt` files in this directory are exempt from the canonical authorship-header per spec §4.6.4: JSON has no comment syntax, and the byte-exact `.yaml` / `.txt` fixtures consumed verbatim by matchers and installers cannot carry an in-band header without breaking those consumers. This `NOTICE.md` carries the canonical Markdown-variant SPDX license notice on behalf of the entire `schemas/` directory as a **directory-class provenance statement**: every header-exempt file alongside it is licensed under MIT through this notice. For a curated, purpose-and-consumer description of each file, see [`README.md`](README.md) — this notice does not duplicate that enumeration. The schemas validate frontmatter on `agents/`, `skills/`, `commands/`, and `output-styles/` artifacts inside this ecosystem, and on plan files authored in downstream projects. The Plan schema is consumed by `/plan-spec --quick` at plan-frontmatter authoring time so downstream-project plans can be validated without invoking the full prose-refinement pipeline.
+
+## License coverage
+
+This notice covers every header-exempt file in this directory — the `.json` schemas, the `.yaml` configuration and manifest files, and the `.txt` fixtures (including `__init__.py`'s sibling data files). The authoritative per-file purpose-and-consumer catalog lives in [`README.md`](README.md); when a new schema or fixture is added, it is described there rather than re-enumerated here.

package/src/apothem/schemas/README.md

@@ -0,0 +1,104 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Schemas
+
+JSON Schema definitions, configuration schemas, and fixture files — the validation surface for Apothem's artifact frontmatter and the canonical fixtures the conformity tooling reads. These files ship inside the installed wheel via `[tool.setuptools.package-data]` so downstream tooling can resolve them by package path.
+
+> **Provenance.** [`NOTICE.md`](NOTICE.md) carries the canonical single-line SPDX license header on behalf of every `.json` / `.yaml` / `.txt` file here — those formats cannot carry an in-band header. See `NOTICE.md` for the per-file provenance record; this README describes purpose and consumers.
+
+## Frontmatter schemas
+
+JSON Schema files validating the YAML frontmatter of apothem artifact classes.
+
+| File | Validates |
+|------|-----------|
+| [`agent.schema.json`](agent.schema.json) | Frontmatter of persistent agent definitions under [`../agents/`](../agents/). |
+| [`command.schema.json`](command.schema.json) | Frontmatter of slash-command definitions under [`../commands/`](../commands/). |
+| [`output-style.schema.json`](output-style.schema.json) | Frontmatter of output-style definitions under [`../output-styles/`](../output-styles/). |
+| [`skill.schema.json`](skill.schema.json) | Frontmatter of skill definitions under [`../skills/`](../skills/)`<name>/SKILL.md`. |
+| [`plan.schema.json`](plan.schema.json) | Frontmatter of downstream-project plan files; consumed by `/plan-spec --quick` so plans can be validated without the full prose-refinement pipeline. |
+| [`profile.schema.json`](profile.schema.json) | The apothem shared-profile configuration (`~/.config/apothem/profile.yaml`). |
+
+## Profile-schema versioning & migration
+
+The shared profile carries an optional top-level `schema_version` integer
+(minimum `1`). The contract is additive and forward-compatible:
+
+- **Optional, defaults to the current version.** A version-less profile is
+  treated as the current schema version and validates unchanged; existing
+  profiles need no edit.
+- **Current version is `1`.** The engine constant `_CURRENT_SCHEMA_VERSION` in
+  [`../lib/profile.py`](../lib/profile.py) is the source of truth.
+- **Additive migration shim.** `migrate_profile` runs at the top of
+  `validate_profile`, before schema validation. It forward-migrates a profile
+  to the current version through an ordered, append-only migration chain. The
+  v1 chain is a no-op — the profile is returned unchanged.
+- **Newer-than-supported is rejected early.** A profile stamped with a
+  `schema_version` greater than the engine supports raises a
+  `profile.version_unsupported` diagnostic — "the profile was written by a
+  newer apothem; upgrade the engine" — instead of an opaque
+  `additionalProperties` error. A non-integer `schema_version` is left for the
+  schema validator to reject.
+
+## Canonical `$id` host
+
+Every `*.schema.json` `$id` resolves under the canonical host
+`https://apothem.ahmedgad.com/schemas/<name>.schema.json` (filename segment
+preserved). `tests/unit/test_schema_id_host.py` asserts the invariant across
+the directory.
+
+## Configuration & manifest schemas
+
+| File | Purpose |
+|------|---------|
+| [`compatibility-matrix.yaml`](compatibility-matrix.yaml) | Cross-harness compatibility matrix — declares per-rule, per-agent, per-hook, per-output-style, per-skill, and per-schema compatibility across the apothem harness adapters. A reference artifact exposed via `schemas.compatibility_matrix_path()`; install-time asset resolution itself flows through `../lib/propagation-manifest.yaml` and `cohort-manifest.yaml`, not this matrix. |
+| [`cohort.schema.json`](cohort.schema.json) | Schema for the cohort manifest — defines the closed cohort set (`core`, `developer`, `security`, `research`, `ai-engineering`, `full`) and the `per_harness_targets` contract that resolves each cohort's native plugin target. Consumed by `cohort-manifest.yaml` (which validates against it) and `tests/unit/test_cohort_contract.py`. |
+| [`cohort-manifest.yaml`](cohort-manifest.yaml) | The cohort manifest itself — declares the six cohorts and their catalog member sets, validated against `cohort.schema.json`. Consumers resolve per-harness native targets through `per_harness_targets.source` (`../lib/propagation-manifest.yaml`); asserted by `tests/unit/test_cohort_contract.py`. |
+| [`plugin.schema.json`](plugin.schema.json) | Schema for the Claude Code plugin manifest (`.claude-plugin/plugin.json`) — the component-path contract for `commands`, `agents`, and `skills`. Consumed by `build_plugin_manifest` / `_validate_manifest` in [`../lib/plugin_tree.py`](../lib/plugin_tree.py). |
+| [`handoff-manifest.yaml`](handoff-manifest.yaml) | Manifest schema for cross-phase handoffs in the plan pipeline. |
+| [`advisory-finding.schema.json`](advisory-finding.schema.json) | Output contract for the advisory-mode conformance / security auditor and reporting surface — the finding shape (`id`, `category`, `severity`, `location`, `message`, `next_step`) plus the advisory semantics (findings reported, never blocking unless `strict`). |
+| [`header-visibility.yaml`](header-visibility.yaml) | Visibility configuration for authorship-header rendering across surfaces. |
+| [`cohort-metadata-vocabulary.yaml`](cohort-metadata-vocabulary.yaml) | Canonical repo-controlled vocabulary — status names, severity names, ownership classes, per-cohort frontmatter key sets (mechanical floor vs authoritative contract), version-field rules, output-contract field shapes, and exemption markers. Each entry names the live artifact (`controlled_by`) that owns its values; `tests/unit/test_cohort_metadata_vocabulary.py` asserts the live schemas and validators agree with the declared values, so drift on either surface fails the gate. |
+
+## Data-surface schemas
+
+Agnostic JSON Schema files validating the records of the memory, contexts, and
+continuous-learning surfaces. None carries a tool-specific or vendor-specific
+identifier, so the same record applies across every installation target.
+
+| File | Validates |
+|------|-----------|
+| [`memory-record.schema.json`](memory-record.schema.json) | One durable, operator-portable knowledge record in the memory surface — a fact, convention, preference, insight, or reference. |
+| [`context-fragment.schema.json`](context-fragment.schema.json) | One named, injectable prompt or context fragment with an enable/disable switch and activation metadata. |
+| [`learning-signal.schema.json`](learning-signal.schema.json) | One captured signal in the opt-in continuous-learning loop — the raw observation the capture stage records once the operator opts in. |
+
+## Fixtures
+
+| File | Purpose |
+|------|---------|
+| [`authorship-header.txt`](authorship-header.txt) | Byte-exact canonical authorship-header fixture (all variant families). The conformity tooling renders per-variant blocks from these lines. |
+| [`header-exceptions.txt`](header-exceptions.txt) | Glob list of file classes exempt from authorship-header injection — a pathspec fixture, one pattern per non-comment line. |
+| [`profile.example.yaml`](profile.example.yaml) | Worked example of a shared profile — copy to `~/.config/apothem/profile.yaml` and edit; validated against `profile.schema.json`. |
+| [`profile.minimal.yaml`](profile.minimal.yaml) | Minimal valid shared profile — the smallest profile that validates against `profile.schema.json`; consumed by `../cli/_helpers.py`, `__init__.py`, and the profile / rollback / learning tests. |
+| [`freshness-token-denylist.txt`](freshness-token-denylist.txt) | Denylist of legacy / deferral / replacement narrative tokens — read by `../conformity/freshness_token_grep.py` to enforce the current-version-only facade. |
+| [`reference-token-denylist.txt`](reference-token-denylist.txt) | Denylist of reference-platform brand / identifier tokens — read by `../conformity/reference_token_grep.py` to enforce own-voice reimplementation. |
+
+## Other contents
+
+- `__init__.py` — package marker making `apothem.schemas` importable so the schema files resolve by package path at runtime.
+- [`NOTICE.md`](NOTICE.md) — the directory's authorship-header carrier and provenance record (already present; not duplicated here).
+
+## Conventions
+
+- `.json` / `.yaml` / `.txt` files carry no in-band authorship header; `NOTICE.md` carries it for the directory class per the spec's authorship-header exception.
+- Frontmatter schemas are consumed by the PreToolUse Write hooks (frontmatter-compliance check) and by the ecosystem-audit skill.
+- All files in this directory ship in the installed wheel via the package-data declaration in `pyproject.toml`.
+
+## Operating in this folder
+
+- **Resolve-by-package-path ripple.** Matchers, installers, and the PreToolUse hooks resolve these files by package path, so a change here ripples to every consumer.
+- **Byte-exact fixtures are contracts.** `authorship-header.txt`, `header-exceptions.txt`, and the denylist fixtures are consumed verbatim by matchers and installers; their content is a contract, not free prose. A whitespace or line change ripples to every consumer — treat a fixture edit as a contract change and verify its matchers and installers still pass.
+- **Schema ↔ consumer agreement.** The cohort-metadata vocabulary and the live schemas must agree; a drift on either surface fails the gate. Change a frontmatter schema and its consuming validator in the same change-set.
+- **Agnostic data surfaces.** The memory / context / learning record schemas carry no tool-specific or vendor-specific identifier; keep them portable across every installation target.
+- **Adding or modifying a schema:** edit the `.json` / `.yaml` file (no SPDX line), update `NOTICE.md` if a new file class arrives, and update every consumer in the same change-set (the PreToolUse frontmatter check, the audit surface, or a validator that reads the schema).
+- Validate with `python -m apothem.conformity.gate --all .` and `python -m pytest` (the cohort-vocabulary test asserts schema/validator agreement).

package/src/apothem/schemas/__init__.py

@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: MIT
+
+"""Schemas, fixtures, and reference data packaged as Python resources.
+
+This package ships JSON schemas, YAML configuration fixtures, and text
+fixtures (banner, exceptions list) as importable package resources so
+runtime consumers resolve them via ``importlib.resources`` rather than
+filesystem-walks anchored against ``__file__``. The latter break in
+installed-package contexts where the relative layout differs from the
+source tree.
+
+Each public accessor returns a ``pathlib.Path`` pointing at the
+on-disk-materialized resource (sufficient for ``Path.read_text``,
+``Path.is_file``, and equality comparisons), or — for callers that need
+the abstract ``Traversable`` form — a direct ``.files()`` traversal is
+also exported.
+
+Example:
+    >>> from apothem.schemas import banner_path
+    >>> text = banner_path().read_text(encoding="utf-8")
+"""
+
+from __future__ import annotations
+
+from importlib.resources import as_file, files
+from pathlib import Path
+from typing import Final
+
+_PACKAGE: Final[str] = __name__
+
+_BANNER_NAME: Final[str] = "authorship-header.txt"
+_HEADER_EXCEPTIONS_NAME: Final[str] = "header-exceptions.txt"
+_HEADER_VISIBILITY_NAME: Final[str] = "header-visibility.yaml"
+_COMPATIBILITY_MATRIX_NAME: Final[str] = "compatibility-matrix.yaml"
+_HANDOFF_MANIFEST_NAME: Final[str] = "handoff-manifest.yaml"
+_PROFILE_EXAMPLE_NAME: Final[str] = "profile.example.yaml"
+_PROFILE_MINIMAL_NAME: Final[str] = "profile.minimal.yaml"
+
+_AGENT_SCHEMA_NAME: Final[str] = "agent.schema.json"
+_COMMAND_SCHEMA_NAME: Final[str] = "command.schema.json"
+_SKILL_SCHEMA_NAME: Final[str] = "skill.schema.json"
+_PLAN_SCHEMA_NAME: Final[str] = "plan.schema.json"
+_OUTPUT_STYLE_SCHEMA_NAME: Final[str] = "output-style.schema.json"
+_PROFILE_SCHEMA_NAME: Final[str] = "profile.schema.json"
+_ADVISORY_FINDING_SCHEMA_NAME: Final[str] = "advisory-finding.schema.json"
+_MEMORY_RECORD_SCHEMA_NAME: Final[str] = "memory-record.schema.json"
+_CONTEXT_FRAGMENT_SCHEMA_NAME: Final[str] = "context-fragment.schema.json"
+_LEARNING_SIGNAL_SCHEMA_NAME: Final[str] = "learning-signal.schema.json"
+
+
+def resource_path(name: str) -> Path:
+    """Return the on-disk path of a schema resource by filename.
+
+    Args:
+        name: The schema fixture's filename (e.g.,
+            ``"authorship-header.txt"``).
+
+    Returns:
+        A ``pathlib.Path`` to the resource. When the package is
+        installed from a wheel into a zipfile-based loader, the path
+        points at a materialized on-disk copy.
+
+    Raises:
+        FileNotFoundError: When the named resource is not bundled in
+            the installed package.
+    """
+    traversable = files(_PACKAGE) / name
+    with as_file(traversable) as concrete:
+        return Path(concrete)
+
+
+def banner_path() -> Path:
+    """Path to the canonical authorship-header fixture."""
+    return resource_path(_BANNER_NAME)
+
+
+def header_exceptions_path() -> Path:
+    """Path to the header-exceptions glob fixture."""
+    return resource_path(_HEADER_EXCEPTIONS_NAME)
+
+
+def header_visibility_path() -> Path:
+    """Path to the per-class header-visibility fixture."""
+    return resource_path(_HEADER_VISIBILITY_NAME)
+
+
+def compatibility_matrix_path() -> Path:
+    """Path to the harness compatibility matrix."""
+    return resource_path(_COMPATIBILITY_MATRIX_NAME)
+
+
+def handoff_manifest_schema_path() -> Path:
+    """Path to the plan-pipeline handoff-manifest schema."""
+    return resource_path(_HANDOFF_MANIFEST_NAME)
+
+
+def profile_example_path() -> Path:
+    """Path to the example user-profile fixture."""
+    return resource_path(_PROFILE_EXAMPLE_NAME)
+
+
+def profile_minimal_path() -> Path:
+    """Path to the minimal user-profile fixture."""
+    return resource_path(_PROFILE_MINIMAL_NAME)
+
+
+def agent_schema_path() -> Path:
+    """Path to the agent JSON schema."""
+    return resource_path(_AGENT_SCHEMA_NAME)
+
+
+def command_schema_path() -> Path:
+    """Path to the command JSON schema."""
+    return resource_path(_COMMAND_SCHEMA_NAME)
+
+
+def skill_schema_path() -> Path:
+    """Path to the skill JSON schema."""
+    return resource_path(_SKILL_SCHEMA_NAME)
+
+
+def plan_schema_path() -> Path:
+    """Path to the plan JSON schema."""
+    return resource_path(_PLAN_SCHEMA_NAME)
+
+
+def output_style_schema_path() -> Path:
+    """Path to the output-style JSON schema."""
+    return resource_path(_OUTPUT_STYLE_SCHEMA_NAME)
+
+
+def profile_schema_path() -> Path:
+    """Path to the user-profile JSON schema."""
+    return resource_path(_PROFILE_SCHEMA_NAME)
+
+
+def advisory_finding_schema_path() -> Path:
+    """Path to the advisory-mode auditor findings JSON schema."""
+    return resource_path(_ADVISORY_FINDING_SCHEMA_NAME)
+
+
+def memory_record_schema_path() -> Path:
+    """Path to the agnostic memory-record JSON schema."""
+    return resource_path(_MEMORY_RECORD_SCHEMA_NAME)
+
+
+def context_fragment_schema_path() -> Path:
+    """Path to the injectable context-fragment JSON schema."""
+    return resource_path(_CONTEXT_FRAGMENT_SCHEMA_NAME)
+
+
+def learning_signal_schema_path() -> Path:
+    """Path to the continuous-learning signal JSON schema."""
+    return resource_path(_LEARNING_SIGNAL_SCHEMA_NAME)
+
+
+__all__ = [
+    "advisory_finding_schema_path",
+    "agent_schema_path",
+    "banner_path",
+    "command_schema_path",
+    "compatibility_matrix_path",
+    "context_fragment_schema_path",
+    "handoff_manifest_schema_path",
+    "header_exceptions_path",
+    "header_visibility_path",
+    "learning_signal_schema_path",
+    "memory_record_schema_path",
+    "output_style_schema_path",
+    "plan_schema_path",
+    "profile_example_path",
+    "profile_minimal_path",
+    "profile_schema_path",
+    "resource_path",
+    "skill_schema_path",
+]

package/src/apothem/schemas/advisory-finding.schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://apothem.ahmedgad.com/schemas/advisory-finding.schema.json",
+  "title": "Apothem Advisory Auditor Findings",
+  "description": "Output contract for the advisory-mode conformance / security auditor and the advisory-mode reporting surface. Findings are ADVISORY by default: their presence reports issues but does not block, abort, or force failure on the end user unless the auditor runs with strict = true. Every finding carries a definitive next_step — the determinant advisory move the operator can take. An internal auditor error is itself reported as a finding (category = error), never swallowed.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["findings", "strict", "summary"],
+  "properties": {
+    "findings": {
+      "type": "array",
+      "description": "Every finding the auditor produced, in deterministic order.",
+      "items": {
+        "$ref": "#/$defs/finding"
+      }
+    },
+    "strict": {
+      "type": "boolean",
+      "default": false,
+      "description": "When false (the default), the auditor is advisory: it exits zero even with findings present. When true, findings-present forces a non-zero exit. Strict mode is opt-in, never the shipped default."
+    },
+    "summary": {
+      "$ref": "#/$defs/summary"
+    }
+  },
+  "$defs": {
+    "finding": {
+      "type": "object",
+      "description": "A single advisory finding. Always carries a definitive next_step.",
+      "additionalProperties": false,
+      "required": ["id", "category", "severity", "location", "message", "next_step"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable finding identifier (e.g., the matcher or check name)."
+        },
+        "category": {
+          "type": "string",
+          "enum": ["config-scan", "secret", "conformance", "error"],
+          "description": "config-scan: configuration-file scan finding. secret: secret-pattern detection (closed catalog). conformance: rule-based conformance finding. error: an internal auditor failure reported as a finding rather than a silent swallow or crash."
+        },
+        "severity": {
+          "type": "string",
+          "enum": ["HIGH", "MEDIUM", "LOW"],
+          "description": "Severity triage; advisory regardless of level."
+        },
+        "location": {
+          "$ref": "#/$defs/location"
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1,
+          "description": "What was found, stated specifically."
+        },
+        "next_step": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The determinant advisory move — the definitive next action the operator can take to resolve the finding. Always present and non-empty."
+        }
+      }
+    },
+    "location": {
+      "type": "object",
+      "description": "Where the finding was found.",
+      "additionalProperties": false,
+      "required": ["path"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Path to the artifact the finding concerns."
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based line number, when the finding is line-scoped."
+        },
+        "column": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based column number, when the finding is column-scoped."
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "description": "Aggregate finding counts for the run.",
+      "additionalProperties": false,
+      "required": ["total", "high", "medium", "low"],
+      "properties": {
+        "total": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "high": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "medium": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "low": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}