@ahmed-g-gad/apothem 0.1.1

package/src/apothem/schemas/handoff-manifest.yaml

@@ -0,0 +1,353 @@
+# SPDX-License-Identifier: MIT
+
+# Handoff Manifest Schema
+#
+# YAML-fronted schema specification for the Handoff Manifest carried through
+# the `/plan-*` pipeline. `plan-spec` creates the manifest; `plan-generate`,
+# `plan-review`, `plan-design`, and `plan-execute` augment it as they add
+# validated artifacts. Downstream commands refuse to proceed if the manifest is
+# missing, malformed, or violates the `p0-unresolved: 0` / `p1-unresolved: 0`
+# invariant.
+#
+# Manifest instances land at `{suite}/_inputs/handoff-manifest.yml` per the
+# command's Output table. Standalone invocations still emit the manifest with
+# `downstream: "none (standalone invocation)"` — terminal-ness is never silent.
+
+# -----------------------------------------------------------------------------
+# Field-level schema
+# -----------------------------------------------------------------------------
+
+command:
+  type: string
+  required: true
+  enum:
+    - plan-spec
+    - plan-generate
+    - plan-review
+    - plan-design
+    - plan-execute
+    - plan-status
+  description: |
+    The most recent command that emitted or augmented this manifest. The
+    canonical sequence is `plan-spec` → `plan-generate` → `plan-review` →
+    `plan-design` (conditional for architecture-bearing suites) →
+    `plan-execute`; `plan-status` is read-only but may report against the same
+    manifest shape.
+
+repository:
+  type: string
+  required: true
+  pattern: '^[a-z0-9][a-z0-9-]*$'
+  description: |
+    Repo-bound identifier per the work-root naming convention. Kebab-case,
+    starts with a letter or digit. Non-empty.
+
+mission:
+  type: string
+  required: true
+  pattern: '^[a-z0-9][a-z0-9-]*$'
+  description: |
+    Mission-bearing identifier per the work-root naming convention. Kebab-case,
+    starts with a letter or digit. Distinct from `repository`. Non-empty.
+
+created_at:
+  type: string
+  required: true
+  format: iso8601
+  description: |
+    Timestamp at G5 emission. ISO-8601 UTC with `Z` suffix. Example:
+    `2026-04-27T15:30:00Z`.
+
+invocation_sequence:
+  type: integer
+  required: true
+  minimum: 1
+  description: |
+    Monotonically increasing per-suite invocation counter. Initial run = 1;
+    each `--refine-existing` run increments by 1. Lets downstream commands
+    detect spec drift between consecutive Forge runs.
+
+downstream:
+  type: string
+  required: true
+  description: |
+    The downstream consumer. One of the canonical command paths
+    (`/plan-generate`, `/plan-review`, `/plan-design`, `/plan-execute`,
+    `/plan-status`) OR the literal string `none (standalone invocation)` per
+    the standalone-invocation discipline.
+
+p0-unresolved:
+  type: integer
+  required: true
+  enum: [0]
+  description: |
+    Count of P0-severity questionables that did not resolve at their gate and
+    do not carry a deferred-with-placeholder routing. The four-discipline
+    operational invariant requires this field to read `0`. A non-zero value is
+    a P0 integrity failure; downstream refuses to proceed.
+
+p1-unresolved:
+  type: integer
+  required: true
+  enum: [0]
+  description: |
+    Count of P1-severity questionables that did not resolve at their gate and
+    do not carry a deferred-with-placeholder routing. Required to read `0` per
+    the operational invariant. Non-zero = downstream refuses to proceed.
+
+placeholders:
+  type: array
+  required: true
+  items:
+    type: object
+    properties:
+      kind:
+        type: string
+        required: true
+        description: |
+          The questionable's kind tag (e.g., `identity`, `workroot-scheme`,
+          `ops-verification`). Joins to the Question-Resolution Audit row's
+          `trigger-category` and to the spec's inline placeholder.
+      defer-reason:
+        type: string
+        required: true
+        description: |
+          One sentence; cites the concrete reason deferral was selected over
+          inline resolution.
+      defer-timestamp:
+        type: string
+        required: true
+        format: iso8601
+        description: |
+          ISO-8601 UTC timestamp at deferral.
+      deferred-by-command:
+        type: string
+        required: true
+        enum:
+          - plan-spec
+          - plan-generate
+          - plan-review
+          - plan-design
+          - plan-execute
+        description: |
+          The command that surfaced and deferred the question.
+      resolve-by-gate:
+        type: string
+        required: true
+        description: |
+          The downstream gate at which resolution is expected. Either a named
+          gate of a downstream command (`/plan-generate G1` etc.) or the
+          literal `next-Forge-iteration` for refinement-loop deferrals.
+  description: |
+    Empty array `[]` is admissible when no questionable was deferred.
+    Otherwise carries one row per `<USER-CONFIRM:...>` placeholder embedded in
+    the emitted spec.
+
+appendices:
+  type: object
+  required: true
+  properties:
+    consideration_log:
+      type: object
+      properties:
+        path:
+          type: string
+          required: true
+          description: Path to the Consideration Log inside the emitted spec (e.g., `_spec/spec.md#appendix-a-consideration-log`).
+        row_count:
+          type: integer
+          required: true
+          minimum: 1
+    potency_map:
+      type: object
+      properties:
+        path:
+          type: string
+          required: true
+        row_count:
+          type: integer
+          required: true
+          minimum: 1
+    preservation_audit:
+      type: object
+      properties:
+        path:
+          type: string
+          required: true
+        l1_pass:
+          type: integer
+          required: true
+        l1_fail:
+          type: integer
+          required: true
+          enum: [0]
+        l2_pass:
+          type: integer
+          required: true
+        l2_fail:
+          type: integer
+          required: true
+          enum: [0]
+        l3_pass:
+          type: integer
+          required: true
+        l3_partial:
+          type: integer
+          required: true
+        l3_fail:
+          type: integer
+          required: true
+          enum: [0]
+    expertise_gap_log:
+      type: object
+      properties:
+        path:
+          type: string
+          required: true
+        applied_axes_count:
+          type: integer
+          required: true
+          minimum: 0
+          maximum: 7
+        not_applicable_axes_count:
+          type: integer
+          required: true
+          minimum: 0
+          maximum: 7
+        envelope_limited_axes_count:
+          type: integer
+          required: true
+          minimum: 0
+          maximum: 7
+    question_resolution_audit:
+      type: object
+      properties:
+        path:
+          type: string
+          required: true
+        row_count:
+          type: integer
+          required: true
+          minimum: 0
+        p0_count:
+          type: integer
+          required: true
+        p1_count:
+          type: integer
+          required: true
+        p2_count:
+          type: integer
+          required: true
+  description: |
+    Each of the five mandatory appendices reports its anchor + summary
+    statistics so downstream commands can verify the spec's appendix integrity
+    without re-parsing the spec body.
+
+plan_review:
+  type: object
+  required: false
+  properties:
+    scorecards_path:
+      type: string
+      required: false
+    verdict:
+      type: string
+      required: false
+      enum:
+        - pass
+        - fail
+        - not-run
+  description: |
+    Optional augmentation emitted by `/plan-review`. `/plan-design` consumes
+    this block at SHARED+ seriousness and refuses to author a design when the
+    review verdict is missing or failing.
+
+plan_design:
+  type: object
+  required: false
+  properties:
+    applicability:
+      type: string
+      required: false
+      enum:
+        - architecture-bearing
+        - non-architecture-bearing
+      description: |
+        Classification emitted by `/plan-design` or by the upstream review
+        handoff. `architecture-bearing` requires `artifact_path`;
+        `non-architecture-bearing` records an explicit skip and allows
+        `/plan-execute` to proceed without `_inputs/design.md`.
+    skipped_reason:
+      type: string
+      required: false
+      description: |
+        One-sentence rationale when `applicability` is
+        `non-architecture-bearing`; omitted for architecture-bearing suites.
+    artifact_path:
+      type: string
+      required: false
+      description: |
+        Path to the design artifact, normally `_inputs/design.md`.
+    design_gate:
+      type: object
+      required: false
+      description: |
+        Fifteen-bar validation-gate attestation emitted by `/plan-design`.
+    seven_axis_attestation:
+      type: object
+      required: false
+      description: |
+        Per-axis coverage against Architecture, Concurrency, Performance,
+        Security, Testing, Tooling, and Observability.
+    binding_matrix_summary:
+      type: object
+      required: false
+      description: |
+        Bidirectional Binding Matrix summary emitted when the design triggers
+        the matrix threshold.
+  description: |
+    Optional architecture-bearing augmentation emitted by `/plan-design`.
+    `/plan-execute` consumes this block for phases whose PHASE.md declares
+    architecture-bearing outputs; `/architecture-review` consumes the same
+    design artifact during the Audit Review Sequence.
+
+# -----------------------------------------------------------------------------
+# Worked example
+# -----------------------------------------------------------------------------
+#
+# command: plan-spec
+# repository: apothem
+# mission: database-migration-v2
+# created_at: 2026-04-27T15:30:00Z
+# invocation_sequence: 1
+# downstream: /plan-generate
+# p0-unresolved: 0
+# p1-unresolved: 0
+# placeholders: []
+# appendices:
+#   consideration_log:
+#     path: _spec/spec.md#appendix-a-consideration-log
+#     row_count: 38
+#   potency_map:
+#     path: _spec/spec.md#appendix-b-potency-map
+#     row_count: 47
+#   preservation_audit:
+#     path: _spec/spec.md#appendix-c-preservation-audit
+#     l1_pass: 124
+#     l1_fail: 0
+#     l2_pass: 47
+#     l2_fail: 0
+#     l3_pass: 12
+#     l3_partial: 0
+#     l3_fail: 0
+#   expertise_gap_log:
+#     path: _spec/spec.md#appendix-d-expertise-gap-log
+#     applied_axes_count: 5
+#     not_applicable_axes_count: 2
+#     envelope_limited_axes_count: 0
+#   question_resolution_audit:
+#     path: _spec/spec.md#appendix-e-question-resolution-audit
+#     row_count: 6
+#     p0_count: 0
+#     p1_count: 4
+#     p2_count: 2

