@ahmed-g-gad/apothem 0.1.1

package/src/apothem/schemas/skill.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://apothem.ahmedgad.com/schemas/skill.schema.json",
+  "title": "Skill",
+  "description": "Frontmatter schema for skill definitions under src/apothem/skills/<name>/SKILL.md. Reconciled to the live skill corpus: every shipped SKILL.md carries name, description, version, updated, archetype, userInvocable, disable-model-invocation, and allowed-tools; argument-hint is optional. The agnostic posture forbids a model/effort/permission preset, so effort/model/permissionMode are not admitted keys.",
+  "type": "object",
+  "required": [
+    "allowed-tools",
+    "archetype",
+    "description",
+    "disable-model-invocation",
+    "name",
+    "updated",
+    "userInvocable",
+    "version"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Human-readable kebab-case name (matches the skill folder).",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "description": {
+      "type": "string",
+      "description": "Trigger-rich, capability-led description that surfaces detection signals so the harness routes matching requests to the skill. The shipped corpus uses dense trigger phrasing up to ~1.6k chars; the 2048 ceiling bounds the field while admitting the live convention.",
+      "maxLength": 2048
+    },
+    "version": {
+      "type": "string",
+      "description": "SemVer version of the skill definition.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "updated": {
+      "type": "string",
+      "description": "ISO 8601 date of the skill's last revision.",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    },
+    "archetype": {
+      "type": "string",
+      "description": "Shape class of the skill, named as a kebab-case '<class>-template' identifier (e.g. audit-template, authoring-template, workflow-template).",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*-template$"
+    },
+    "userInvocable": {
+      "type": "boolean",
+      "description": "Whether the operator can invoke the skill directly through the Skill tool."
+    },
+    "disable-model-invocation": {
+      "type": "boolean",
+      "description": "When true, the skill is reached only by explicit invocation, never auto-selected by the model from its description."
+    },
+    "allowed-tools": {
+      "type": "string",
+      "description": "Comma-separated list of tools the skill may invoke (e.g. \"Read, Write, Edit, Glob, Grep, Bash\"), or \"*\" for the full surface."
+    },
+    "argument-hint": {
+      "type": "string",
+      "description": "Optional usage hint shown to the operator describing the skill's accepted arguments and flags."
+    }
+  },
+  "examples": [
+    {
+      "name": "dependency-upgrade",
+      "description": "Changelog-reviewed, pinned, gate-verified dependency upgrade — matched when the operator asks to 'bump deps', 'upgrade dependencies', or 'refresh dependency versions'.",
+      "version": "0.1.0",
+      "updated": "2026-06-09",
+      "archetype": "maintenance-template",
+      "userInvocable": true,
+      "disable-model-invocation": true,
+      "allowed-tools": "Read, Write, Edit, Glob, Grep, Bash",
+      "argument-hint": "[--package NAME] [--dry-run]"
+    }
+  ]
+}

package/src/apothem/skills/README.md

