@aperant/framework 0.6.4 → 0.6.6

package/templates/adr-format.md

@@ -0,0 +1,56 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/ADR-FORMAT.md
+Licensed under MIT. Modifications: ported as the Aperant ADR template
+emitted by `apt-tools adr write` with Nygard's 3-gate filter
+(hard-to-reverse AND surprising-without-context AND real-trade-off).
+-->
+
+# ADR-NNNN: {Title}
+
+**Status:** {Proposed | Accepted | Deprecated | Superseded}
+**Date:** {YYYY-MM-DD}
+
+## Context
+
+{What is the issue that we're seeing that is motivating this decision or
+change? Include enough background that a reader 12 months from now can
+understand WHY this decision was needed without reading the surrounding
+codebase. Cite empirical evidence, prior decisions, or codebase artifacts
+where possible.}
+
+## Decision
+
+{What is the change that we're proposing or have agreed to implement?
+State the decision in declarative terms — what WILL be done, not what
+might be considered.}
+
+## Consequences
+
+{What becomes easier or harder to do because of this change? Enumerate
+both the positive and negative consequences. The Nygard form is
+deliberately neutral — you list both upsides and downsides so a future
+reader can weigh whether the trade-off still holds.}
+
+---
+
+## Nygard 3-gate filter (audit trail)
+
+This ADR was written via `apt-tools adr write` and passed all three of
+Nygard's filter gates. If any one had failed, the decision would have
+stayed in `.aperant/context/notes/{task-id}.md` and no ADR file would
+have been created. The filter prevents ADR pollution — only durable,
+surprising, trade-off-bearing decisions become ADRs.
+
+- **Hard to reverse:** {true | false} — Could this be undone in a single
+  PR if we changed our minds in 6 months? If "yes, easily" → not an ADR.
+- **Surprising without context:** {true | false} — Would a new
+  contributor reading the code be surprised by this choice and want to
+  know why? If "no, this is the obvious approach" → not an ADR.
+- **Real trade-off:** {true | false} — Did we genuinely consider an
+  alternative and pick the worse-along-one-axis option for a
+  better-along-another? If "no, no alternative was real" → not an ADR.
+
+Reversible decisions, obvious decisions, and trade-off-free decisions
+all stay in context-notes — they survive the task but don't deserve a
+permanent ADR slot.

package/templates/config.json

@@ -106,6 +106,10 @@
 		"review_mode": "auto",
 		"debate_mode": "auto"
 	},
+	"diagram": {
+		"mode": "file",
+		"mcpConsent": null
+	},
 	"docs_policy": {
 		"$comment": "C33 docs-coherence policy. Override via /apt:setup Batch 7. Keys are globs/paths; values are 'auto-update' | 'flag-drift' | 'skip'. Missing block → defaults from packages/framework/templates/docs-policy-defaults.json apply."
 	},

package/templates/context-format.md

@@ -0,0 +1,34 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md
+Licensed under MIT. Modifications: ported as the Aperant CONTEXT.md
+template emitted by `apt-tools context write`. Adds the "Project glossary"
+header and example dialogue section.
+-->
+
+# Project glossary (CONTEXT.md)
+
+This file is the persistent project glossary. Each term-block carries the
+following fields per Pocock's CONTEXT.md format:
+
+- **{Term}** — definition (one line).
+  - **Aliases to avoid:** comma-separated synonyms or near-synonyms that
+    should NOT be used interchangeably. Prevents conflated-terminology
+    bugs that no amount of code review catches.
+  - **Cardinality:** one-to-one, one-to-many, many-to-many. When the
+    term refers to an entity, this is the relationship to its parent or
+    children.
+  - **Flagged ambiguities:** any known gray areas where the term is used
+    inconsistently in the codebase. Resolving these is part of the
+    grill loop.
+  - **Example dialogue:** a 1-2 turn example showing how the term is
+    used in a sentence (or in a UI label, error message, API field
+    name). Anchors the term to surface usage.
+
+`apt-tools context write` upserts term-blocks into this file. The writer
+is idempotent — re-running with the same `--term` overwrites the
+existing block in place. Fields not explicitly overridden are preserved.
+
+The format intentionally mirrors a domain glossary, not a code glossary.
+Terms are user-facing concepts (e.g., "Plan thread", "Sparring round"),
+not implementation details (e.g., "ChatSession", "useTaskStore").