package/src/apothem/schemas/header-exceptions.txt

@@ -0,0 +1,141 @@
+# schemas/header-exceptions.txt — final form
+#
+# Encodes the categorical authorship-header exception list from
+# spec §4.6.4 as a glob fixture. Each non-comment, non-blank line is a
+# pathspec relative to the working-tree root. Patterns honor
+# fnmatch-style globbing with `**` segment expansion (recursive
+# directory match), so `**/vendor/**` matches every file in any
+# `vendor/` subtree.
+#
+# Authored as a draft at the coverage-map sub-phase, ratified
+# operator-approved-as-is at the banner-ratification sub-phase, and
+# locked here at the fixture-and-injector sub-phase alongside the
+# canonical banner fixture (`schemas/authorship-header.txt`) and the
+# injector scripts (`scripts/inject-header.{sh,py}`). Any future
+# amendment requires re-firing the banner-ratification structured inquiry
+# and producing a new ratification record.
+#
+# Lines beginning with `#` are comments. Blank lines are ignored.
+
+# --- Fixture self-exemption ---------------------------------------------------
+# The canonical banner fixture IS the byte-exact banner content; injecting
+# the banner into the fixture would produce a recursive header-of-header.
+schemas/authorship-header.txt
+
+# --- Categorical filename exemptions -----------------------------------------
+# The legal instrument itself; carries its own copyright line that the
+# license-author-consistency validator verifies is present in LICENSE.
+LICENSE
+LICENSE.md
+LICENSE.txt
+NOTICE
+
+# Version string, single-line by convention.
+VERSION
+
+# --- Categorical extension exemptions ----------------------------------------
+# JSON has no comment syntax; sibling `<file>.NOTICE.md` carries
+# attribution where required.
+**/*.json
+
+# Lockfiles — machine-managed; banner would churn on every dependency
+# update and provoke spurious diffs.
+**/*.lock
+**/package-lock.json
+**/yarn.lock
+**/pnpm-lock.yaml
+**/Cargo.lock
+**/Pipfile.lock
+**/poetry.lock
+**/uv.lock
+**/go.sum
+
+# --- Vendored / third-party trees --------------------------------------------
+# Upstream attribution must not be overwritten with our banner. Apothem's
+# frozen vendored tree lives at `src/apothem/_vendor/` (leading underscore),
+# so `**/_vendor/**` is the load-bearing exemption; `**/vendor/**` is retained
+# for any future non-underscore vendored tree.
+**/_vendor/**
+**/vendor/**
+**/third_party/**
+**/node_modules/**
+
+# --- Audit / planning ephemera ------------------------------------------------
+# Out of scope of the published tree (gitignored). The canonical working
+# directory is `.apothem/` (plans, memory, learning, contexts); a legacy
+# `.plans/` tree is upgraded to `.apothem/plans/` via `apothem migrate-workspace`.
+.audit/**
+.apothem/**
+projects/**
+memory/**
+
+# --- Test fixtures ------------------------------------------------------------
+# Byte-exact text and claim-list fixtures consumed by the validators
+# at `src/apothem/conformity/`. Validators match the fixture content against
+# narrative-presence checks elsewhere in the tree, so injecting a
+# banner would corrupt the byte-exact reference. Test source files
+# (`test_*.py`, `conftest.py`) under `tests/fixtures/` carry the
+# banner; only the data fixtures themselves are exempt.
+tests/fixtures/**.yaml
+tests/fixtures/**.yml
+tests/fixtures/**.txt
+tests/fixtures/**.json
+
+# --- Empty-marker files -------------------------------------------------------
+# Semantically zero-byte; banner would defeat their purpose.
+**/.keep
+**/.gitkeep
+**/py.typed
+
+# --- Machine-parseable packaging manifest --------------------------------------
+# `.SRCINFO` is generated via `makepkg --printsrcinfo` from `PKGBUILD`. Its
+# parser admits only `key = value` rows under `pkgbase = ...` / `pkgname = ...`
+# stanzas and does not tolerate comment lines; injecting the banner would
+# produce a malformed manifest.
+**/.SRCINFO
+
+# --- Generated / minified -----------------------------------------------------
+# Generated files carry an upstream `Generated by ...` marker; minified
+# bundles are derived artifacts.
+**/*.min.js
+**/*.min.css
+**/generated/**
+
+# SVG is XML, and the XML comment that would carry the single-line SPDX
+# header cannot contain a `--` sequence, which is illegal inside an XML
+# comment and breaks parsers. SVG assets are covered by the asset
+# provenance README and generated raster outputs instead of an inline header.
+**/*.svg
+
+# --- Binary extensions --------------------------------------------------------
+# Banners cannot be embedded in opaque byte streams.
+**/*.png
+**/*.jpg
+**/*.jpeg
+**/*.gif
+**/*.ico
+**/*.webp
+**/*.pdf
+**/*.zip
+**/*.tar
+**/*.gz
+**/*.tgz
+**/*.7z
+**/*.rar
+**/*.exe
+**/*.dll
+**/*.so
+**/*.dylib
+**/*.bin
+**/*.pyc
+**/*.pyo
+**/*.woff
+**/*.woff2
+**/*.ttf
+**/*.otf
+**/*.eot
+**/*.mp3
+**/*.mp4
+**/*.webm
+**/*.mov
+**/*.avi