@@ -0,0 +1,93 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Skills
+
+Skill definitions — reusable, detectable techniques the harness loads on demand. Each skill is **one folder** whose canonical entry point is `SKILL.md`: a Markdown file with YAML frontmatter declaring the skill's identity and trigger surface, and a body specifying the procedure.
+
+## Index
+
+| Skill | Purpose | Invocability |
+|-------|---------|--------------|
+| [`ecosystem-audit/`](ecosystem-audit/) | Blind audit of the apothem ecosystem — detects drift, staleness, orphans, dangling references, conflicting directives, frontmatter invalidity, registry-vs-disk count mismatches, secret exposure. Optionally applies FIX-class fixes under `--fix`. | User-invocable; also dispatchable from `/plan-execute` discovery context. |
+| [`plan-suite/`](plan-suite/) | Master Plan Suite template — houses the canonical template defining plan-suite structure, mandates, core principles, and the Technical Co-Founder Framework. | Not directly user-invocable; the `/plan` pipeline stages resolve the template by path. |
+| [`research-suite/`](research-suite/) | Research Suite knowledge surface — houses the canonical research-suite template defining the suite directory structure, the ten rigor mandates (R1–R10), the thirteen-stage research lifecycle, and the Principal-Investigator Framework. | Not directly user-invocable; the `/research` pipeline stages resolve the template by path. |
+| [`test-authoring/`](test-authoring/) | Behavior-first test authoring with strict Arrange-Act-Assert discipline — discovers a unit's behavior contracts, writes failing AAA assertions covering happy path, edge boundaries, and failure modes, and reports residual coverage gaps. Authors tests only. | User-invocable. |
+| [`refactor-extract/`](refactor-extract/) | Scoped behavior-preserving extraction refactor — extracts what the code does, clean-room re-derives from the extracted specification, elevates quality against a named deficiency, and verifies behavior is preserved. | User-invocable. |
+| [`dependency-upgrade/`](dependency-upgrade/) | Changelog-reviewed, pinned, gate-verified dependency upgrade — enumerates outdated dependencies, reviews each changelog for breaking changes, applies host-policy pinned bumps, and runs the host's lint / test / type-check gates. | User-invocable. |
+| [`incident-runbook/`](incident-runbook/) | Operational incident runbook authoring and execution — produces a Trigger → Diagnosis → Action → Verification → Rollback procedure where every action carries an explicit, tested rollback path. | User-invocable. |
+| [`secret-rotation/`](secret-rotation/) | Safe secret-rotation template — detects the exposure surface, revokes the compromised credential at its issuer, re-issues a replacement, rewires config through env-var or secret-manager indirection, and verifies no plaintext residue remains. | User-invocable. |
+| [`vuln-triage/`](vuln-triage/) | Vulnerability and security-advisory triage — severity-classifies an advisory, maps it to the affected surface, determines exploitability and reachability, routes remediation, and records the disposition with rationale. | User-invocable. |
+| [`multi-source-research/`](multi-source-research/) | Multi-source research harness — decomposes the question, fans out parallel source-discovery queries, fetches and extracts per source, adversarially verifies each claim against two or more independent sources, and synthesizes a cited report. | User-invocable. |
+| [`source-synthesis/`](source-synthesis/) | Reconcile a fixed set of provided sources into one cited synthesis — extracts the claim set per source, reconciles agreements and contradictions, and separates consensus from contested ground while flagging coverage gaps. | User-invocable. |
+| [`prompt-engineering/`](prompt-engineering/) | Design and eval-validate structured prompts — clarifies the task contract, drafts a structured prompt with explicit role / instructions / output schema, defines happy / edge / adversarial eval cases, and iterates against them. | User-invocable. |
+| [`eval-harness/`](eval-harness/) | Build and run reproducible LLM evaluation harnesses — defines a labeled dataset, a scorer with an explicit pass criterion, a candidate runner, and an aggregated metrics report with per-category breakdowns, confidence, and regression detection. | User-invocable. |
+| [`workflow/`](workflow/) | Workflow-harnessing orchestration — decomposes a mission, dispatches genuinely-independent multi-agent dynamic workflows under named return contracts, runs a refute-by-default verification pass before any finding survives, and self-augments from current authoritative sources. Multi-agent dispatch is opt-in / confirmation-gated. | User-invocable (entry form `/goal <<mission>>`). |
+| [`projectify/`](projectify/) | Chat-app Project elevation — produces the three deliverables (Description, Instruction, knowledge Files) for a Claude Project / ChatGPT Custom GPT / Gemini Gem through a structured-inquiry-saturated elicitation, holding knowledge files within a measurable per-platform context budget. | User-invocable. |
+| [`diagram-authoring/`](diagram-authoring/) | Diagram authoring and rendering — one author → validate → render → export pipeline covering declarative diagrams (flowchart / sequence / state / class / ER / gantt) and data-driven visualizations, exporting to SVG / PNG / PDF via a headless renderer. | User-invocable. |
+| [`document-authoring/`](document-authoring/) | Long-form structured-document authoring — an approval-gated outline → draft → review pipeline with verified citations (every reference resolves to a real source) and a deterministic compile pipeline routing engine / bibliography / index passes by detected source features. | User-invocable. |
+| [`dev-toolkit/`](dev-toolkit/) | Engineering-discipline toolkit — sequences the core loops (structured debugging, test-first red-green-refactor, vertical-slice decomposition, requirement-to-issue breakdown) into one composable, gated procedure; cross-references sibling capabilities (does not duplicate them). | User-invocable. |
+| [`surgical-guard/`](surgical-guard/) | Surgical-edit + reactive-guard — pairs a minimal-diff, anchor-bounded editing discipline with a post-edit diff-based quality guard (clean-code / test / docs checks with progressive rule loading); feeds the `surgical-manipulation` mandate. | User-invocable. |
+
+## What a skill is
+
+A skill packages a technique with a **detection signal** — the frontmatter `description` enumerates the phrasings or contexts that match the skill — and a **procedure** — the body that runs once matched. The harness surfaces a matched skill to the agent; the agent invokes it.
+
+## Progressive disclosure
+
+Skills load on demand. Keep `description` precise enough that the harness can
+match the skill from the user's request, touched paths, or task class without
+pulling unrelated procedures into baseline context. When a skill applies only to
+one subtree, name the subtree or file class in the detection signal and keep
+supporting references beside `SKILL.md` so the procedure can load them
+selectively.
+
+## The skill convention
+
+- **One folder per skill**, named in kebab-case, under `skills/`.
+- **Entry point is always `SKILL.md`** with YAML frontmatter validated against [`../schemas/skill.schema.json`](../schemas/skill.schema.json). Required frontmatter fields (per `skill.schema.json`): `name`, `version`, `updated`, `description` (the detection signal), `archetype` (the skill's shape class, e.g. `audit-template`, `workflow-template`), `userInvocable`, `disable-model-invocation`, and `allowed-tools`; the optional `argument-hint` field may also appear.
+- **Supporting files** live alongside `SKILL.md` in the same folder. The `plan-suite/` skill ships `master_template.md` — the canonical plan-suite template the `/plan` pipeline stages consume.
+- Every file carries the canonical single-line SPDX license header.
+
+## Folder contents
+
+| Path | Role |
+|------|------|
+| `ecosystem-audit/SKILL.md` | The audit skill's concise entry-point router. |
+| `ecosystem-audit/references/procedure.md` | The five-phase audit procedure, improvement-classification taxonomy, failure-recovery table, cadence guidance, and phase-thread diagram (progressively disclosed by the router). |
+| `ecosystem-audit/references/audit-fortress.md` | The Audit-Fortress Phase Skeleton (canonical flowchart + per-command parameter table) the eleven audit-fortress commands cite. |
+| `plan-suite/SKILL.md` | The plan-suite skill's entry point. |
+| `plan-suite/master_template.md` | The canonical Master Plan Suite template resolved by `/plan-spec`, `/plan-generate`, `/plan-review`, `/plan-audit`, `/plan-design`, `/plan-execute`, `/plan-status`. |
+| `research-suite/SKILL.md` | The research-suite skill's concise entry-point router. |
+| `research-suite/research_template.md` | The canonical Research Suite template resolved by the `/research-<stage>` commands. |
+| `research-suite/references/directory-structure.md` | The research-suite directory-structure map (progressively disclosed by the router). |
+| `research-suite/references/rigor-mandates.md` | The ten rigor mandates (R1–R10) in full (progressively disclosed by the router). |
+| `research-suite/references/lifecycle.md` | The thirteen-stage research lifecycle + per-stage invoking-surfaces table (progressively disclosed by the router). |
+| `research-suite/references/principal-investigator-framework.md` | The Principal-Investigator (PI) lens and its six commitments (progressively disclosed by the router). |
+| `test-authoring/SKILL.md` | The test-authoring skill's entry point and procedure. |
+| `refactor-extract/SKILL.md` | The refactor-extract skill's entry point and procedure. |
+| `dependency-upgrade/SKILL.md` | The dependency-upgrade skill's entry point and procedure. |
+| `incident-runbook/SKILL.md` | The incident-runbook skill's entry point and procedure. |
+| `secret-rotation/SKILL.md` | The secret-rotation skill's entry point and procedure. |
+| `vuln-triage/SKILL.md` | The vuln-triage skill's entry point and procedure. |
+| `multi-source-research/SKILL.md` | The multi-source-research skill's entry point and procedure. |
+| `source-synthesis/SKILL.md` | The source-synthesis skill's entry point and procedure. |
+| `prompt-engineering/SKILL.md` | The prompt-engineering skill's entry point and procedure. |
+| `eval-harness/SKILL.md` | The eval-harness skill's entry point and procedure. |
+| `workflow/SKILL.md` | The workflow-harnessing skill's entry point and procedure. |
+| `projectify/SKILL.md` | The projectify skill's entry point and procedure. |
+| `diagram-authoring/SKILL.md` | The diagram-authoring skill's entry point and procedure. |
+| `document-authoring/SKILL.md` | The document-authoring skill's entry point and procedure. |
+| `dev-toolkit/SKILL.md` | The dev-toolkit skill's entry point and procedure. |
+| `surgical-guard/SKILL.md` | The surgical-guard skill's entry point and procedure. |
+
+## Operating in this folder
+
+- **One folder per skill; the entry point is always `SKILL.md`,** never a differently-named file. The `description` frontmatter field is the match surface: make it precise enough that the harness selects the skill from the request, touched paths, or task class without pulling unrelated procedures into context.
+- **Keep supporting files self-loading and beside the entry point;** do not scatter a skill's references across the tree, so they load selectively with the procedure rather than into baseline context.
+- **Adding a skill:** create a new kebab-case subfolder, author its `SKILL.md` with valid frontmatter and an SPDX header, place supporting files beside it, then register the skill in the index and Folder-contents tables above and in any consuming command — in the same change-set. **Removing or renaming a skill** updates the same tables and every consumer in the same change-set.
+- Validate a change with `python -m apothem.conformity.gate --all .`, `python -m pytest`, and `python -m ruff check`.
+
+## Cross-references
+
+- The `/plan` pipeline stages that consume `plan-suite/` are under [`../commands/`](../commands/).
+- Convention and gap-detection discipline for skills is specified in `../rules/persistent-conventions-vigilance.md`.

package/src/apothem/skills/dependency-upgrade/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: "dependency-upgrade"
+version: "0.1.0"
+updated: "2026-06-09"
+description: "Changelog-reviewed, pinned, gate-verified dependency upgrade — matched when the operator asks to 'bump deps', 'upgrade dependencies', 'update packages', 'bump the lockfile', 'refresh dependency versions', or any phrasing requesting an audited version bump of the host project's third-party dependencies. Five-step loop: enumerate outdated dependencies from the host's manifest + lockfile, classify each candidate against its changelog (safe / breaking / major), apply pinned bumps honoring the host's discovered pin policy, run the host's lint / test / type-check gates, and report. Breaking and major candidates STOP for structured inquiry — never crossed silently. Idempotent (re-run on a current manifest yields zero bumps); --dry-run classifies without writing; --package NAME scopes to one dependency. Developer + security cohorts; user-invocable; honors host-discovered tooling and assumes no package manager."
+archetype: "maintenance-template"
+userInvocable: true
+argument-hint: "[--package NAME] [--dry-run]"
+disable-model-invocation: true
+allowed-tools: "Read, Write, Edit, Glob, Grep, Bash"
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+## Purpose
+
+Upgrade the host project's third-party dependencies under one discipline: **changelog-reviewed, pinned, gate-verified**. No bump lands without a breaking-change review of the candidate's changelog; every applied version honors the host's discovered pin policy; the host's full quality matrix is green before the change is reported complete. The skill bumps declared dependencies and lets the host's resolver own the transitive graph — its value is *audited safety*, not raw version-chasing.
+
+## Detection Signal
+
+The operator requests "bump deps", "upgrade dependencies", "update packages", "bump the lockfile", "refresh dependency versions", or any phrasing asking for an audited version bump of the host's third-party dependencies. Flags: `--package NAME` scopes the upgrade to one dependency; `--dry-run` enumerates and classifies without writing the bump.
+
+## Non-Goals
+
+A deliberately narrow surface — each boundary routes the out-of-scope work to its rightful owner:
+
+- **Not a transitive-resolver replacement.** Bumps declared dependencies and lets the host's package manager resolve the transitive graph; never hand-edits transitive pins or overrides the lock algorithm.
+- **Not a migration-code generator.** When a changelog names a breaking API change, surfaces the break for operator decision; never rewrites call sites. Code migration is a separate, operator-driven workstream.
+- **Not a security-advisory scanner.** Known-vulnerability detection is the host's audit tool (`pip-audit`, `npm audit`, `cargo audit`) under the host's CI; this skill reviews changelogs for breaking changes, not advisory databases.
+- **Not a major-version forcer.** A SemVer-major boundary is a version-pin inquiry category; never crossed silently — the crossing routes through the structured-inquiry channel.
+- **Not a manifest restructurer.** Bumps pins in place; never reorganizes dependency groups, splits runtime from development dependencies, or changes the declared pin policy. Manifest restructuring is operator-driven.
+
+## Workflow
+
+The five steps run in order; each carries a testable post-condition.
+
+1. **Enumerate outdated dependencies (host-discovery).** Walk the host's ratified manifest + lockfile per `rules/host-discovery.md`:
+
+   | Ecosystem | Manifest | Lockfile | Outdated-report command |
+   |-----------|----------|----------|-------------------------|
+   | Python | `pyproject.toml` / `requirements*.txt` / `Pipfile` | matching lock | `pip list --outdated` |
+   | Node | `package.json` | `package-lock.json` / `yarn.lock` / `pnpm-lock.yaml` | `npm outdated` |
+   | Rust | `Cargo.toml` | `Cargo.lock` | `cargo outdated` |
+   | Go | `go.mod` | `go.sum` | `go list -m -u all` |
+
+   Under `--package NAME`, narrow to the named dependency. **Testable:** the candidate set is the exact intersection of declared dependencies and the host outdated-report output.
+
+2. **Classify each candidate against its changelog.** For each candidate, read the project's changelog at its canonical source (CHANGELOG.md, the forge's Releases page, the registry's release notes) for every version between the installed pin and the upgrade target. Assign exactly one of three classes:
+
+   - `safe` — patch / minor with no breaking entry in range.
+   - `breaking` — a breaking entry in range (no major boundary crossed).
+   - `major` — crosses a SemVer-major boundary.
+
+   **Testable:** every candidate carries a class with its changelog source cited.
+
+3. **Apply the pinned version bump.** For `safe` candidates only, edit the manifest to the upgrade target honoring the host's discovered pin policy — exact `==X.Y.Z` where the host pins exactly; range operator (`^`, `~`, `>=`) where the host uses ranges. Regenerate the lockfile via the host's lock command (`pip-compile`, `npm install`, `cargo update -p NAME`, `go get`). `breaking` and `major` candidates STOP for structured inquiry before any write. Under `--dry-run`, write nothing. **Testable:** the manifest diff touches only the bumped pins, and each new pin matches the host's pin-policy shape.
+
+4. **Run the host's quality gates.** Execute the host's discovered lint, test, and type-check commands (`ruff check` / `pytest` / `mypy` for Python; `eslint` / the configured test runner / `tsc` for Node; the host's equivalents elsewhere). A gate failure traceable to a bump reverts that candidate and reclassifies it `breaking` for operator decision. **Testable:** every applied bump leaves the host's full gate matrix green, or is reverted.
+
+5. **Report.** Emit the upgrade report per the Return Contract — candidate set, per-candidate class with changelog source, applied bumps with before/after pins, gate outcomes, and the deferred `breaking` / `major` candidates with their inquiry records. **Testable:** the applied-bump count equals the count of `safe` candidates whose gates stayed green; the deferred count equals the `breaking` plus `major` count.
+
+**Idempotence.** A second invocation against an already-current manifest enumerates an empty candidate set at Step 1 and reports zero bumps. **Dry-run.** A `--dry-run` invocation stops after Step 2's classification with nothing written, so the operator reviews the proposed bumps and their changelog citations before committing to the manifest edit.
+
+## Return Contract
+
+Maximum response: 1500 tokens. Structure:
+
+- **Summary** — one sentence naming the count of candidates enumerated, bumped, and deferred.
+- **Applied bumps** — a table of `package · from · to · classification · gate-outcome`.
+- **Deferred** — `breaking` / `major` candidates with the changelog citation and the structured-inquiry record.
+- **Gate results** — the host's lint / test / type-check outcomes for the change-set.
+
+Under `--dry-run`, the Applied-bumps table reports the *proposed* bumps with no gate-outcome column; nothing is written.
+
+## Foundational Stanzas
+
+The four standing surfaces every operator inherits, adapted to this skill's user-invocable maintenance role.
+
+### Refusal & Escalation
+
+REFUSE any request to act outside the stated mission — migration-code generation, transitive-pin hand-editing, advisory scanning, silent major-version crossing. Refusal is explicit: name what was refused, name the mission boundary crossed, and surface an escalation option through the structured-inquiry channel per `rules/interactive-questions.md` (canonical channel; three-segment option annotation; never free-form prose as primary input). When the host exposes no recognizable manifest or lockfile, STOP and surface the discovery gap; never invent a package-manager convention.
+
+### Output Surface
+
+The primary output is the upgrade report (markdown) written to STDOUT. The bump itself edits the host's manifest and lockfile at their canonical locations per `rules/host-discovery.md`; per `rules/operational-mandates.md` CM-7, those edits carry natural domain language with zero plan-internal references. The change-set ships production-ready per `rules/production-ready-prs.md` — the bump, the regenerated lockfile, a CHANGELOG entry where the host maintains one, and a conformant commit message, all in one change-set. NEVER write the report or any scratch state to a global-ecosystem location or to a downstream project's `.apothem/plans/`.
+
+### File-Authoring Contract
+
+The skill edits manifest and lockfile artifacts in place; new files are rare. A NEW file routes through `scripts/inject-header.py` so the canonical single-line SPDX header is injected at the head — the injector is idempotent and detects the filetype variant automatically. Lockfiles and JSON config are header-exempt per `src/apothem/schemas/header-exceptions.txt`, so manifest and lock edits preserve the file's existing head. The header-inject-guard hook at `hooks/messages/pretooluse-{write,edit}-header-guard.md` enforces the contract at every Write / Edit invocation.
+
+### Structured Inquiry on Ambiguity
+
+At every version-pin decision per `rules/authority-inquiry.md` — which version of which dependency where the host has not pinned and the choice matters (security-relevant deps, behavioral-shift deps, SemVer-major boundaries) — when the host is silent, route the resolution through the structured-inquiry channel with the three-segment option annotation per `rules/interactive-questions.md` §3 (rationale / recommendation / default-pointer). Free-form prose questions as primary input are forbidden. NEVER fabricate a version pin. Every `breaking` and `major` candidate blocks its own bump until the operator resolves the inquiry; the upgrade target carries its changelog citation as the recommended-option rationale.
+
+## Recommended Next Step
+
+**Run the host's dependency-audit command** (`pip-audit`, `npm audit`, or `cargo audit`) against the upgraded change-set to confirm the bumps closed known advisories without introducing new ones before the change-set lands at its commit gate.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every dependency-upgrade engagement against a host project's manifest and lockfile. ● The changelog-review-before-bump discipline at every candidate. ● The host-pin-policy honoring at every applied version bump. ◐ The production-ready change-set shape (bump + lockfile + CHANGELOG + commit).
+- **Satisfies →** ● `CLAUDE.md` Source Layout row "dependency-upgrade" (skills/ class). ● The maintenance-template archetype's audited-version-bump mission.
+- **Established by ↑** ● `CLAUDE.md` Source Layout (skills/ class declaration with the folder-with-`SKILL.md` convention). ● `CLAUDE.md` Ambiguity Handling (structured inquiry over fabrication).
+- **Gated by ←** ● The harness's Bash tool surface (the outdated-report, lock-regeneration, and gate commands run through it). ● The presence of a recognizable host manifest and lockfile (host-discovery resolves the package manager).
+- **Cross-bound with ↔** ↔ `rules/host-discovery.md` (manifest / lockfile / pin-policy discovery). ↔ `rules/production-ready-prs.md` (the change-set ships tests + CHANGELOG + conformant commit in one set). ↔ `rules/interactive-questions.md` (version-pin inquiries route through the canonical channel). ↔ `skills/ecosystem-audit/SKILL.md` (sibling maintenance-tier skill).

package/src/apothem/skills/dev-toolkit/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: "dev-toolkit"
+version: "0.1.0"
+updated: "2026-06-14"
+description: "Engineering-discipline toolkit — matched when the operator asks to 'diagnose a bug', 'debug systematically', 'do TDD / write a failing test first', 'break this into vertical slices', 'turn this into a PRD / issues', 'decompose this work', or otherwise needs a disciplined software-engineering loop rather than an ad-hoc fix. Sequences four named, gated, composable loops — structured debugging (reproduce → minimize → hypothesize → instrument → fix root cause), test-first red-green-refactor (red observed before green), vertical-slice decomposition (independently-shippable testable units), and requirement-to-issue breakdown (goal → testable requirement set → tracked issues + ADR) — selected by --mode or by the request. Cross-references (never duplicates) sibling owners: orchestration → /workflow, diagrams → diagram-authoring, minimal-diff guarding → surgical-guard. Harness-agnostic; deterministic output; drives the host's discovered toolchain."
+archetype: "engineering-template"
+userInvocable: true
+argument-hint: "[task or defect] [--mode diagnose|tdd|slice|decompose]"
+disable-model-invocation: true
+allowed-tools: "Read, Write, Edit, Glob, Grep, Bash, TodoWrite"
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+## Purpose
+
+Apply a disciplined software-engineering loop to a task or defect instead of an ad-hoc fix. The skill sequences four core loops into one composable, gated procedure:
+
+- **structured debugging** — reproduce → minimize → hypothesize → instrument → fix root cause;
+- **test-first development** — red → green → refactor (red observed, never assumed);
+- **vertical-slice decomposition** — break work into independently-shippable, independently-testable units;
+- **requirement-to-issue breakdown** — turn a goal into a testable requirement set, then tracked issues + an ADR.
+
+Its value is **expressiveness**: the loops are *named and sequenced* so the engineering intent is legible, rather than scattered across unrelated one-off commands.
+
+## Detection Signal
+
+The operator asks to diagnose / debug systematically, write a failing test first (TDD), break work into vertical slices, turn a goal into a PRD / issues, or decompose a non-trivial task. A request that one direct edit resolves is below this skill's threshold.
+
+## Non-Goals
+
+Each boundary routes the out-of-scope work to its canonical owner — encoding the EF-2 single-source-of-truth principle. The source toolkits this skill is reauthored from bundled orchestration, diagramming, and guarding together; apothem keeps each capability with its owner and cross-references rather than duplicating.
+
+- **Not a multi-agent orchestrator.** Parallel agent dispatch, background-agent management, and git-worktree isolation route to `/workflow` (the orchestration owner) — this skill applies the engineering loops, it does not orchestrate agents.
+- **Not a diagram tool.** Technical diagrams (architecture, sequence, data-flow) route to `diagram-authoring` — this skill references a diagram, it does not render one.
+- **Not a guard / surgical-edit tool.** Minimal-diff editing discipline and post-edit quality guarding route to `surgical-guard` — this skill produces the change, that skill guards how it lands.
+- **Not a host-tool replacement.** It drives the host's discovered test runner / linter / type-checker; it ships none of its own. The toolchain is discovered, not assumed.
+
+## Conformity Posture
+
+- **Discover-don't-assume preamble (M1).** Discover the host's test runner, linter, type-checker, and issue / ADR conventions per `rules/host-discovery.md`; the loops drive the host's ratified tools, not assumed ones. Record discoveries with provenance.
+- **Search-before-implement (CM-4).** Before authoring a fix or a slice, search the codebase for the reusable component — the engineering loops begin from the host's actual state.
+
+## Procedure
+
+The skill selects the loop by `--mode` (or by the request when `--mode` is unset); the loops compose. Every loop is **gated** — a step does not advance until its gate is satisfied.
+
+### Mode: diagnose — Structured Debugging
+
+`reproduce → minimize → hypothesize → instrument → fix → verify`
+
+Reproduce the defect (a failing observation) → minimize to the smallest reproducing case → hypothesize the root cause → instrument to confirm or refute the hypothesis → fix the **root cause** (not the symptom, per CM-8) → verify the reproduction now passes. **Gates:** no fix before a confirmed hypothesis; no "done" before the minimized reproduction passes.
+
+### Mode: tdd — Red-Green-Refactor
+
+`red → green → refactor`
+
+Write a behavioral test that **fails first** (red — observed failing, never assumed) → implement the minimum to pass (green) → refactor with the test as the safety net (refactor). **Gate:** the red observation — a green claimed without a prior observed red is non-conformant.
+
+### Mode: slice — Vertical-Slice Decomposition
+
+Break the work into independently-shippable, independently-testable vertical slices — each delivers observable value end-to-end and carries its own acceptance criteria + test. **Gate:** surface the slice boundaries for approval where they are non-obvious.
+
+### Mode: decompose — Requirement-to-Issue Breakdown
+
+Turn the goal into a structured requirement set (each requirement testable) → then into tracked issues at the host's discovered issue surface → recording an ADR where the decomposition embeds a durable design decision. Domain vocabulary is captured once (a shared context document) so the requirements read coherently. **Gate:** no requirement without a testable acceptance criterion.
+
+### Self-Check (every mode)
+
+Run the host's discovered quality gates (lint / type-check / test) and the fifteen-bar pre-emission gate per `rules/pre-emission-gate.md` against every emitted artifact. Emit the change / decomposition plus the single recommended next move.
+
+## Arguments
+
+- `[task or defect]` — the task to engineer or the defect to diagnose, in natural language.
+- `--mode diagnose|tdd|slice|decompose` — the engineering loop (default: selected by the request).
+
+## Return Contract
+
+The mode's deliverable, plus the host-gate results, the fifteen-bar attestation, and a single `## Recommended Next Step`:
+
+| `--mode` | Deliverable |
+|----------|-------------|
+| `diagnose` | the root-cause fix + the passing-reproduction verification |
+| `tdd` | the red→green→refactor change (with the observed-red evidence) |
+| `slice` | the slice set, each with acceptance criteria + a test |
+| `decompose` | the requirement set + tracked issues + the ADR |
+
+Deterministic per `rules/determinism.md` — the same task + host state yields the same loop output.
+
+## Foundational Stanzas
+
+The four standing surfaces every operator inherits per the canonical project voice at `AGENTS.md` plus the active harness mirror.
+
+### Refusal & Escalation
+
+REFUSE any request beyond the engineering loops — name what was refused, name the boundary crossed, surface an escalation option through the structured-inquiry channel per `rules/interactive-questions.md`. REFUSE a "fix" that addresses a symptom when the structured-debugging loop has not isolated the root cause — surface the unfinished diagnosis instead. REFUSE marking a TDD cycle green when the test was not first observed failing (red).
+
+### Output Surface
+
+Code changes, tests, and decomposition artifacts land at their domain-natural host locations per `rules/host-discovery.md`. Per CM-7, every artifact carries natural domain language — zero engineering-process-internal scaffolding. NEVER write a plan artifact outside the active suite.
+
+### File-Authoring Contract
+
+Every NEW code / test file routes through `scripts/inject-header.{sh,py}` for the canonical SPDX banner (fixture at `src/apothem/schemas/authorship-header.txt`); exempt classes at `src/apothem/schemas/header-exceptions.txt`. Edits preserve any existing banner; the header-inject-guard hook enforces the contract. Code honors the host's per-language code-craft conventions (discovered).
+
+### Structured Inquiry on Ambiguity
+
+When the task's acceptance criteria, the slice boundaries, the reproduction steps, or the requirement scope are ambiguous, route the resolution through the structured-inquiry channel with the three-segment option annotation per `rules/interactive-questions.md` §3. NEVER fabricate a reproduction, a requirement, or a test expectation.
+
+## Recommended Next Step
+
+**Invoke the `dev-toolkit` skill via the Skill tool** with `<task> --mode <diagnose|tdd|slice|decompose>` — run the selected loop to its gate, then route any surfaced orchestration to `/workflow`, any diagram to the `diagram-authoring` skill, and the change's landing discipline to the `surgical-guard` skill. Re-run in `decompose` mode first when the task is large enough to need slicing before implementation.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every disciplined engineering loop applied to a host task or defect. ● The host's discovered quality gates at the Self-Check step. ◐ Cross-references to `/workflow`, `diagram-authoring`, `surgical-guard` for the out-of-scope overlaps (EF-2 boundary).
+- **Satisfies →** ● `CLAUDE.md` Source Layout row "dev-toolkit" (skills/ class). ● The elevation dimension **expressiveness** (named, sequenced, composable engineering loops vs. a loose bag of commands). ● `rules/operational-mandates.md` (CM-4 search-before-implement; CM-8 root-cause-not-symptom).
+- **Established by ↑** ● `CLAUDE.md` Source Layout (skills/ folder-with-`SKILL.md` class). ● `CLAUDE.md` Ambiguity Handling (structured inquiry over fabrication). ● `rules/own-voice-reimplementation.md` (zero-verbatim; `reference-token-grep` = 0). ● `rules/agnostic-posture.md` (17-harness agnostic floor).
+- **Gated by ←** ● The host's discovered test runner / linter / type-checker (the gap is surfaced where absent). ● The per-mode gates (no fix before confirmed hypothesis; no green before red). ● The host's structured-inquiry + Edit + Write + Bash tool surface.
+- **Cross-bound with ↔** ↔ `skills/workflow/SKILL.md` (orchestration owner — overlaps route there). ↔ `skills/diagram-authoring/SKILL.md` (diagram owner). ↔ `skills/surgical-guard/SKILL.md` (minimal-diff + guard owner; this skill produces the change, that skill guards how it lands). ↔ `rules/own-voice-reimplementation.md` + `rules/agnostic-posture.md` (own-voice + agnostic floors). ↔ `skills/document-authoring/SKILL.md` (sibling own-voice authoring skill).

package/src/apothem/skills/diagram-authoring/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: "diagram-authoring"
+version: "0.1.0"
+updated: "2026-06-14"
+description: "Diagram authoring and rendering — matched when the operator asks to 'draw a diagram', 'make a flowchart / sequence / state / ER / architecture diagram', 'author a data visualization', 'render this Mermaid', 'export a diagram to SVG/PNG/PDF', or otherwise needs a structural picture authored and rendered. One deterministic pipeline — pick notation by subject → author source → validate syntax → render → export — spanning declarative diagrams (flowchart / sequence / state / class / ER / gantt / mindmap) and data-driven visualizations (bar / line / scatter / network / hierarchy / geo). Correct-by-construction (validated before render) and portable (SVG / PNG / PDF via a discovered headless renderer). Not for: shipping or assuming a vendor render server (the renderer is discovered, never bundled); fabricating a visualization's dataset (supplied or discovered, never invented); illustrating non-structural prose a paragraph already carries. Harness-agnostic; deterministic output."
+archetype: "authoring-template"
+userInvocable: true
+argument-hint: "[diagram subject] [--notation auto|declarative|data-driven] [--format svg|png|pdf]"
+disable-model-invocation: true
+allowed-tools: "Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch"
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+## Purpose
+
+Author a structural picture — a flowchart, sequence, state machine, class / ER model, gantt, mindmap, or a data-driven visualization (bar, line, scatter, network, hierarchy, geographic) — and render it to a shareable image through one deterministic pipeline:
+
+**pick the notation from the subject → author the source → validate the syntax → render → export.**
+
+The skill unifies declarative diagram authoring and data-driven visualization behind a single procedure and a single validate-then-render contract, so a diagram is **correct-by-construction** (validated before render) and **portable** (exported to SVG / PNG / PDF) regardless of which notation the subject called for.
+
+## Detection Signal
+
+The operator asks to "draw / author a diagram", names a diagram class (flowchart, sequence, state, class, ER, gantt, mindmap, architecture), asks for a "data visualization" / "chart" / "graph" of a dataset, asks to "render" diagram source to an image, or asks to "export" a diagram to a file format. A request to embed a diagram inside a structural document also routes here (the `document-authoring` skill consumes this skill's render output).
+
+## Non-Goals
+
+- **Not a bundled rendering server.** A deterministic procedure that invokes whatever diagram renderer the host makes available (a headless diagram CLI, a headless browser, or a render service in the MCP inventory) — it ships or assumes no specific vendor's server. The renderer is discovered, not bundled.
+- **Not a notation monoculture.** It selects the right notation for the subject — declarative diagram grammar for relationship / flow / state pictures, a data-viz grammar for quantitative pictures — never forcing one notation onto every subject.
+- **Not an unvalidated emitter.** Diagram source is syntax-validated before render; a render of invalid source is a failure surfaced with the offending construct, not a silently-broken image.
+
+## Conformity Posture
+
+- **Discover-don't-assume preamble (M1).** Discover the host's available diagram renderer and its invocation (a headless diagram CLI on PATH, a headless browser, or an MCP-registered render service) per `rules/host-discovery.md`, and the host's diagram-asset directory convention. Record each with provenance. The renderer is never assumed — it is discovered, and where absent the gap is surfaced.
+- **Visual-leverage alignment (M9).** Authored diagrams carry the provenance + `verified:` date metadata per `rules/visual-leverage.md`, so the picture reflects current reality, not aspirational or stale state.
+
+## Procedure
+
+### 1. Frame the Subject & Pick the Notation
+
+Read the subject and classify it:
+
+| Subject class | Notation family | Members |
+|---------------|-----------------|---------|
+| relationship / flow / state / structure | declarative diagram grammar | flowchart, sequence, state, class, ER, gantt, mindmap |
+| quantitative / dataset | data-viz grammar | bar, line, scatter, network, hierarchy, geographic |
+
+Under `--notation auto` (default) the classification is by subject; when ambiguous, inquire. Record the chosen notation and why.
+
+### 2. Author the Diagram Source
+
+Author the source in the chosen notation, derived from the subject's intent (the structure to depict, the data to plot). For data-driven visualizations, bind the supplied / discovered dataset to the visual encoding (axes, scales, marks, color) **deterministically** — the same dataset produces the same picture. Keep the source human-readable and diffable (text source over binary where the notation permits).
+
+### 3. Validate Before Render
+
+Validate the source syntax before any render — parse the declarative grammar or the data-viz spec. On a parse error, surface the offending construct and halt; never render invalid source into a broken image. This validate-then-render contract is the skill's robustness floor.
+
+### 4. Render & Export
+
+Render the validated source to an image via the discovered renderer; export to the requested `--format`:
+
+- **SVG** (default) — scalable, diffable.
+- **PNG** — raster embedding.
+- **PDF** — print.
+
+When the render reports a *recoverable* error (a layout overflow, an unsupported construct), apply **one** corrective pass (adjust the construct → re-validate → re-render) before surfacing failure — a bounded validate→correct→re-render loop, never unbounded retry.
+
+### 5. Self-Check & Emit
+
+Attach the provenance + `verified:` metadata. Run the fifteen-bar pre-emission gate per `rules/pre-emission-gate.md` against the emitted source + image. Emit the diagram source, the rendered image, and the single recommended next move.
+
+## Arguments
+
+- `[diagram subject]` — the structure or dataset to depict, in natural language.
+- `--notation auto|declarative|data-driven` — notation family (default: `auto`, classified by subject).
+- `--format svg|png|pdf` — export format (default: `svg`).
+
+## Return Contract
+
+The diagram **source** (text, diffable, with provenance + `verified:` metadata), the rendered **image** at the chosen format, the **notation choice + rationale**, and a single `## Recommended Next Step`. Deterministic per `rules/determinism.md`: the same subject + dataset + notation produces byte-stable source and a reproducible render. The rendered binary's exact bytes may vary with the discovered renderer version — the declared non-deterministic element, stamped with the renderer + version.
+
+## Foundational Stanzas
+
+The four standing surfaces every operator inherits per the canonical project voice at `AGENTS.md` plus the active harness mirror.
+
+### Refusal & Escalation
+
+REFUSE any request beyond authoring and rendering a diagram — name what was refused, name the boundary crossed, surface an escalation option through the structured-inquiry channel per `rules/interactive-questions.md`. REFUSE emitting an image from source that failed syntax validation — surface the validation error and the offending construct instead. When the subject is ambiguous between two notations, surface the choice; never guess.
+
+### Output Surface
+
+Diagram source and rendered images land at the operator's chosen location (a structural document's asset directory, a plan suite's working surface, or an operator-named path) per host-discovery and the suite-locality invariant at `rules/context-management.md` §2.6.1. Diagram source carries a provenance + verification-date comment per `rules/visual-leverage.md` so the rendered picture is auditable against the reality it abstracts. Per CM-7, the diagram describes its subject in natural domain language.
+
+### File-Authoring Contract
+
+Diagram-source files (a `.mmd` / `.svg` / data-viz spec) authored as host-project artifacts route through `scripts/inject-header.{sh,py}` where the filetype carries a header variant; rendered binary images (`.png` / `.pdf`) are header-exempt per `src/apothem/schemas/header-exceptions.txt`. Edits preserve any existing banner; the header-inject-guard hook enforces the contract.
+
+### Structured Inquiry on Ambiguity
+
+When the notation, the diagram class, the dataset shape, the target format, or the rendering surface is ambiguous, route the resolution through the structured-inquiry channel with the three-segment option annotation per `rules/interactive-questions.md` §3. NEVER fabricate the data a visualization plots — the dataset is supplied or discovered, never invented.
+
+## Recommended Next Step
+
+**Invoke the `diagram-authoring` skill via the Skill tool** with `<subject> --notation auto --format svg` — review the validated source and the rendered SVG, then embed the source (not just the image) in the consuming document so the picture stays diffable and re-renderable. Re-run with `--notation` set explicitly when the subject spans both a structural and a quantitative view.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every authored-and-rendered diagram across the host's structural artifacts. ● The validate-then-render contract that gates every image emission. ◐ The document-authoring skill, which consumes this skill's render output for embedded figures.
+- **Satisfies →** ● `CLAUDE.md` Source Layout row "diagram-authoring" (skills/ class). ● The elevation dimension **structural novelty** (one unified author→validate→render→export pipeline across declarative + data-driven notation — a shape no single source capability carries alone). ● `rules/visual-leverage.md` (M9 diagram provenance + verification-date discipline).
+- **Established by ↑** ● `CLAUDE.md` Source Layout (skills/ folder-with-`SKILL.md` class). ● `CLAUDE.md` Ambiguity Handling (structured inquiry over fabrication). ● `rules/own-voice-reimplementation.md` (zero-verbatim own-voice; `reference-token-grep` = 0). ● `rules/agnostic-posture.md` (17-harness agnostic floor).
+- **Gated by ←** ● A discovered diagram renderer (the gap is surfaced where absent). ● The host's structured-inquiry + Edit + Write + Bash tool surface. ● A statable subject (and, for data-viz, a supplied / discovered dataset — never invented).
+- **Cross-bound with ↔** ↔ `rules/visual-leverage.md` (M9 — provenance + `verified:` metadata; this skill is the authoring instrument for the diagrams that rule mandates). ↔ `rules/own-voice-reimplementation.md` + `rules/agnostic-posture.md` (own-voice + agnostic floors). ↔ `rules/determinism.md` (deterministic pipeline). ↔ `skills/document-authoring/SKILL.md` (sibling own-voice authoring skill; consumes this skill's render output for embedded figures).