feat: AGT-inspired governance improvements — severity registry, trust tiers, limitations doc, conformance manifest

.documentation/memory/constitution.md

@@ -149,4 +149,10 @@ This constitution supersedes all other development practices in the DevSpark rep
 Amendments require: documentation of the change, leadership approval, and a migration plan for any
 affected workflows or repositories.
 
+## Companion Documents
+
+- [Known Governance Limitations](known-limitations.md)
+- [Severity Registry](severity-registry.md)
+- [Prompt Conformance Manifest](prompt-conformance-manifest.md)
+
 **Version**: 1.4.0 | **Ratified**: 2026-04-06 | **Last Amended**: 2026-05-22

.documentation/memory/known-limitations.md

@@ -0,0 +1,117 @@
+---
+document: known-limitations
+version: "1.0.0"
+created: "2026-06-03"
+related: .documentation/memory/constitution.md
+---
+
+# DevSpark — Known Governance Limitations
+
+This document catalogues what DevSpark does **not** govern, with honest rationale for each
+gap. It exists so adopters can make informed decisions about complementary tooling before
+discovering a gap in production.
+
+## What DevSpark Governs
+
+DevSpark governs the **development process** that produces AI-assisted software: it provides
+spec-driven workflows, constitution-based quality gates, and right-sized execution paths.
+A human developer is always in the loop. DevSpark reviews artifacts (specs, plans, tasks,
+PRs) — it does not enforce runtime behavior of the systems those artifacts describe.
+
+## Known Limitations
+
+### L-001 — Runtime Agent Behavior
+
+**Scope**: DevSpark does not govern what AI agents do at runtime in production systems.
+
+**Rationale**: DevSpark operates in developer workflows where a human is always present.
+Runtime enforcement (cryptographic identity, policy engines, execution rings, audit chains)
+is infrastructure suited to autonomous multi-agent production environments — not to
+spec-driven development tooling. Adding such machinery would violate §V Simplicity.
+
+**Complementary tooling**: [Microsoft Agent Governance Toolkit (AGT)](https://github.com/microsoft/agent-governance-toolkit)
+for production-grade runtime enforcement of AI agent behavior.
+
+---
+
+### L-002 — Outcome Verification
+
+**Scope**: DevSpark records compliance attempts, not whether implementations actually
+achieved their stated goals in production.
+
+**Rationale**: DevSpark verifies that the correct process was followed (spec present, plan
+complete, review done) and that artifacts are internally consistent. It cannot verify that
+the shipped feature works correctly in production — that is the domain of testing, monitoring,
+and observability tooling.
+
+**Complementary tooling**: Feature flagging systems, A/B testing platforms, production
+monitoring (Datadog, Grafana, etc.), and post-deployment validation runbooks.
+
+---
+
+### L-003 — Cross-Session Workflow Sequences
+
+**Scope**: DevSpark validates individual PR compliance, not sequences of PRs or whether
+a multi-PR epic was delivered in the correct order.
+
+**Rationale**: Each `/devspark.pr-review` run is stateless — it evaluates the PR in
+isolation against the constitution and the current spec lifecycle. Tracking whether PR #3
+should not have merged before PR #1 was complete requires project-management tooling,
+not a development-process governance framework.
+
+**Complementary tooling**: GitHub Projects, Linear, Jira, or similar project tracking
+tools for epic-level sequencing and dependency management.
+
+---
+
+### L-004 — Technical Enforcement
+
+**Scope**: DevSpark's quality gates are advisory (AI-evaluated), not technically enforced.
+A contributor can merge a PR without running any DevSpark command.
+
+**Rationale**: DevSpark is designed to work with any AI coding assistant and any team
+culture. Mandatory CI gates would require framework-specific CI configuration and would
+conflict with §I Backward Compatibility for repositories that already have CI pipelines.
+Enforcement relies on team culture, optional CI hooks, and the positive incentive
+created by trust-tiered review depth.
+
+**Complementary tooling**: GitHub branch protection rules, required status checks, and
+optional DevSpark CI hooks (documented in `quickstart/`) for teams that want harder gates.
+
+---
+
+### L-005 — AI Context Provenance
+
+**Scope**: DevSpark reviews artifacts (specs, code, PRs) but does not audit what context
+an AI agent used when generating those artifacts.
+
+**Rationale**: There is no reliable mechanism to reconstruct the full context window an
+AI agent operated in when producing a given artifact. DevSpark can evaluate the output
+(is the spec complete? does the code comply with the constitution?) but cannot detect
+whether the agent was given misleading context, outdated documentation, or prompt-injected
+instructions during generation.
+
+**Complementary tooling**: Prompt audit logging (where supported by the AI platform),
+code review for AI-generated artifacts, and red-teaming practices.
+
+---
+
+### L-006 — Direct Constitution Edit Bypass
+
+**Scope**: DevSpark's severity registry and this limitations document are not automatically
+updated when `constitution.md` is amended by a direct file edit.
+
+**Rationale**: The `/devspark.evolve-constitution` workflow enforces registry and
+limitations updates via Review Checklist items (FR-009, FR-006). However, a contributor
+who edits `constitution.md` directly (without using that command) bypasses those checklist
+gates entirely. DevSpark cannot detect this bypass automatically — it would require
+comparing file modification timestamps and commit history on every run, which violates
+§V Simplicity.
+
+**Mitigation**: `severity-registry.md` carries an inline maintenance note reminding
+direct-edit authors to update companion documents in the same PR. This is a process
+control, not a technical gate.
+
+**Complementary tooling**: Git pre-commit hooks or CI checks that detect modifications to
+`constitution.md` and emit a warning to also check `severity-registry.md` and
+`known-limitations.md`.

.documentation/memory/prompt-conformance-manifest.md

@@ -0,0 +1,171 @@
+---
+document: prompt-conformance-manifest
+version: "1.0.0"
+created: "2026-06-03"
+scope: templates/commands/
+---
+
+# Prompt Conformance Manifest
+
+This manifest defines the required governance elements that every command template in
+`templates/commands/` must contain. It is evaluated by an AI agent via `/devspark.checklist`
+— no new scripts or tool dependencies required.
+
+> **Contributor obligation**: Run `/devspark.checklist` against this manifest before any
+> PR that modifies files in `templates/commands/`. This is the re-run trigger for the
+> conformance baseline.
+
+## Required Elements — All Command Templates
+
+For each file in `templates/commands/`, verify the following three elements:
+
+### Element 1 — Constitution Authority Block
+
+**Check**: The file contains a block referencing `constitution.md` as non-negotiable authority.
+
+**Deterministic anchor**: The file MUST contain the string `constitution.md` AND the word
+`non-negotiable` within 15 lines of each other.
+
+**Finding if missing**:
+
+```yaml
+finding_id: conformance-{command-name}-01
+severity: high
+description: "Command template is missing a Constitution Authority block. The template
+  does not reference constitution.md as non-negotiable within 15 lines. This allows
+  implementations to drift from constitution principles without a documented gate."
+recommended_action: "Add a '## Constitution Authority' section (or equivalent functional
+  block) that references constitution.md as non-negotiable for this command's scope."
+execution_mode: manual
+status: open
+outcome: ""
+```
+
+**Constitution reference**: `§IV.SHOWSTOPPER` (Governance Authority — all commands must
+enforce constitution non-negotiability).
+
+---
+
+### Element 2 — Frontmatter Handoffs Block
+
+**Check**: The YAML frontmatter block contains the key `handoffs:`.
+
+**Deterministic anchor**: The file's YAML frontmatter (between the opening `---` and
+closing `---`) MUST contain the key `handoffs:`.
+
+**Finding if missing**:
+
+```yaml
+finding_id: conformance-{command-name}-02
+severity: medium
+description: "Command template frontmatter is missing the 'handoffs:' key. Without
+  handoff declarations, downstream workflow routing is undefined and agents cannot
+  surface next-step options to users."
+recommended_action: "Add a 'handoffs:' block to the YAML frontmatter with at least
+  one downstream agent label and prompt."
+execution_mode: manual
+status: open
+outcome: ""
+```
+
+---
+
+### Element 3 — Artifact Output Statement
+
+**Check**: The file describes at least one artifact it produces or writes.
+
+**Deterministic anchor**: The file MUST contain at least one of the following phrases
+in a section describing what the command produces: `Write`, `Save`, `Create`, `Generate`,
+`Output`. The phrase must appear in a context describing a command output (not just as
+a verb in a general description).
+
+**Finding if missing**:
+
+```yaml
+finding_id: conformance-{command-name}-03
+severity: medium
+description: "Command template does not contain a clear artifact output statement.
+  Users and downstream tools cannot determine what artifact this command produces
+  or where it is saved."
+recommended_action: "Add an explicit statement describing the artifact this command
+  creates or updates, including the file path where it is written."
+execution_mode: manual
+status: open
+outcome: ""
+```
+
+---
+
+## Default Behavior for Unlisted Templates
+
+Any file in `templates/commands/` not explicitly mentioned in the Known Variant Headings
+section below is evaluated against all three universal required elements above.
+
+Findings for unlisted templates use the same `finding_id` pattern:
+`conformance-{command-name}-{01|02|03}`
+
+Failures for unlisted templates are flagged as **LOW** severity unless the missing element
+is Element 1 (Constitution Authority), which is always **HIGH** regardless of whether the
+template is listed or not.
+
+---
+
+## Known Variant Headings
+
+The following commands use non-standard headings or structures for constitution authority
+content. They are pre-documented to prevent false positives.
+
+### `evolve-constitution.md`
+
+**Variant**: Uses `## Lifecycle Position` instead of `## Constitution Authority`.
+
+**Qualifying text present**: The section contains the phrase `constitution.md` and
+references it as non-negotiable authority within the Lifecycle Position block.
+
+**Status**: Acceptable — passes Element 1 check.
+
+---
+
+### `specify.md`
+
+**Variant**: Has `## Constitution Authority` heading but uses "MUST align" rather than
+"non-negotiable" as the authority phrase; references `constitution.md` in the section.
+
+**Qualifying text present**: `## Constitution Authority` heading present; "MUST align with
+mandated principles" is functionally equivalent to non-negotiable enforcement.
+
+**Status**: Acceptable — passes Element 1 check via heading + constitution.md reference.
+
+---
+
+## Conformance Check Procedure
+
+When invoked via `/devspark.checklist`:
+
+1. List all files in `templates/commands/`
+2. For each file, evaluate the three required elements using the deterministic anchors above
+3. Check Known Variant Headings before flagging Element 1 failures
+4. For any missing element, emit a finding using the Shared Review Resolution Contract schema
+   (as defined in each element's "Finding if missing" block above)
+5. Manually verify 3 known-good templates (`specify.md`, `plan.md`, `pr-review.md`) pass
+   all three checks as a sanity test before accepting any full baseline
+
+**Pass**: All three elements present in all templates → no findings emitted.
+
+**Fail**: One finding per missing element per template.
+
+---
+
+## Baseline Results
+
+*To be populated after T013 baseline run. Document pass/fail results per template here.*
+
+<!-- BASELINE: Run 2026-06-03 against specify.md, plan.md, pr-review.md (sanity check).
+Sanity results:
+- plan.md: PASS (all 3 elements present; constitution.md + non-negotiable on same line)
+- pr-review.md: PASS (all 3 elements present; non-negotiable in Guidelines/Constitution Authority section)
+- specify.md: VARIANT — Element 1 uses "MUST align" with constitution.md rather than "non-negotiable";
+  has ## Constitution Authority heading. Adding to Known Variant Headings below.
+Full baseline across all templates/commands/ files: pending /devspark.checklist run.
+Re-run before any PR that modifies files in templates/commands/.
+-->

.documentation/memory/severity-registry.md

@@ -0,0 +1,62 @@
+---
+document: severity-registry
+constitution_version: "1.4.0"
+last_updated: "2026-06-03"
+authoritative_source: .documentation/memory/constitution.md
+---
+
+# DevSpark Severity Registry
+
+This document is the authoritative mapping from constitution sections to severity levels
+and finding codes used by `/devspark.pr-review` and other governance commands.
+
+## Purpose
+
+Every finding emitted by a DevSpark governance command that references a constitution
+principle MUST use a finding code from this registry in the format `§{section}.{LEVEL}`.
+This makes findings machine-trackable, audit-ready, and consistent across amendment cycles.
+
+## Maintenance Note
+
+> **IMPORTANT**: If `constitution.md` is amended directly without using
+> `/devspark.evolve-constitution`, the author MUST manually verify and update this
+> registry in the same PR. The `/devspark.evolve-constitution` workflow enforces this
+> via a Review Checklist item (FR-009), but direct edits bypass that gate.
+
+## Severity Levels
+
+| Level | Description | Effect on PR |
+|---|---|---|
+| `SHOWSTOPPER` | Violates a NON-NEGOTIABLE principle — blocks merge | Hard block |
+| `HIGH` | Violates a MUST requirement significantly | Should block merge |
+| `MEDIUM` | Partial compliance or process finding | Should be addressed before merge |
+| `LOW` | Minor improvement opportunity | Advisory only |
+
+## Registry Entries
+
+| Section | Principle | Severity | Finding Code | Trigger | Remediation Example |
+|---|---|---|---|---|---|
+| §I | Backward Compatibility | SHOWSTOPPER | `§I.SHOWSTOPPER` | Existing single-app repo forced to restructure or change behavior without opt-in | Revert breaking change; make new capability additive and opt-in only |
+| §II | Explicit Over Implied | SHOWSTOPPER | `§II.SHOWSTOPPER` | Scope, review scope, or governance scope inferred from working directory, branch name, or heuristic detection rather than declared explicitly | Add explicit scope declaration; replace heuristic with required argument |
+| §III | Ownership Boundary | SHOWSTOPPER | `§III.SHOWSTOPPER` | Install or upgrade flow adds, removes, or modifies files under any `.documentation/` directory | Move all install/upgrade writes to `.devspark/`; never touch `.documentation/` in framework operations |
+| §IV | Governance Authority | SHOWSTOPPER | `§IV.SHOWSTOPPER` | Application-level governance weakens a mandatory repo-wide rule from `constitution.md` | Restore the stricter repo-wide rule; app-level governance may only extend or strengthen |
+| §VI | Platform Parity | HIGH | `§VI.HIGH` | A script in `scripts/bash/` is updated without a matching update in `scripts/powershell/`, or vice versa; or install/upgrade delivers only one script set | Add the corresponding script in the other language in the same commit |
+| §VII | PR Review Artifact Commit Discipline | MEDIUM | `§VII.MEDIUM` | The PR review file (`.documentation/specs/pr-review/pr-NNN.md`) is committed in the same commit as production code, tests, or other docs | Split into two commits: one for the review file only, one for all other changes |
+| §VIII | Markdown Quality (CI block) | HIGH | `§VIII.HIGH` | A markdown file with markdownlint errors is merged to the default branch, blocking the CI lint job | Fix all markdownlint errors before merging; run `npx markdownlint-cli2 "**/*.md"` locally first |
+| §VIII | Markdown Quality (pre-push) | MEDIUM | `§VIII.MEDIUM` | Markdownlint errors caught locally before push (not yet blocking CI) | Fix errors before pushing; use editor markdownlint integration for real-time feedback |
+
+## Finding Code Format
+
+```text
+§{roman-numeral-section}.{SEVERITY}
+```
+
+**Examples**: `§VI.HIGH`, `§VII.MEDIUM`, `§VIII.HIGH`, `§I.SHOWSTOPPER`
+
+**For findings not mapped to any constitution section**: emit the finding without a `§`
+code and flag it as a `CON` candidate for `/devspark.evolve-constitution`.
+
+## Companion Documents
+
+- [Known Governance Limitations](known-limitations.md)
+- [Constitution](constitution.md)