package/src/apothem/schemas/header-visibility.yaml

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: MIT
+
+# schemas/header-visibility.yaml
+#
+# Per-file-class visibility policy for the authorship-header banner
+# in Markdown files, per spec §4.6.5.
+#
+# - `invisible` (default): banner wrapped in `<!-- ... -->`, source-visible
+#   only; the rendered Markdown surface stays clean.
+# - `visible`: banner appears at the top of the rendered output as a
+#   plain text or fenced-code block; appropriate for stand-alone
+#   reference documents that benefit from immediately readable provenance.
+# - `special-rendered`: format-bound files (e.g., CHANGELOG.md per
+#   release-notes format) where the banner sits as a single
+#   HTML-comment block above the format header rather than being
+#   interleaved into the format body.
+#
+# An override at file scope is permitted with an inline marker
+# `<!-- header-visibility: visible -->` immediately after the banner;
+# the inline marker takes precedence over the per-class default.
+#
+# Authored at the fixture-and-injector sub-phase per the locked
+# banner-ratification policy; consumed by the injector
+# (`scripts/inject-header.{sh,py}`) when rendering Markdown variants.
+
+default-visibility: invisible
+
+class-overrides:
+  - class: spec-document
+    visibility: visible
+    pattern: "**/spec*.md"
+
+  - class: changelog
+    visibility: special-rendered
+    pattern: "**/CHANGELOG.md"
+
+  - class: license-readable
+    visibility: visible
+    pattern: "**/LICENSE.md"

package/src/apothem/schemas/learning-signal.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://apothem.ahmedgad.com/schemas/learning-signal.schema.json",
+  "title": "Apothem Learning Signal",
+  "description": "One captured signal in the opt-in continuous-learning loop. A signal is the raw observation the capture stage records when the operator has opted in; the extraction stage scores patterns over a set of signals. The shape is neutral: it carries no tool-specific or vendor-specific identifier.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "kind", "summary", "captured"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable signal identifier, unique within a learning store."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["correction", "confirmation", "observation"],
+      "description": "Signal taxonomy. correction: an operator corrected an action. confirmation: an operator confirmed an approach. observation: a recurring pattern noticed in the work."
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One-line statement of what was observed."
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Tags used to group related signals during pattern extraction.",
+      "default": []
+    },
+    "payload": {
+      "type": "object",
+      "description": "Free-form structured detail accompanying the signal.",
+      "additionalProperties": true,
+      "default": {}
+    },
+    "captured": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp the signal was captured."
+    }
+  }
+}

package/src/apothem/schemas/memory-record.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://apothem.ahmedgad.com/schemas/memory-record.schema.json",
+  "title": "Apothem Memory Record",
+  "description": "One durable, agnostic, operator-portable knowledge record in the memory surface. The record shape is neutral: it carries no tool-specific or vendor-specific identifier, so the same record round-trips between any two installation targets without loss. A record captures a stable fact, convention, preference, insight, or reference worth preserving across sessions.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "title", "body", "kind", "created"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable record identifier, unique within a memory store."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One-line summary used to decide relevance during recall."
+    },
+    "body": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The knowledge itself, stated specifically."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["fact", "convention", "preference", "insight", "reference"],
+      "description": "Record taxonomy. fact: a stable observed truth. convention: a ratified practice. preference: an operator-stated choice. insight: a derived lesson. reference: a pointer to an external resource."
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Discovery tags for recall filtering.",
+      "default": []
+    },
+    "created": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp the record was first written."
+    },
+    "updated": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp the record was last amended."
+    },
+    "source": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Provenance — where the knowledge came from (a session, a document, an operator statement)."
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Optional confidence in the record's accuracy, in the closed interval [0, 1]."
+    }
+  }
+}

package/src/apothem/schemas/output-style.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://apothem.ahmedgad.com/schemas/output-style.schema.json",
+  "title": "Output-style",
+  "description": "Frontmatter schema for output-style definitions under src/apothem/output-styles/. The required floor is name + description, matching the mechanical floor the conformity grep enforces on every cohort file; id, applies-to, version, and last-reviewed are optional extensions.",
+  "type": "object",
+  "required": ["name", "description"],
+  "additionalProperties": true,
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Stable kebab-case identifier for the output style.",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable style name shown in /output-style."
+    },
+    "description": {
+      "type": "string",
+      "description": "One- to two-sentence statement of the style's tone, format, and intended use."
+    },
+    "applies-to": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Artifact classes or contexts the style applies to."
+    },
+    "version": {
+      "type": "string",
+      "description": "SemVer version of the output-style definition.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "last-reviewed": {
+      "type": "string",
+      "description": "ISO 8601 date of last human review.",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    }
+  }
+}