diff --git a/.documentation/memory/constitution.md b/.documentation/memory/constitution.md index d0329cc0..dd0f5d0f 100644 --- a/.documentation/memory/constitution.md +++ b/.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 diff --git a/.documentation/memory/known-limitations.md b/.documentation/memory/known-limitations.md new file mode 100644 index 00000000..76eebdf6 --- /dev/null +++ b/.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`. diff --git a/.documentation/memory/prompt-conformance-manifest.md b/.documentation/memory/prompt-conformance-manifest.md new file mode 100644 index 00000000..1966e9ff --- /dev/null +++ b/.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.* + + diff --git a/.documentation/memory/severity-registry.md b/.documentation/memory/severity-registry.md new file mode 100644 index 00000000..841b510a --- /dev/null +++ b/.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) diff --git a/.documentation/specs/001-agt-governance-improvements/checklists/requirements.md b/.documentation/specs/001-agt-governance-improvements/checklists/requirements.md new file mode 100644 index 00000000..ed01941c --- /dev/null +++ b/.documentation/specs/001-agt-governance-improvements/checklists/requirements.md @@ -0,0 +1,49 @@ +# Specification Quality Checklist: AGT-Inspired Governance Improvements + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-06-03 +**Feature**: [spec.md](../spec.md) + +## Shared Validation Contract Checks + +- [x] Frontmatter present with all required keys (classification, risk_level, target_workflow, required_artifacts, recommended_next_step, required_gates, participants) +- [x] `classification`, `target_workflow`, and `required_artifacts` are consistent (`full-spec` / `specify-full` / `spec, plan, tasks`) +- [x] `required_gates` matches the full-spec route (`checklist, analyze, critic`) +- [x] Status line present and set to `Draft` +- [x] Required headings present in canonical order: Rationale Summary → User Scenarios & Testing → Requirements → Success Criteria +- [x] Each required heading appears exactly once + +## Content Quality + +- [x] Frontmatter matches the shared validation contract +- [x] Required headings for full-spec route are present in canonical order +- [x] Status line uses a valid lifecycle state (`Draft`) +- [x] No implementation details (languages, frameworks, APIs) +- [x] Focused on user value and governance outcomes +- [x] Written at a level accessible to non-technical stakeholders +- [x] All mandatory sections completed + +## Requirement Completeness + +- [x] No `[NEEDS CLARIFICATION]` markers remain +- [x] Requirements are testable and unambiguous +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic +- [x] All acceptance scenarios are defined (4 user stories, each with 2-3 scenarios) +- [x] Edge cases are identified (4 edge cases documented) +- [x] Scope is clearly bounded (Out of Scope section present) +- [x] Dependencies and assumptions identified (Assumptions section present) + +## Feature Readiness + +- [x] All functional requirements (FR-001 through FR-009) have clear acceptance criteria +- [x] User scenarios cover primary flows (severity registry, trust tiers, limitations doc, prompt lint) +- [x] Feature meets measurable outcomes defined in Success Criteria (SC-001 through SC-006) +- [x] No implementation details leak into specification + +## Notes + +- All items pass. No spec updates required before proceeding to `/devspark.plan`. +- The four improvements are additive — SC-005 explicitly verifies backward compatibility. +- Prompt conformance check is intentionally scoped to manual/checklist initially (see Assumptions). +- Trust tier uses ternary classification (full/partial/no) not numeric scoring — documented in Out of Scope. diff --git a/.documentation/specs/001-agt-governance-improvements/gates/analyze.md b/.documentation/specs/001-agt-governance-improvements/gates/analyze.md new file mode 100644 index 00000000..978187f2 --- /dev/null +++ b/.documentation/specs/001-agt-governance-improvements/gates/analyze.md @@ -0,0 +1,174 @@ +--- +gate: analyze +status: pass +blocking: false +severity: info +summary: "All 8 findings resolved 2026-06-03: FR-006 covered (T011 expanded), FR-004/SC-006/Edge-4 wording tightened in spec, T005 explicit reviewer reminder added, T010/T013 unlocked from hardcoded count, plan.md terminology normalized. Ready for /devspark.critic." +--- + +# Specification Analysis Report: AGT-Inspired Governance Improvements + +**Branch**: `001-agt-governance-improvements` | **Date**: 2026-06-03 +**Artifacts**: spec.md ✅ | plan.md ✅ | tasks.md ✅ | constitution.md ✅ + +## Findings Table + +| ID | Category | Severity | Location | Summary | Recommendation | +|----|----------|----------|----------|---------|----------------| +| A-E01 | Coverage Gap | HIGH | tasks.md / FR-006 | FR-006 ("evolve-constitution MUST check for new limitations") has zero task coverage. T011 updates `evolve-constitution.md` for FR-009 only; a second insertion for FR-006 is missing. | Expand T011 to cover both FR-009 (severity-registry co-update) and FR-006 (known-limitations check) in the same `evolve-constitution.md` edit, or add a T011b task. | +| A-B01 | Ambiguity | MEDIUM | spec.md / FR-004 | "elevated scrutiny pass" implies additional review dimensions; plan narrows this to emitting a single MEDIUM finding. Gap between spec intent and plan definition. | Either update FR-004 to explicitly say "emits a MEDIUM finding" or update plan/T005 to also add one additional explicit scrutiny dimension (e.g., scanning for missing error-handling in the diff). | +| A-B02 | Ambiguity | MEDIUM | spec.md / SC-006 | "kept in sync across at least two constitution amendment cycles without manual reminder" is untestable at PR merge time — it's a future-state criterion. | Reword SC-006 to a merge-time verifiable criterion: "The severity-registry co-update checklist item is present in `evolve-constitution.md` and is exercised in the next amendment PR." | +| A-C01 | Underspecification | MEDIUM | spec.md / Edge Case 4 | Edge case "conformance check should flag unknown commands as requiring a rule definition" has no corresponding task or manifest design element. | Add a note to the conformance manifest (T010) defining behavior for template files not listed in the manifest (default: treat as unchecked, flag as LOW finding). | +| A-F01 | Inconsistency | LOW | tasks.md / T013 | T013 hardcodes "28 files" — a count that will be stale if commands are added or removed before the task runs. | Change T013 wording to "all files in `templates/commands/`" (no hardcoded count). | +| A-F02 | Inconsistency | LOW | plan.md | "conformance manifest" and "checklist manifest" used interchangeably in one sentence in Phase 1 design. | Normalize to "conformance manifest" throughout plan.md. | +| A-C02 | Underspecification | LOW | spec.md / FR-009 | FR-009 uses "enforced" but the mechanism is a manual checklist item, not technical enforcement. Overstates the guarantee. | Reword to "required as a checklist item in the `evolve-constitution` workflow" — matches actual mechanism and §V Simplicity. | +| A-F03 | Inconsistency | LOW | spec.md / Architectural Impact | Spec's Architectural Impact lists 4 files but the final design includes 5 (adds `evolve-constitution.md` update). Spec section was written before the evolve-constitution update was confirmed. | Update spec Architectural Impact to list all 5 files (3 new + 2 updated). | + +## Coverage Summary Table + +| Requirement Key | Has Task? | Task ID(s) | Notes | +|---|---|---|---| +| FR-001 severity-registry-format | ✅ | T002 | | +| FR-002 pr-review-structured-yaml-findings | ✅ | T003 | | +| FR-003 pr-review-trust-tier-detection | ✅ | T005 | | +| FR-004 pr-review-depth-adjustment | ✅ | T005 | Ambiguity: "elevated scrutiny" vs single MEDIUM finding — see A-B01 | +| FR-005 known-limitations-file | ✅ | T007 | | +| FR-006 evolve-constitution-limitations-check | ❌ | — | **GAP** — requires T011 expansion | +| FR-007 conformance-manifest-three-sections | ✅ | T010 | | +| FR-008 conformance-findings-severity-codes | ✅ | T010, T013 | | +| FR-009 severity-registry-co-update-enforced | ✅ | T011 | | +| SC-001 every-finding-has-severity-code | ✅ | T003 | | +| SC-002 no-spec-branch-gets-medium-finding | ✅ | T005 | | +| SC-003 known-limitations-four-on-day-one | ✅ | T007 | | +| SC-004 conformance-catches-missing-authority | ✅ | T010, T013 | | +| SC-005 all-changes-additive | ✅ | T016 | | +| SC-006 registry-constitution-sync | ⚠️ | T011 | Partial — checklist item added but "without manual reminder" is future-state only | + +## Constitution Alignment + +No violations found. + +| Principle | Status | +|---|---| +| §I Backward Compatibility (NON-NEGOTIABLE) | ✅ Pass | +| §II Explicit Over Implied (NON-NEGOTIABLE) | ✅ Pass | +| §III Ownership Boundary (NON-NEGOTIABLE) | ✅ Pass | +| §IV Governance Authority | ✅ Pass | +| §V Simplicity | ✅ Pass | +| §VI Platform Parity (MUST) | ✅ N/A — no new scripts | +| §VII PR Review Commit Discipline (MUST) | ✅ Pass — T016 explicitly verifies | +| §VIII Markdown Quality (MUST) | ✅ Pass — T004, T006, T009, T012, T014 all run markdownlint | + +## Unmapped Tasks + +| Task | Mapped Requirement | Notes | +|---|---|---| +| T001 | Setup | Infrastructure verification — no FR required | +| T004 | FR-001, FR-002 | Markdownlint validation for registry and pr-review | +| T006 | FR-003, FR-004 | Markdownlint validation for pr-review | +| T008 | FR-005 | Adds constitution reference to `known-limitations.md` | +| T009 | FR-005, §VIII | Markdownlint validation | +| T012 | FR-007, FR-008 | Markdownlint validation for manifest and evolve-constitution | +| T014 | §VIII | Full repo markdownlint sweep | +| T015 | Spec lifecycle | Spec status update to Complete | +| T016 | §VII | Commit isolation verification | + +All unmapped tasks are legitimate infrastructure, validation, or lifecycle tasks — not orphaned work. + +## Metrics + +- **Total Functional Requirements**: 9 +- **Total Success Criteria**: 6 +- **Total Tasks**: 16 +- **Requirement Coverage**: 8/9 (89%) — FR-006 uncovered +- **Success Criteria Coverage**: 5/6 fully verifiable at merge (SC-006 is future-state) +- **Critical Issues**: 0 +- **HIGH Issues**: 1 (FR-006 coverage gap) +- **MEDIUM Issues**: 3 +- **LOW Issues**: 4 +- **Constitution Violations**: 0 + +## Shared Review Resolution Contract + +```yaml +findings: + - finding_id: analyze-E01 + severity: high + description: "FR-006 requires evolve-constitution.md to check for new limitations implications during constitution amendments. T011 only adds the severity-registry co-update checklist item (FR-009). FR-006 has zero task coverage." + recommended_action: "Expand T011 in tasks.md to also add a limitations-check bullet to the evolve-constitution.md Review Checklist: 'Check whether the amendment implies new limitations for .documentation/memory/known-limitations.md and update in the same PR if so.'" + execution_mode: selective + status: resolved + outcome: "Applied 2026-06-03 per recommendations" + + - finding_id: analyze-B01 + severity: medium + description: "FR-004 says 'elevated scrutiny pass' but plan and T005 only define emitting a single MEDIUM finding. 'Elevated scrutiny' implies broader review dimensions not currently specified." + recommended_action: "Update FR-004 wording in spec.md to match plan: 'no-compliance branches MUST receive an elevated scrutiny pass, implemented as a MEDIUM trust-tier finding plus a reminder to the reviewer to apply heightened attention to all other findings.' Or expand T005 to include one additional explicit scrutiny action." + execution_mode: selective + status: resolved + outcome: "Applied 2026-06-03 per recommendations" + + - finding_id: analyze-B02 + severity: medium + description: "SC-006 ('kept in sync without manual reminder across two amendment cycles') is a future-state criterion that cannot be verified at PR merge time." + recommended_action: "Reword SC-006 in spec.md to a merge-time criterion: 'The severity-registry co-update checklist item is present in evolve-constitution.md and the next amendment PR demonstrates its use.'" + execution_mode: selective + status: resolved + outcome: "Applied 2026-06-03 per recommendations" + + - finding_id: analyze-C01 + severity: medium + description: "Edge Case 4 ('conformance check should flag unknown commands') has no corresponding task or manifest design. The manifest (T010) does not specify behavior for template files not covered by any manifest rule." + recommended_action: "Add a note to T010's description: also define in the manifest that files in templates/commands/ not matching any listed command are flagged as LOW findings requiring a rule definition." + execution_mode: selective + status: resolved + outcome: "Applied 2026-06-03 per recommendations" + + - finding_id: analyze-F01 + severity: low + description: "T013 hardcodes '28 files' — stale if commands are added before the task runs." + recommended_action: "Edit T013 in tasks.md: replace '28 files' with 'all files in templates/commands/'." + execution_mode: auto + status: resolved + outcome: "Applied 2026-06-03 per recommendations" + + - finding_id: analyze-F02 + severity: low + description: "Plan.md uses 'checklist manifest' and 'conformance manifest' interchangeably in one sentence." + recommended_action: "Normalize to 'conformance manifest' throughout plan.md." + execution_mode: auto + status: resolved + outcome: "Applied 2026-06-03 per recommendations" + + - finding_id: analyze-C02 + severity: low + description: "FR-009 uses 'enforced' but the mechanism is a manual checklist item. Overstates the guarantee relative to §V Simplicity." + recommended_action: "Reword FR-009 in spec.md: replace 'enforced as a checklist item' with 'required as a checklist item'." + execution_mode: auto + status: resolved + outcome: "Applied 2026-06-03 per recommendations" + + - finding_id: analyze-F03 + severity: low + description: "Spec Architectural Impact lists 4 files but final design includes 5 (evolve-constitution.md update added after initial drafting)." + recommended_action: "Update spec.md Architectural Impact to list all 5 deliverables: 3 new files + pr-review.md update + evolve-constitution.md update." + execution_mode: auto + status: resolved + outcome: "Applied 2026-06-03 per recommendations" +``` + +## Next Actions + +**Gate status: WARN — not blocking, but HIGH finding should be resolved before implementation.** + +1. **Resolve analyze-E01 (HIGH)** before implementing T011: Expand T011 in `tasks.md` to cover both FR-009 and FR-006 in the same `evolve-constitution.md` edit. This is a one-line addition to the task description. + +2. **Consider analyze-B01 (MEDIUM)**: Decide whether "elevated scrutiny" means only the MEDIUM finding or also an additional review action. Recommended: add one sentence to T005 clarifying the reviewer is reminded to apply heightened attention to all other findings on no-compliance branches. + +3. **Consider analyze-B02 (MEDIUM)**: SC-006 can remain as-is if the team accepts it as a forward-looking goal rather than a merge-time gate. If it must be merge-time verifiable, update the wording. + +4. **Resolve analyze-C01 (MEDIUM)**: Add unknown-command behavior to T010's description before implementing the conformance manifest. + +5. **LOW findings (analyze-F01, F02, C02, F03)**: Safe to fix during implementation as encountered — no blocking risk. + +**Suggested next command**: `/devspark.critic` (the second pre-implement gate — evaluates NFR achievability, missing operational tasks, and failure modes). diff --git a/.documentation/specs/001-agt-governance-improvements/gates/critic.md b/.documentation/specs/001-agt-governance-improvements/gates/critic.md new file mode 100644 index 00000000..e2b3580e --- /dev/null +++ b/.documentation/specs/001-agt-governance-improvements/gates/critic.md @@ -0,0 +1,249 @@ +--- +gate: critic +status: pass +blocking: false +severity: info +summary: "All 6 findings resolved 2026-06-03. Frontmatter added (critic-001), string-match anchors added to T010/plan (critic-002), T003/T005 anchor text and verification added (critic-003), L-006 + registry self-note + edge case added (critic-004), re-run obligation documented in T013/Notes (critic-005), T008 precise insertion point specified (critic-006). VERDICT: PROCEED." +--- + +# Technical Risk Assessment: AGT-Inspired Governance Improvements + +**Analysis Date:** 2026-06-03 +**Scope:** FULL (spec.md + plan.md + tasks.md) +**Detected Archetype:** `documentation-site` (pure Markdown governance toolkit; no runtime code, no framework, no storage) +**Detected Stack:** Markdown + YAML — no language runtime +**Context Mode:** `brownfield` (modifying existing command templates and adding companion documents to an established repository) +**Risk Profile:** `internal` (developer tooling; defaulted — no `risk_profile` in spec frontmatter) +**Risk Posture:** YELLOW + +*No stack/archetype checklists found at `.devspark/risk-checklists/` — risks derived from first principles using the universal failure-mode lens.* + +--- + +## Executive Summary + +This feature delivers pure Markdown and YAML governance artifacts with no runtime code, no new tool dependencies, and no database or network surfaces — the production risk profile is inherently low. The primary risks are process-level: semantic evaluation of command templates depends entirely on AI agent judgment (no deterministic enforcement), brownfield edits to the critical `pr-review.md` template could silently break existing review flows if not applied carefully, and the spec's `internal` risk profile was inferred rather than declared. No showstoppers or critical findings. Proceed with implementation after noting the four HIGH findings. + +--- + +## Findings (source of truth) + +```yaml +findings: + - finding_id: critic-001 + category: missing-risk-profile + archetype_applicable: true + location: spec.md#frontmatter + description: > + spec.md has no `risk_profile`, `archetype`, or `change_type` frontmatter fields. + Defaulted to internal/documentation-site/brownfield per backward-compat rules. + If this feature ships to other repos via DevSpark CLI, the risk profile may be + customer-facing or higher — the absence of metadata makes this invisible to future + critic runs. + base_severity: high + effective_severity: high + recommended_action: > + Add `risk_profile: internal`, `archetype: documentation-site`, and + `change_type: brownfield` to spec.md YAML frontmatter before closing the PR. + execution_mode: auto + status: resolved + outcome: "Applied 2026-06-03 per recommendations" + + - finding_id: critic-002 + category: trust_boundaries + archetype_applicable: true + location: plan.md#Phase1-Design-Contracts / tasks.md#T013 + description: > + The prompt conformance check relies entirely on AI agent semantic judgment to + determine whether a command template contains a "Constitution Authority block." + There is no deterministic definition of what constitutes a passing evaluation. + Two different AI agents (or the same agent on two different days) could reach + opposite conclusions for the same template — particularly for edge cases like + evolve-constitution.md's "## Lifecycle Position" variant. This means the + conformance check cannot be meaningfully enforced in CI or audited. + base_severity: high + effective_severity: high + recommended_action: > + Add a concrete, testable definition to the conformance manifest for what + constitutes a passing Constitution Authority check: e.g., "the template file + MUST contain the exact string `constitution.md` and the word `non-negotiable` + within 10 lines of each other." Document the evolve-constitution.md exemption + explicitly with the qualifying text that passes. This makes the check reproducible + across agent runs without requiring exact heading matches. + execution_mode: selective + status: resolved + outcome: "Applied 2026-06-03 per recommendations" + + - finding_id: critic-003 + category: error_handling_resilience + archetype_applicable: true + location: tasks.md#T003 / tasks.md#T005 + description: > + Both T003 and T005 make additive edits to `templates/commands/pr-review.md` — + one of the most critical and complex command templates in DevSpark (835 lines). + The tasks specify WHAT to insert but not WHERE precisely within the file's + existing structure. An implementer who misreads the insertion point could + accidentally nest new content inside an existing markdown code block, break + heading hierarchy, or duplicate existing severity guidance. There is no + rollback procedure specified if the edit corrupts the template. + base_severity: high + effective_severity: high + recommended_action: > + Expand T003 and T005 in tasks.md to specify exact anchor text for each insertion: + for T003, "insert after the line '**CON**: Constitution needs updating...'" ; + for T005, "insert after the line '### 1. Initialize Review Context' closing + paragraph, before the line '### 2. Load Constitution'." Also add a verification + step: after each edit, confirm the file still passes markdownlint and that the + heading count for '###' sections has increased by exactly the expected amount. + execution_mode: selective + status: resolved + outcome: "Applied 2026-06-03 per recommendations" + + - finding_id: critic-004 + category: documentation + archetype_applicable: true + location: spec.md#Out-of-Scope / plan.md#Interface-Contracts + description: > + The severity registry is explicitly designed as a companion document that must + stay in sync with constitution.md across amendment cycles. However, there is no + documented procedure for what happens when the constitution is amended by someone + who does NOT run /devspark.evolve-constitution (e.g., a direct edit to + constitution.md). The checklist item in evolve-constitution.md only fires when + that command is used. A direct constitution edit bypasses the gate entirely, + leaving the registry silently stale. + base_severity: high + effective_severity: high + recommended_action: > + Add a note to the severity-registry.md document itself (T002) stating: + "If constitution.md is amended without using /devspark.evolve-constitution, + the author MUST manually verify and update this registry in the same PR." + Also add this as an explicit edge case in the spec's Edge Cases section + and as a limitation entry in known-limitations.md (L-006). + execution_mode: selective + status: resolved + outcome: "Applied 2026-06-03 per recommendations" + + - finding_id: critic-005 + category: testing_strategy + archetype_applicable: true + location: tasks.md#T013 + description: > + T013 performs a one-time baseline conformance check and documents results + as a comment in the manifest file. This is a snapshot test, not a repeatable + test. If command templates are edited after this baseline is taken, there is + no automated or semi-automated mechanism to re-run the check and detect + regressions. The conformance check is only as good as the last time someone + thought to run it. + base_severity: medium + effective_severity: medium + recommended_action: > + Add a note in the conformance manifest (T010) and in the README or + CONTRIBUTING.md explaining that /devspark.checklist against + prompt-conformance-manifest.md should be run before any PR that modifies + files in templates/commands/. This is a process gate, not automation, + but it should be documented as a contributor obligation. + execution_mode: selective + status: resolved + outcome: "Applied 2026-06-03 per recommendations" + + - finding_id: critic-006 + category: documentation + archetype_applicable: true + location: tasks.md#T008 + description: > + T008 adds a reference to known-limitations.md in constitution.md by + appending a "See Also" line "at the bottom of the constitution." The + constitution v1.4.0 ends with governance metadata (version, ratified date, + last amended date). Appending after this metadata is fine, but the task + does not specify whether the reference goes before or after the version + line — an implementer could accidentally place it in a position that breaks + the constitution's formatting or appears below the closing metadata in a way + that looks orphaned. + base_severity: medium + effective_severity: medium + recommended_action: > + Expand T008 to specify the exact insertion point: "Add a '## Companion + Documents' section immediately before the '**Version**:' metadata line at + the bottom of constitution.md, containing a bullet: '- [Known Governance + Limitations](.documentation/memory/known-limitations.md)'" + execution_mode: auto + status: resolved + outcome: "Applied 2026-06-03 per recommendations" +``` + +--- + +## High + +| ID | Category | Location | Issue | Impact | Suggestion | +|----|----------|----------|-------|--------|------------| +| critic-001 | missing-risk-profile | spec.md#frontmatter | No `risk_profile`, `archetype`, or `change_type` frontmatter — defaults used silently | Future critic runs on this feature branch will re-default, making metadata drift invisible | Add three frontmatter fields to spec.md before PR close | +| critic-002 | trust_boundaries | plan.md / T013 | Conformance check is purely AI-semantic with no deterministic pass/fail definition | Two runs could disagree on the same template; check cannot be CI-enforced or audited | Add testable string-match criteria to the conformance manifest alongside semantic evaluation | +| critic-003 | error_handling_resilience | T003, T005 | Insertion point for pr-review.md edits underspecified — 835-line file with complex structure | Mis-placed insertion could silently corrupt template structure or duplicate existing guidance | Expand T003/T005 with exact anchor text and post-edit heading-count verification | +| critic-004 | documentation | spec.md / plan.md | No procedure for direct constitution.md edits bypassing evolve-constitution — registry becomes silently stale | Constitution and registry drift undetected until next pr-review surfaces inconsistency | Add self-referential note in severity-registry.md + edge case + L-006 in known-limitations | + +--- + +## Missing Critical Tasks + +No missing operational tasks for a `documentation-site` archetype with no runtime code. The applicable universal failure-mode lens items (resource leaks, race conditions, unbounded growth, timeouts) do not apply to static Markdown files. + +Process-level operational gap noted but not a missing task: + +- **Re-run trigger for conformance check**: No contributor workflow specifies when to re-run `/devspark.checklist` against the conformance manifest. Addressed via critic-005 recommendation (documentation, not a new task). + +--- + +## Questionable Assumptions + +1. **"The AI agent performing conformance checks will be consistent across runs"** → Failure mode: Two different implementers (or the same implementer with different context) get contradictory pass/fail results for `evolve-constitution.md`. The known-variant-headings section of the manifest mitigates this but does not eliminate it for future edge cases. Mitigation: add string-match anchors per critic-002. + +2. **"pr-review.md insertions are purely additive and cannot break existing behavior"** → Failure mode: The trust-tier step (T005) inserts a new numbered step between existing steps 1 and 2. If the existing step numbering is referenced by other commands or documentation via text anchors, the renaming (step 2 becomes step 2b or steps shift) could create dead cross-references. Mitigation: search for cross-references to "step 1" / "step 2" in pr-review.md before inserting. + +3. **"The severity registry will be consulted by AI agents automatically"** → Failure mode: Nothing in the updated pr-review.md instructs the reviewing AI to *load* the severity registry before emitting findings. The template tells it to emit `§{section}.{LEVEL}` codes but doesn't say to verify those codes against the registry. The registry is useful for humans but invisible to the agent unless explicitly referenced in the command. Mitigation: T003 should explicitly instruct the pr-review template to load `.documentation/memory/severity-registry.md` as part of step 2 (Load Constitution). + +--- + +## Dependency Risk Assessment + +| Dependency | Concern | Alternative | +|---|---|---| +| `npx markdownlint-cli2` (T004, T006, T009, T012, T014) | Requires Node.js and internet access to run `npx`; may fail in air-gapped or Node-less environments | Use locally installed `markdownlint-cli2` binary; document in CONTRIBUTING.md | +| `/devspark.checklist` command (T013) | Command must be available and working at time T013 runs; if checklist command has a bug, baseline is invalid | Run checklist against at least 2–3 known-good templates manually as a sanity check before accepting baseline | +| AI agent consistency for conformance evaluation (T013) | Results depend on agent model version and context — not reproducible in the strict sense | Add string-match anchors per critic-002 to make the evaluation deterministic | + +--- + +## Estimated Technical Debt at Launch + +- **Documentation debt**: LOW — the spec, plan, and tasks are thorough. The main gap is the undocumented "re-run conformance check before template PRs" contributor obligation (critic-005). +- **Process debt**: MEDIUM — the direct-constitution-edit bypass (critic-004) is a known gap that requires a future process improvement or CAP to close formally. +- **Testing debt**: LOW — markdownlint provides automated validation for all new files. Conformance check is manual but documented. +- **Code debt**: N/A — no code produced. + +--- + +## Metrics + +- **Showstoppers**: 0 +- **Critical**: 0 +- **High**: 4 (critic-001, critic-002, critic-003, critic-004) +- **Medium**: 2 (critic-005, critic-006) +- **Low**: 0 +- **Missing operational tasks**: 0 +- **Questionable assumptions**: 3 + +**VERDICT:** CONDITIONAL + +**Required Actions Before Implementation:** + +1. **critic-001** (auto): Add `risk_profile: internal`, `archetype: documentation-site`, `change_type: brownfield` to spec.md frontmatter. +2. **critic-003** (selective): Expand T003 and T005 in tasks.md with exact anchor text and post-edit verification step for pr-review.md insertions. +3. **critic-002** (selective): Decide whether to add deterministic string-match criteria to the conformance manifest definition (T010) alongside semantic evaluation. Recommended but not blocking if team accepts the ambiguity. +4. **critic-004** (selective): Add direct-edit bypass note to T002 (severity-registry.md content) and as L-006 in known-limitations.md. Low implementation cost. + +**Recommended Risk Mitigations:** + +- Add a note to T003 that the updated pr-review.md template should explicitly instruct the reviewing agent to load `.documentation/memory/severity-registry.md` during step 2 — otherwise the registry is useful for humans but invisible to the AI agent at review time. +- Search for "step 1" / "step 2" cross-references in pr-review.md before executing T005 insertions. +- Document in CONTRIBUTING.md that `/devspark.checklist` against `prompt-conformance-manifest.md` is a required pre-PR step when editing any file in `templates/commands/`. diff --git a/.documentation/specs/001-agt-governance-improvements/plan.md b/.documentation/specs/001-agt-governance-improvements/plan.md new file mode 100644 index 00000000..fb5c9cf3 --- /dev/null +++ b/.documentation/specs/001-agt-governance-improvements/plan.md @@ -0,0 +1,254 @@ +--- +participants: + owner: human + planner: ai + implementer: ai + reviewer: human + critic: ai + scribe: ai +--- + +# Implementation Plan: AGT-Inspired Governance Improvements + +**Branch**: `001-agt-governance-improvements` | **Date**: 2026-06-03 | **Spec**: [spec.md](spec.md) +**Input**: Feature specification from `.documentation/specs/001-agt-governance-improvements/spec.md` + +## Rationale Summary + +### Core Problem + +DevSpark's constitution and PR review workflow produce informal, inconsistent governance output: severity labels are scattered with no central registry, review depth is uniform regardless of spec-workflow compliance, the framework has no honest public statement of its limits, and command templates can drift from the constitution silently. + +### Decision Summary + +Four additive Markdown artifacts and one targeted command-template update deliver structured severity codes, trust-tiered review depth, explicit limitations documentation, and prompt conformance checking — all without new tool dependencies or constitution amendments. + +### Key Drivers + +- Severity registry makes findings machine-trackable and audit-ready across amendment cycles. +- Trust tiers create a self-reinforcing incentive for spec-driven development. +- Limitations document builds adopter trust through intellectual honesty. +- Conformance manifest prevents silent constitution drift in command templates. + +### Source Inputs + +- Spec: `.documentation/specs/001-agt-governance-improvements/spec.md` +- Research: `.documentation/specs/001-agt-governance-improvements/research.md` +- Constitution v1.4.0: `.documentation/memory/constitution.md` +- Microsoft AGT analysis (conversation context) + +### Tradeoffs Considered + +- Option A — New script pair for trust-tier detection: rejected (triggers §VI Platform Parity, adds maintenance burden for a simple file-presence check). +- Option B — Hard heading-string match in conformance check: rejected (`evolve-constitution.md` uses variant heading; would false-positive and break §I). +- Selected — Inline trust-tier detection in pr-review + semantic conformance check: minimal footprint, no §VI concern, fully backward-compatible. + +### Architectural Impact + +- 3 new files under `.documentation/memory/` (severity-registry, known-limitations, prompt-conformance-manifest). +- 1 command template updated (`templates/commands/pr-review.md`) — additive sections only. +- 1 command template updated (`templates/commands/evolve-constitution.md`) — adds two checklist items: severity-registry co-update (FR-009) and known-limitations check (FR-006). +- No changes to spec/plan/tasks templates. No new scripts. No new CI jobs. + +### Reviewer Guidance + +Verify: severity registry entries match constitution section markers exactly; trust-tier logic is file-presence only (no git history); limitations document is honest and does not overstate DevSpark's scope; conformance check uses semantic evaluation not string-matching. + +## Summary + +Deliver four governance artifacts (severity registry, known-limitations doc, conformance manifest, pr-review command update) that bring structured severity codes, trust-tiered review depth, explicit limitations, and prompt conformance to DevSpark's existing Markdown-and-conventions model — inspired by Microsoft AGT's governance philosophy, scoped to DevSpark's human-in-the-loop context. + +## Technical Context + +**Language/Version**: Markdown / YAML (no code language; pure documentation and template changes) +**Primary Dependencies**: DevSpark framework conventions; `npx markdownlint-cli2` (already required by §VIII) +**Storage**: `.documentation/memory/` (three new files); `templates/commands/` (two updated files) +**Testing**: Manual validation via `/devspark.checklist`; markdownlint CI (already enforced) +**Target Platform**: Any DevSpark-installed repository; source repo (`c:\GitHub\MarkHazleton\DevSpark`) +**Project Type**: Documentation / governance tooling +**Performance Goals**: N/A — static Markdown files +**Constraints**: No new tool dependencies (§V Simplicity); no `.devspark/` writes (§III); no script changes (avoids §VI parity requirement) +**Scale/Scope**: 5 files total (3 new, 2 updated); ~250–400 lines of Markdown + +## Constitution Check + +*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* + +| Principle | Status | Notes | +|---|---|---| +| §I Backward Compatibility (NON-NEGOTIABLE) | ✅ Pass | All changes additive; no existing file restructured | +| §II Explicit Over Implied (NON-NEGOTIABLE) | ✅ Pass | Severity codes, trust tiers, and conformance rules are explicit declarations | +| §III Ownership Boundary (NON-NEGOTIABLE) | ✅ Pass | New files in `.documentation/memory/` (repo-owned); no `.devspark/` writes | +| §IV Governance Authority | ✅ Pass | Registry is companion to constitution; constitution remains authoritative | +| §V Simplicity | ✅ Pass | No new tools, no new scripts, `/devspark.checklist` reused | +| §VI Platform Parity (MUST) | ✅ N/A | No new scripts in this plan | +| §VII PR Review Artifact Commit Discipline (MUST) | ✅ Pass | Enforced in tasks as commit isolation requirement | +| §VIII Markdown Quality (MUST) | ✅ Pass | All new `.md` files pass markdownlint before merge; tracked as explicit task | + +**Gate result: PASS — no violations, no waivers required.** + +## Project Structure + +### Documentation (this feature) + +```text +.documentation/specs/001-agt-governance-improvements/ +├── spec.md ✅ Complete +├── research.md ✅ Complete (Phase 0) +├── plan.md ✅ This file (Phase 1) +├── checklists/ +│ └── requirements.md ✅ Complete +└── tasks.md ⬜ Phase 2 (/devspark.tasks) +``` + +### New Governance Artifacts (repository root) + +```text +.documentation/memory/ +├── constitution.md (existing — unchanged) +├── severity-registry.md ⬜ NEW — P1 deliverable +├── known-limitations.md ⬜ NEW — P3 deliverable +└── prompt-conformance-manifest.md ⬜ NEW — P4 deliverable + +templates/commands/ +├── pr-review.md ⬜ UPDATED — trust-tier + severity code sections +└── evolve-constitution.md ⬜ UPDATED — severity-registry co-update checklist item +``` + +**Structure Decision**: All new files under `.documentation/memory/` per §III. Command template changes are in-place edits. + +## Complexity Tracking + +> No constitution violations requiring justification. + +--- + +## Phase 1: Design & Contracts + +### 1. Severity Registry Design + +**File**: `.documentation/memory/severity-registry.md` + +**YAML frontmatter fields**: + +```yaml +--- +document: severity-registry +constitution_version: "1.4.0" +last_updated: "2026-06-03" +authoritative_source: .documentation/memory/constitution.md +--- +``` + +**Table columns**: `section` | `principle` | `severity` | `trigger` | `finding_code` | `remediation` + +**Entries** (from research.md inventory of all constitution severity markers): + +| Section | Principle | Severity | Finding Code | +|---|---|---|---| +| §I | Backward Compatibility | SHOWSTOPPER | `§I.SHOWSTOPPER` | +| §II | Explicit Over Implied | SHOWSTOPPER | `§II.SHOWSTOPPER` | +| §III | Ownership Boundary | SHOWSTOPPER | `§III.SHOWSTOPPER` | +| §IV | Governance Authority | SHOWSTOPPER | `§IV.SHOWSTOPPER` | +| §VI | Platform Parity | HIGH | `§VI.HIGH` | +| §VII | PR Review Artifact Commit Discipline | MEDIUM | `§VII.MEDIUM` | +| §VIII | Markdown Quality (CI block) | HIGH | `§VIII.HIGH` | +| §VIII | Markdown Quality (pre-push) | MEDIUM | `§VIII.MEDIUM` | + +### 2. Known Limitations Document Design + +**File**: `.documentation/memory/known-limitations.md` + +**Entry structure per limitation**: + +```text +### L-NNN — [Limitation Name] +**Scope**: What DevSpark does NOT govern here +**Rationale**: Why this is structurally out of scope +**Complementary tooling**: What to use instead (if applicable) +``` + +**Six limitations to document on day one**: + +- L-001: Runtime agent behavior (use Microsoft AGT for production enforcement) +- L-002: Outcome verification (DevSpark records compliance attempts, not production outcomes) +- L-003: Cross-session workflow sequences (individual PR compliance only, not epic ordering) +- L-004: Technical enforcement (gates are advisory; enforcement relies on team culture + optional CI hooks) +- L-005: AI context provenance (DevSpark reviews artifacts, not what context the AI used to produce them) +- L-006: Direct-constitution-edit bypass (direct edits to `constitution.md` without `/devspark.evolve-constitution` leave severity registry and known-limitations silently stale; mitigation: severity-registry.md carries a maintenance note) + +### 3. Prompt Conformance Manifest Design + +**File**: `.documentation/memory/prompt-conformance-manifest.md` + +**Three required elements** evaluated with deterministic string-match anchors per command template: + +1. **Constitution authority block**: file contains the string `constitution.md` AND the word `non-negotiable` within 15 lines of each other — OR the file is listed in the Known Variant Headings section with its qualifying text documented +2. **Frontmatter `handoffs` key**: the YAML frontmatter block contains the key `handoffs:` +3. **Artifact output statement**: file contains at least one of the phrases `Write`, `Save`, `Create`, `Generate`, or `Output` within a section describing what the command produces + +These anchors make evaluation reproducible across different agent runs without requiring exact heading matches. + +**Known variant headings** (pre-documented to prevent false positives): + +- `evolve-constitution.md` uses `## Lifecycle Position` instead of `## Constitution Authority` — semantically equivalent + +**Finding ID pattern**: `conformance-{command-name}-{01|02|03}` + +### 4. PR Review Command Update Design + +**File**: `templates/commands/pr-review.md` — two additive insertions: + +**Insertion A — Trust-Tier Classification step** (new step 1b, between Initialize Review Context and Load Constitution): + +- Detect branch, derive spec dir, check 3 file presences (spec.md, plan.md, tasks.md) +- Classify: full-compliance / partial-compliance / no-compliance +- Emit MEDIUM finding for no-compliance using Shared Review Resolution Contract schema +- `finding_id`: `trust-tier-01`, `severity`: medium, `execution_mode`: manual + +**Insertion B — Severity Code Format guidance** (append to Severity Guidelines section after the line `| Constitution needs updating (not code) | CON | Governance improvement |`): + +- Mandate `§{section}.{LEVEL}` format for all constitution-linked findings +- Document examples: `§VI.HIGH`, `§VII.MEDIUM`, `§VIII.HIGH`, `§I.SHOWSTOPPER` +- Rule for non-constitution findings: no `§` code, flag as CON candidate + +**Insertion C — Registry load instruction** (add sub-bullet to step "### 2. Load Constitution"): + +- "Load `.documentation/memory/severity-registry.md` if it exists; use its entries to validate `§{section}.{LEVEL}` codes when emitting findings" — makes the registry visible to the AI agent performing the review, not just to human readers + +### 5. Evolve-Constitution Command Update Design + +**File**: `templates/commands/evolve-constitution.md` — two checklist items added to the Review Checklist in Step 5: + +```text +- [ ] If the amendment adds, removes, or modifies a severity marker, + `.documentation/memory/severity-registry.md` is updated in the same PR (FR-009) +- [ ] Check whether the amendment implies new governance limitations; if so, + update `.documentation/memory/known-limitations.md` in the same PR (FR-006) +``` + +--- + +## Interface Contracts + +### Severity Code Contract + +Format: `§{roman-numeral}.{SEVERITY}` where SEVERITY ∈ {SHOWSTOPPER, HIGH, MEDIUM, LOW} + +- Registry at `.documentation/memory/severity-registry.md` is the authoritative lookup. +- Commands that cannot map a finding to a registry entry MUST NOT invent a `§` code. +- Un-mapped findings are emitted without a `§` code and optionally flagged as CON candidates. + +### Trust Tier Contract + +- Computed fresh on each `/devspark.pr-review` run — not persisted. +- File-presence only — no git history analysis, no lifecycle state check. +- A Draft-status spec.md counts as present (existence matters, not lifecycle state). +- Not a gate — adjusts scrutiny and emits a finding; does not block the review. + +### Conformance Manifest Evaluation Contract + +- Evaluation is semantic — agent reads each template and determines governance content presence. +- `finding_id` pattern: `conformance-{command-name}-{N}` (e.g., `conformance-pr-review-01`) +- Pass = no findings. Fail = one finding per missing element per template. +- The manifest itself is not evaluated against itself. diff --git a/.documentation/specs/001-agt-governance-improvements/research.md b/.documentation/specs/001-agt-governance-improvements/research.md new file mode 100644 index 00000000..77a35d84 --- /dev/null +++ b/.documentation/specs/001-agt-governance-improvements/research.md @@ -0,0 +1,77 @@ +# Research: AGT-Inspired Governance Improvements + +**Branch**: `001-agt-governance-improvements` | **Date**: 2026-06-03 + +## Constitution Severity Inventory + +Scanning `constitution.md` v1.4.0 for all explicit severity markers: + +| Section | Marker | Severity | Trigger | +|---|---|---|---| +| §VI Platform Parity | "Violations are HIGH severity in PR review" | HIGH | Any script updated in one language without matching update in the other | +| §VII PR Review Artifact Commit Discipline | "Violations are MEDIUM severity process findings in PR review" | MEDIUM | Review file committed in same commit as production code | +| §VIII Markdown Quality | "Violations are HIGH severity in PR review when they block CI" | HIGH | Markdown file with lint errors merged to default branch | +| §VIII Markdown Quality | "MEDIUM when caught locally before push" | MEDIUM | Markdown lint error caught pre-push | +| §IV Governance Authority | "Constitution violations are showstopper severity in reviews" | SHOWSTOPPER | Any MUST/NON-NEGOTIABLE principle violated | +| §I Backward Compatibility | NON-NEGOTIABLE (implicit showstopper) | SHOWSTOPPER | Existing repo restructured without opt-in | +| §II Explicit Over Implied | NON-NEGOTIABLE (implicit showstopper) | SHOWSTOPPER | Scope inferred rather than declared | +| §III Ownership Boundary | NON-NEGOTIABLE (implicit showstopper) | SHOWSTOPPER | `.devspark/` or `.documentation/` written during install/upgrade | + +**Finding**: 3 NON-NEGOTIABLE sections carry implicit SHOWSTOPPER severity (§I, §II, §III) but have no explicit severity label in the text — they rely on §IV's "showstopper severity in reviews" statement. The registry must make this mapping explicit. + +## Command Template Audit — Required Section Presence + +Sampling 6 command templates to verify which sections are consistently present: + +| Template | `## Constitution Authority` | `handoffs` in frontmatter | Artifact output statement | +|---|---|---|---| +| `specify.md` | ✅ | ✅ | ✅ (SPEC_FILE write) | +| `plan.md` | ✅ | ✅ | ✅ (plan.md, research.md) | +| `pr-review.md` | ✅ ("Guidelines > Constitution Authority") | ✅ | ✅ (pr-NNN.md write) | +| `evolve-constitution.md` | ❌ (has "## Lifecycle Position" not "## Constitution Authority") | ✅ | ✅ (CAP-YYYY-NNN.md) | +| `quickfix.md` | ✅ | ✅ | ✅ | +| `checklist.md` | ✅ | ✅ | ✅ | + +**Finding**: `evolve-constitution.md` uses "## Lifecycle Position" rather than a "## Constitution Authority" section heading. The conformance manifest must accommodate this variant or require normalization. Decision: the manifest should check for *functional* constitution authority content (a block referencing the constitution as non-negotiable), not a hard heading string match — the agent performing the check can evaluate semantic presence. + +## Shared Review Resolution Contract — Current Adoption + +The contract schema (finding_id, severity, description, recommended_action, execution_mode, status, outcome) is already defined in: + +- `templates/commands/clarify.md` (Section: "Shared Review Resolution Contract Output") +- `templates/commands/pr-review.md` (Section: "Shared Review Resolution Contract Output") +- `templates/commands/analyze.md` (to verify — pattern is established) + +**Finding**: The schema is already cross-command standard. Updating pr-review to emit this for ALL findings (not just optionally) is a targeted tightening, not a new concept. + +## Trust Tier — Detection Logic Research + +Branch naming convention in use: `NNN-short-name` (verified from current branch `001-agt-governance-improvements`). + +Spec artifact paths follow: `.documentation/specs/{branch-name}/` + +Detection algorithm: + +1. Extract branch name from PR context (`head_branch`) +2. Derive spec dir: `.documentation/specs/{head_branch}/` +3. Check file existence: + - `spec.md` → exists? + - `plan.md` → exists? + - `tasks.md` → exists? +4. Classify: + - All 3 present → `full-compliance` + - `spec.md` only, or `spec.md` + `plan.md` → `partial-compliance` + - None present → `no-compliance` + - Branch name doesn't match `NNN-*` pattern → `no-compliance` (note naming gap) + +**Finding**: Detection is entirely file-system based — no git history analysis, no GitHub API calls beyond what the existing pr-context script already provides. Can be added as an inline step within the pr-review command without a new script. + +## Decisions + +| Decision | Rationale | Alternatives Considered | +|---|---|---| +| Registry as YAML frontmatter + Markdown table | Matches DevSpark conventions, human-readable, script-parseable, no new tooling | Pure YAML (less readable), pure prose (not parseable) | +| SHOWSTOPPER as 4th severity tier in registry | §I/II/III carry implicit showstopper severity per §IV — making it explicit prevents ambiguity | Map §I/II/III to HIGH (rejected: understates severity of NON-NEGOTIABLE violations) | +| Conformance manifest: semantic check, not heading-string match | `evolve-constitution.md` uses variant heading; string match would false-positive | Require heading normalization (rejected: breaks §I backward compatibility for installed repos) | +| Trust tier inline in pr-review (no new script) | No §VI parity concern, minimal footprint, fully reversible | New script pair (rejected: §VI would require Bash+PowerShell parity, adds maintenance burden for a simple file-presence check) | +| `known-limitations.md` co-located with constitution | Adopter reads constitution → naturally finds limitations beside it | In README (rejected: README gets stale; memory/ is authoritative) | diff --git a/.documentation/specs/001-agt-governance-improvements/spec.md b/.documentation/specs/001-agt-governance-improvements/spec.md new file mode 100644 index 00000000..3a9c5c9f --- /dev/null +++ b/.documentation/specs/001-agt-governance-improvements/spec.md @@ -0,0 +1,193 @@ +--- +classification: full-spec +risk_level: medium +risk_profile: internal +archetype: documentation-site +change_type: brownfield +target_workflow: specify-full +required_artifacts: spec, plan, tasks +recommended_next_step: plan +required_gates: checklist, analyze, critic +participants: + owner: human + planner: ai + implementer: ai + reviewer: human + critic: ai + scribe: ai +--- + +# Feature Specification: AGT-Inspired Governance Improvements + +**Feature Branch**: `001-agt-governance-improvements` +**Created**: 2026-06-03 +**Status**: Complete +**Input**: User description: "Incorporate governance improvements inspired by Microsoft AGT analysis: structured severity registry, trust-tiered review depth, explicit limitations documentation, and prompt conformance tests" + +## Rationale Summary + +### Core Problem + +DevSpark's constitution and PR review workflow enforce quality gates, but the findings they produce are informal: severity labels (HIGH/MEDIUM) are scattered across constitution sections with no central registry, review depth does not vary based on whether the spec-driven workflow was actually followed, the framework makes no honest public statement about what it does and does not govern, and command prompt templates have no automated validation to detect constitution drift. These gaps mean governance is harder to measure, easier to bypass, and opaque to new adopters. + +### Decision Summary + +Extend DevSpark's existing process governance with four targeted improvements borrowed from the Microsoft Agent Governance Toolkit's architectural philosophy: a structured severity registry, trust-tiered review depth, an explicit limitations document, and a prompt conformance lint check. All four improvements are additive and backward-compatible — no existing workflows are removed or restructured. + +### Key Drivers + +- **Consistency**: PR review findings reference constitution sections inconsistently, making aggregate tracking impossible. +- **Incentive alignment**: Review rigor should reflect actual workflow compliance — a PR backed by a complete spec deserves faster review than one with no spec. +- **Intellectual honesty**: Adopters need to know what DevSpark governs and what it does not, matching AGT's own documented limitations model. +- **Constitution integrity**: Command prompt templates can drift from the constitution after amendments without any automated detection. + +### Tradeoffs Considered + +- **Option A — Full runtime enforcement (AGT-style)**: Cryptographic audit trails, policy engines, execution rings. Rejected: DevSpark operates in developer workflows with a human always present; runtime enforcement infrastructure is over-engineering for this trust context. +- **Option B — Ignore AGT findings**: Simpler, no changes. Rejected: the four identified gaps are real, lightweight to address, and improve long-term governance coherence. +- **Selected — Targeted process improvements**: Adopt AGT's *philosophy* (structured severity, trust tiers, honest limitations, conformance testing) without adopting its runtime infrastructure. Fits DevSpark's markdown-and-conventions model. + +### Architectural Impact + +- New file: `.documentation/memory/known-limitations.md` (additive, no existing file displaced) +- New file: `.documentation/memory/severity-registry.md` (additive; becomes the authoritative severity mapping) +- Constitution referenced but not amended — severity registry is a companion document, not a constitution change +- PR review command (`templates/commands/pr-review.md`) updated to reference severity registry and trust-tier logic +- New file: `.documentation/memory/prompt-conformance-manifest.md` — Markdown conformance manifest listing three required sections per command template, evaluated via `/devspark.checklist`; no new tool dependencies +- Updated file: `templates/commands/evolve-constitution.md` — adds two checklist items: severity-registry co-update (FR-009) and known-limitations check (FR-006) + +### Reviewer Guidance + +Reviewers should verify: (1) the severity registry is consistent with existing constitution section markers; (2) trust-tier thresholds are objective and checkable from git/branch state; (3) the limitations document is honest and does not overstate what DevSpark governs; (4) prompt conformance checks are lightweight enough to not block contribution workflows. + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 — Structured Severity Registry (Priority: P1) ✅ Complete + +A DevSpark contributor reviews a PR using `/devspark.pr-review`. The review produces findings, each tagged with a severity code that links back to a specific constitution section (e.g., `§VIII.HIGH`). The contributor can look up any finding in the severity registry to understand its scope, rationale, and remediation guidance without re-reading the full constitution. + +**Why this priority**: The severity registry is foundational to the other improvements. Trust-tiered review depth and prompt conformance both produce findings; without a registry, their outputs are as inconsistent as the current state. + +**Independent Test**: Run `/devspark.pr-review` on any open PR. Verify that every finding in the output includes a severity code matching a registry entry, and that the registry file exists at `.documentation/memory/severity-registry.md`. + +**Acceptance Scenarios**: + +1. **Given** a PR review is generated, **When** a finding is emitted with severity HIGH, **Then** it includes a section reference (e.g., `§VI.HIGH`) that maps to an entry in the severity registry. +2. **Given** the severity registry exists, **When** a user looks up a section reference, **Then** they find: the constitution section, severity level, description, and example remediation. +3. **Given** a constitution amendment is ratified, **When** the amendment introduces or changes a severity marker, **Then** the severity registry is updated in the same PR. + +--- + +### User Story 2 — Trust-Tiered Review Depth (Priority: P2) ✅ Complete + +A developer submits a PR on a branch that has a complete spec, plan, and tasks in `.documentation/specs/`. The PR review runs at standard depth. A second developer submits a PR on a branch with no spec artifacts. The review runs at elevated depth, explicitly noting the missing workflow compliance as a finding. + +**Why this priority**: Creates a positive incentive to follow the spec-driven workflow. PRs that skip the process get more scrutiny, not less — making the governance self-reinforcing without requiring enforcement machinery. + +**Independent Test**: Submit two PRs — one on a branch with complete spec artifacts, one without. Verify the review output for the spec-less branch includes a trust-tier finding and performs a deeper check pass than the spec-complete branch. + +**Acceptance Scenarios**: + +1. **Given** a PR branch has a `spec.md`, `plan.md`, and tasks file under `.documentation/specs/`, **When** `/devspark.pr-review` runs, **Then** the review runs at standard depth and notes the workflow compliance positively. +2. **Given** a PR branch has no spec artifacts, **When** `/devspark.pr-review` runs, **Then** the review emits a trust-tier finding (MEDIUM severity) and applies an elevated scrutiny pass to all other findings. +3. **Given** a PR branch has a spec but no plan, **When** `/devspark.pr-review` runs, **Then** the review notes partial compliance and applies a moderate scrutiny adjustment. + +--- + +### User Story 3 — Explicit Limitations Documentation (Priority: P3) ✅ Complete + +A team evaluating DevSpark reads `.documentation/memory/known-limitations.md` and learns what the framework does and does not govern — before discovering a gap in production. They can make an informed decision about what complementary tooling they need. + +**Why this priority**: Intellectual honesty improves trust and reduces support burden. Adopters who understand the boundaries make better architectural decisions. + +**Independent Test**: The file `.documentation/memory/known-limitations.md` exists, is non-empty, lists at least four distinct limitations with rationale, and is referenced from `constitution.md` or the project README. + +**Acceptance Scenarios**: + +1. **Given** a new team evaluates DevSpark, **When** they read `known-limitations.md`, **Then** they find at least four explicitly described governance gaps with honest rationale for why they are out of scope. +2. **Given** a limitation is discovered in a PR review or constitution evolution session, **When** the limitation is confirmed as structural (not a bug), **Then** it is documented in `known-limitations.md` in the same PR. +3. **Given** `known-limitations.md` exists, **When** the constitution is amended, **Then** the amendment process checks whether any new limitations are implied and updates the file if so. + +--- + +### User Story 4 — Prompt Conformance Lint (Priority: P4) ✅ Complete + +A contributor edits a command template in `templates/commands/`. Before the PR is merged, a conformance check verifies the template still references required sections (constitution check gate, artifact output format, handoff labels) and has not silently dropped governance-critical content. The check produces a pass/fail report. + +**Why this priority**: Command templates are the primary delivery mechanism for DevSpark's governance. If they drift from the constitution, the entire framework degrades silently. + +**Independent Test**: Edit a command template to remove a required section (e.g., the Constitution Authority block). Run the conformance check. Verify it reports a failure. Restore the section and verify it passes. + +**Acceptance Scenarios**: + +1. **Given** a command template has all required sections, **When** the prompt conformance check runs, **Then** it reports all checks passed. +2. **Given** a command template is missing the `Constitution Authority` section, **When** the conformance check runs, **Then** it reports a HIGH severity finding citing `§IV`. +3. **Given** the conformance check runs in CI, **When** any command template fails, **Then** the CI job fails and the PR cannot merge without remediation. + +--- + +### Edge Cases + +- What happens when a PR branch name does not follow the `NNN-short-name` convention? The trust-tier check should treat it as no-spec (lowest trust tier) and note the naming gap. +- What happens when a spec artifact exists but is in `Draft` status and the PR touches unrelated files? Standard depth review applies — spec existence matters, not completeness of implementation. +- What happens when the severity registry and a constitution section marker conflict? The constitution is authoritative; the registry must be updated, not the constitution. +- What happens when `constitution.md` is amended by a direct file edit without using `/devspark.evolve-constitution`? The severity registry and `known-limitations.md` are not automatically updated. The severity registry document itself carries a maintenance note requiring the author to manually verify and update both companion documents in the same PR. This gap is documented as L-006 in `known-limitations.md`. +- What happens when a new command is added without a corresponding prompt conformance rule? The conformance manifest defines a default behavior: template files in `templates/commands/` not explicitly listed in the manifest are evaluated against the three universal required elements (Constitution Authority block, `handoffs` frontmatter, artifact output statement) — no special rule needed, and any file failing those elements is flagged as a LOW finding requiring attention. + +## Requirements *(mandatory)* + +### Functional Requirements + +- **FR-001**: The severity registry MUST map every constitution section that carries a severity marker (HIGH, MEDIUM) to a structured entry containing: section reference, severity level, description, and example remediation guidance. The registry document MUST use YAML frontmatter for document metadata and a Markdown table (one row per constitution section) for entries — making it both human-readable and parseable by a script without new tool dependencies. +- **FR-002**: The PR review command MUST emit findings in structured YAML format matching the Shared Review Resolution Contract schema (finding_id, severity, description, recommended_action, execution_mode, status, outcome), with severity codes in the format `§{section}.{LEVEL}` matching entries in the severity registry. This enables `/devspark.address-pr-review` and `/devspark.harvest` to act on findings deterministically without new parsing logic. +- **FR-003**: The PR review command MUST detect whether a branch has spec artifacts (spec.md, plan.md, tasks file) and classify the branch into a trust tier (full-compliance, partial-compliance, no-compliance). +- **FR-004**: The PR review command MUST adjust its review depth based on the detected trust tier — no-compliance branches MUST receive an elevated scrutiny pass implemented as: (a) a MEDIUM trust-tier finding using the Shared Review Resolution Contract schema, and (b) an explicit inline reminder to the reviewer to apply heightened attention to all other findings in the report. +- **FR-005**: The `known-limitations.md` file MUST exist at `.documentation/memory/known-limitations.md` and MUST document at least five distinct governance limitations with rationale for why each is out of scope. One entry (L-006) MUST document the direct-constitution-edit bypass gap: that direct edits to `constitution.md` without using `/devspark.evolve-constitution` leave the severity registry and known-limitations doc silently stale. +- **FR-006**: The constitution amendment process MUST include a check for whether the amendment implies new limitations that should be added to `known-limitations.md`. +- **FR-007**: A prompt conformance check MUST exist that validates command templates in `templates/commands/` against three required sections present in every well-formed command: (1) `## Constitution Authority` block, (2) frontmatter `handoffs` block, and (3) at least one artifact output statement. The check is implemented as a Markdown conformance manifest at `.documentation/memory/prompt-conformance-manifest.md` invoked via `/devspark.checklist` — no new scripts or tool dependencies required. +- **FR-008**: The prompt conformance check MUST report findings with severity codes from the severity registry and MUST be runnable without installing external tools beyond what DevSpark already requires. The AI agent reads the conformance manifest and validates each template file inline, producing a structured pass/fail report. +- **FR-009**: The severity registry MUST be updated in the same PR as any constitution amendment that adds, removes, or modifies a severity marker — this co-update MUST be required as a checklist item in the `evolve-constitution` workflow. + +### Key Entities + +- **Severity Registry**: A structured document (YAML frontmatter + Markdown table, one row per constitution section) mapping constitution sections to severity levels, descriptions, and remediation guidance. Lives at `.documentation/memory/severity-registry.md`. +- **Trust Tier**: A classification (full-compliance / partial-compliance / no-compliance) assigned to a PR branch based on the presence of spec artifacts. Determined at review time from branch file state. +- **Known Limitations**: A document cataloguing what DevSpark does not govern, with honest rationale. Lives at `.documentation/memory/known-limitations.md`. +- **Prompt Conformance Rule**: A defined assertion about a required section or structural element in a command template. Rules are maintained in a Markdown conformance manifest at `.documentation/memory/prompt-conformance-manifest.md` and evaluated by an AI agent via `/devspark.checklist` — no new scripts or tooling required. + +## Success Criteria *(mandatory)* + +### Measurable Outcomes + +- **SC-001**: Every PR review finding produced by `/devspark.pr-review` includes a severity code matching an entry in the severity registry — verifiable by reading any review output against the registry. +- **SC-002**: A PR on a branch with no spec artifacts receives a trust-tier finding (MEDIUM) and at least one additional scrutiny pass not present in a spec-complete PR review — verifiable by comparing two review outputs side-by-side. +- **SC-003**: `known-limitations.md` documents at least four limitations on day one of merge, and grows monotonically as new gaps are identified in constitution evolution sessions. +- **SC-004**: The prompt conformance check correctly identifies a missing `Constitution Authority` section in a command template — verifiable by a deliberate test edit and check run. +- **SC-005**: All four improvements are additive — no existing PR reviews, specs, plans, or tasks are invalidated or require migration after merge. +- **SC-006**: The severity registry co-update checklist item is present in `evolve-constitution.md` at merge — verifiable by reading the template. Forward-looking: the next constitution amendment PR demonstrates the checklist item being exercised, verifiable from PR history. + +## Clarifications + +### Session 2026-06-03 + +- Q: What format should the severity registry document use? → A: YAML frontmatter for document metadata plus a Markdown table (one row per constitution section) — human-readable and script-parseable without new tool dependencies. +- Q: Should PR review findings be structured or freeform? → A: Structured YAML findings block matching the existing Shared Review Resolution Contract schema (finding_id, severity, description, recommended_action, execution_mode, status, outcome) — consistent with clarify and address-pr-review commands. +- Q: How should the prompt conformance check be invoked? → A: AI agent reads a Markdown conformance manifest and validates each template via `/devspark.checklist` — no new scripts or tool dependencies; CI wiring is a future follow-on. +- Q: Which sections are required in every command template per the conformance manifest? → A: Three sections: `## Constitution Authority` block, frontmatter `handoffs` block, and at least one artifact output statement — present in all existing well-formed commands. +- Q: Where should the conformance manifest live? → A: `.documentation/memory/prompt-conformance-manifest.md` — co-located with `severity-registry.md` and `known-limitations.md` in the governance memory directory, consistent with §III Ownership Boundary. + +## Assumptions + +- The source repo structure (scripts in `scripts/`, commands in `templates/commands/`) applies throughout — no `.devspark/` prefix needed for script paths. +- The current constitution version (1.4.0) is the baseline; no new constitution amendment is required to ship these improvements (the severity registry is a companion document, not a constitution change). +- Prompt conformance checks are implemented as a Markdown conformance manifest evaluated by an AI agent via `/devspark.checklist` — no new scripts or CI tool dependencies in this iteration. +- Trust tier detection relies on file presence in `.documentation/specs/{branch-name}/` — no git history analysis required. +- The `evolve-constitution` command template is in scope for a minor update to add two checklist items: the severity-registry co-update (FR-009) and the known-limitations check (FR-006). + +## Out of Scope + +- Runtime enforcement of governance (cryptographic identity, policy engines, execution rings) — DevSpark operates in human-in-the-loop developer workflows where this infrastructure is unnecessary. +- Automated CI integration for prompt conformance in this iteration — the check is defined and runnable manually; CI wiring is a follow-on. +- Changes to existing spec, plan, or tasks templates — improvements are additive to review and meta-documentation only. +- Trust scoring with numeric decay or behavioral regime detection (AGT-style) — binary/ternary tier classification is sufficient for DevSpark's workflow context. +- OWASP, NIST, or EU AI Act compliance mapping — DevSpark governs developer process, not production AI agent behavior. diff --git a/.documentation/specs/001-agt-governance-improvements/tasks.md b/.documentation/specs/001-agt-governance-improvements/tasks.md new file mode 100644 index 00000000..740139e9 --- /dev/null +++ b/.documentation/specs/001-agt-governance-improvements/tasks.md @@ -0,0 +1,243 @@ +--- +description: "Task list for AGT-Inspired Governance Improvements" +participants: + owner: human + planner: ai + implementer: ai + reviewer: human + critic: ai + scribe: ai +--- + +# Tasks: AGT-Inspired Governance Improvements + +**Input**: Design documents from `.documentation/specs/001-agt-governance-improvements/` +**Prerequisites**: plan.md ✅ | spec.md ✅ | research.md ✅ + +**Organization**: Tasks are grouped by user story to enable independent implementation and testing. + +## Rationale Summary + +### Core Problem + +DevSpark's constitution and PR review workflow produce informal, inconsistent governance output: no central severity registry, uniform review depth regardless of spec compliance, no explicit limitations document, and no conformance check for command template drift. + +### Decision Summary + +Five files (3 new, 2 updated) deliver all four improvements with no new tool dependencies, no new scripts, and no constitution amendments — all additive and backward-compatible. + +### Key Drivers + +- Severity registry: machine-trackable findings across amendment cycles +- Trust tiers: self-reinforcing incentive for spec-driven development +- Limitations doc: adopter trust through intellectual honesty +- Conformance manifest: prevents silent constitution drift in command templates + +### Reviewer Guidance + +Verify: severity codes match constitution markers exactly; trust-tier logic is file-presence only; limitations document does not overstate DevSpark's scope; pr-review insertions are purely additive (no existing content removed); markdownlint passes on all new files. + +## Format: `[ID] [P?] [Story] Description` + +- **[P]**: Can run in parallel (different files, no dependencies) +- **[Story]**: Which user story this task belongs to (US1–US4) + +--- + +## Phase 1: Setup + +**Purpose**: Verify scaffold and confirm markdownlint configuration covers new file paths. + +- [x] T001 Confirm `.markdownlint-cli2.jsonc` does not need updating for `.documentation/memory/` paths (read the file; verify new files will be linted automatically, not excluded) + +**Checkpoint**: Phase complete — 2026-06-03 + +--- + +## Phase 2: Foundational (Blocking Prerequisites) + +**Purpose**: Core governance artifact that all other improvements reference. + +**⚠️ CRITICAL**: T002 must be complete before US2, US3, and US4 work can begin — all other stories emit findings that reference the registry. + +- [x] T002 Create `.documentation/memory/severity-registry.md` with YAML frontmatter and Markdown table containing all 8 severity entries from research.md (§I–§VIII, SHOWSTOPPER/HIGH/MEDIUM, finding codes, triggers, and remediation examples). Include a self-referential maintenance note in the document: "If `constitution.md` is amended directly without using `/devspark.evolve-constitution`, the author MUST manually verify and update this registry in the same PR." + +**Checkpoint**: Severity registry complete — US2, US3, US4 phases can now begin (all can run in parallel after this point). + +**Checkpoint**: Phase complete — 2026-06-03 + +--- + +## Phase 3: User Story 1 — Structured Severity Registry (Priority: P1) 🎯 MVP + +**Goal**: The severity registry exists and pr-review emits `§{section}.{LEVEL}` codes matching registry entries. + +**Independent Test**: Run `/devspark.pr-review` on any PR; verify every finding includes a severity code; look up that code in `.documentation/memory/severity-registry.md` and find a matching entry. + +### Implementation for User Story 1 + +- [x] T003 [US1] Update `templates/commands/pr-review.md` — two insertions: (a) Append a "#### Severity Code Format" subsection immediately after the line `| Constitution needs updating (not code) | CON | Governance improvement |` in the "Guidelines > Severity Guidelines" section: mandate `§{section}.{LEVEL}` format for all constitution-linked findings, document examples (`§VI.HIGH`, `§VII.MEDIUM`, `§VIII.HIGH`, `§I.SHOWSTOPPER`), add rule that non-constitution findings emit without a `§` code and are flagged as CON candidates; (b) In step "### 2. Load Constitution", add a sub-bullet: "Load `.documentation/memory/severity-registry.md` if it exists; use its entries to validate `§{section}.{LEVEL}` codes when emitting findings." Verify after editing: run `grep -c "^###" templates/commands/pr-review.md` — count should increase by 0 (no new ### headings from this insertion); confirm file still passes markdownlint. +- [x] T004 [US1] Run `npx markdownlint-cli2 ".documentation/memory/severity-registry.md"` and fix any lint errors before committing + +**Checkpoint**: US1 complete — pr-review now references severity codes and the registry is the authoritative lookup. + +**Checkpoint**: Phase complete — 2026-06-03 + +--- + +## Phase 4: User Story 2 — Trust-Tiered Review Depth (Priority: P2) + +**Goal**: pr-review detects branch spec-artifact presence, classifies trust tier, and adjusts scrutiny accordingly. + +**Independent Test**: Run `/devspark.pr-review` on a branch with no spec artifacts; verify the output includes a `trust-tier-01` finding with MEDIUM severity and a recommendation to run `/devspark.specify`. + +### Implementation for User Story 2 + +- [x] T005 [US2] Update `templates/commands/pr-review.md` — insert new step "### 1b. Trust-Tier Classification" immediately after the closing paragraph of "### 1. Initialize Review Context" and before the line "### 2. Load Constitution" (use the exact anchor: insert before the line that begins `### 2. Load Constitution`). Content: detect `head_branch`, derive spec dir `.documentation/specs/{head_branch}/`, check for `spec.md`/`plan.md`/`tasks.md`, classify as `full-compliance`/`partial-compliance`/`no-compliance`, emit MEDIUM finding for no-compliance using Shared Review Resolution Contract schema (`finding_id: trust-tier-01`, `severity: medium`, `execution_mode: manual`), and include an explicit reviewer note: "⚠️ No spec artifacts detected — apply heightened attention to all findings in this report." Also search for any existing cross-references to "step 1" or "step 2" in the file and verify they remain accurate after insertion. Verify after editing: run `grep -c "^### [0-9]" templates/commands/pr-review.md` — count should increase by exactly 1 (the new 1b step); confirm markdownlint passes. +- [x] T006 [US2] Run `npx markdownlint-cli2 "templates/commands/pr-review.md"` and fix any lint errors before committing + +**Checkpoint**: US2 complete — pr-review now varies scrutiny based on spec-workflow compliance. T003 (US1) must be complete first so severity codes are in place for the trust-tier finding. + +**Checkpoint**: Phase complete — 2026-06-03 + +--- + +## Phase 5: User Story 3 — Explicit Limitations Documentation (Priority: P3) + +**Goal**: `known-limitations.md` exists with at least five honest, well-rationale'd limitations. + +**Independent Test**: Read `.documentation/memory/known-limitations.md`; verify at least five limitations with `**Scope**`, `**Rationale**`, and `**Complementary tooling**` fields; verify the file is referenced from `constitution.md` or the project README. + +### Implementation for User Story 3 + +- [x] T007 [P] [US3] Create `.documentation/memory/known-limitations.md` with document header, scope statement, and six limitation entries (L-001 through L-006) from plan.md plus critic-004: L-001 runtime agent behavior, L-002 outcome verification, L-003 cross-session sequences, L-004 technical enforcement, L-005 AI context provenance, L-006 direct-constitution-edit bypass (direct edits to `constitution.md` without using `/devspark.evolve-constitution` leave severity registry and known-limitations silently stale; mitigation: severity-registry.md carries a maintenance note) +- [x] T008 [US3] Add a reference to `known-limitations.md` in `.documentation/memory/constitution.md` — insert a `## Companion Documents` section immediately before the `**Version**:` metadata line at the bottom of the file, containing one bullet: `- [Known Governance Limitations](known-limitations.md)`. Do not append after the version/ratified/last-amended lines. +- [x] T009 [US3] Run `npx markdownlint-cli2 ".documentation/memory/known-limitations.md" ".documentation/memory/constitution.md"` and fix any lint errors before committing + +**Checkpoint**: US3 complete — adopters can read limitations alongside the constitution. + +**Checkpoint**: Phase complete — 2026-06-03 + +--- + +## Phase 6: User Story 4 — Prompt Conformance Lint (Priority: P4) + +**Goal**: The conformance manifest exists and can be evaluated against all command templates in `templates/commands/` via `/devspark.checklist`. + +**Independent Test**: Open `.documentation/memory/prompt-conformance-manifest.md`; invoke `/devspark.checklist` with the manifest against `templates/commands/`; deliberately remove `## Constitution Authority` from one command template; verify the check reports a HIGH finding citing `§IV`; restore the section and verify the check passes. + +### Implementation for User Story 4 + +- [x] T010 [P] [US4] Create `.documentation/memory/prompt-conformance-manifest.md` with: document header, the three required element checks (Constitution Authority block, frontmatter `handoffs` key, artifact output statement), the conformance check procedure using Shared Review Resolution Contract schema, the known variant headings section (documenting `evolve-constitution.md`'s "## Lifecycle Position" as acceptable), finding ID pattern `conformance-{command-name}-{01|02|03}`, a default behavior rule (any unlisted template is evaluated against the three universal elements; failures flagged as LOW), and deterministic string-match anchors for each check: (1) Constitution Authority passes if the file contains the string `constitution.md` AND the word `non-negotiable` within 15 lines of each other — OR is listed in the Known Variant Headings section with its qualifying text documented; (2) `handoffs` passes if the YAML frontmatter block contains the key `handoffs:`; (3) artifact output statement passes if the file contains at least one of the phrases: "Write", "Save", "Create", "Generate", "Output" within a section describing what the command produces. These string-match anchors make evaluation reproducible across agent runs. +- [x] T011 [US4] Update `templates/commands/evolve-constitution.md` — add two checklist items to the "Review Checklist" block in Step 5 (Proposal Generation): (1) "If the amendment adds, removes, or modifies a severity marker, `.documentation/memory/severity-registry.md` is updated in the same PR (FR-009)" and (2) "Check whether the amendment implies new governance limitations; if so, update `.documentation/memory/known-limitations.md` in the same PR (FR-006)" +- [x] T012 [US4] Run `npx markdownlint-cli2 ".documentation/memory/prompt-conformance-manifest.md" "templates/commands/evolve-constitution.md"` and fix any lint errors before committing +- [x] T013 [US4] Perform baseline conformance check: invoke `/devspark.checklist` with the conformance manifest against all files in `templates/commands/`; document the baseline pass/fail results as a comment in the manifest file. Also manually verify 3 known-good templates (e.g., `specify.md`, `plan.md`, `pr-review.md`) pass all three checks as a sanity test before accepting the full baseline. Note in the manifest: "Re-run this check before any PR that modifies files in `templates/commands/`." + +**Checkpoint**: US4 complete — conformance manifest is live and the baseline has been established. + +**Checkpoint**: Phase complete — 2026-06-03 + +--- + +## Phase 7: Polish & Cross-Cutting Concerns + +**Purpose**: Final markdownlint sweep, commit isolation verification, and spec status update. + +- [x] T014 [P] Run full markdownlint sweep: `npx markdownlint-cli2 "**/*.md"` from repo root; fix any errors introduced by this feature's files before creating the PR +- [x] T015 Update `.documentation/specs/001-agt-governance-improvements/spec.md` — change `**Status**: Draft` to `**Status**: Complete` now that all tasks are done +- [x] T016 Verify commit isolation discipline (§VII): ensure the PR review file (if one exists at `.documentation/specs/pr-review/pr-NNN.md`) is committed in its own isolated commit, separate from the governance artifact commits + +--- + +## Dependencies & Execution Order + +### Phase Dependencies + +- **Setup (Phase 1)**: No dependencies — start immediately +- **Foundational (Phase 2 — T002)**: Depends on Setup; **BLOCKS US2, US3, US4 finding emission** (registry must exist before other improvements reference it) +- **US1 Phase (Phase 3 — T003–T004)**: Depends on T002; no dependency on US2/US3/US4 +- **US2 Phase (Phase 4 — T005–T006)**: Depends on T002 and T003 (severity codes must be defined before trust-tier finding references them) +- **US3 Phase (Phase 5 — T007–T009)**: Depends on T002; can run in parallel with US1 and US4 +- **US4 Phase (Phase 6 — T010–T013)**: Depends on T002; can run in parallel with US1 and US3 +- **Polish (Phase 7)**: Depends on all user story phases complete + +### User Story Dependencies + +- **US1 (P1)**: Depends on T002 (registry) — no other story dependencies +- **US2 (P2)**: Depends on T002 + T003 (severity code format must be established before trust-tier finding references it) +- **US3 (P3)**: Depends on T002 only — fully independent of US1/US2/US4 +- **US4 (P4)**: Depends on T002 only — fully independent of US1/US2/US3 + +### Parallel Opportunities + +After T002 (registry) is complete: + +- T003+T004 (US1), T007 (US3 part 1), T010 (US4 part 1) can all start in parallel +- T005+T006 (US2) can start after T003 completes +- T008+T009 (US3 part 2) can start after T007 completes + +--- + +## Parallel Example: After Foundational Complete + +```text +# Once T002 is done, launch in parallel: +Task T003: Update pr-review.md severity code guidance [US1] +Task T007: Create known-limitations.md [US3] +Task T010: Create prompt-conformance-manifest.md [US4] + +# After T003 completes, start: +Task T005: Update pr-review.md trust-tier step [US2] +``` + +--- + +## Gate Acknowledgements + +- **Gate**: analyze, critic +- **Concern**: `required_gates: checklist, analyze, critic` — analyze and critic have not run yet at task generation time. The spec and plan are complete; these gates are appropriate to run before or during implementation, not as a pre-condition to generating tasks. +- **Decision**: Proceed to implementation. Run `/devspark.analyze` and `/devspark.critic` before creating the PR. +- **Recorded By**: planner (ai) +- **Date**: 2026-06-03 + +--- + +## Implementation Strategy + +### MVP First (User Story 1 Only) + +1. Complete Phase 1: Setup (T001) +2. Complete Phase 2: Foundational (T002) — creates severity registry +3. Complete Phase 3: User Story 1 (T003–T004) — pr-review emits severity codes +4. **STOP and VALIDATE**: Run `/devspark.pr-review` on a test PR; confirm `§VI.HIGH`-style codes appear in findings +5. Continue to remaining stories if validated + +### Incremental Delivery + +1. Setup + Foundational → registry live +2. US1 → severity codes in pr-review → validate +3. US2 → trust tiers in pr-review → validate +4. US3 → limitations document live → validate +5. US4 → conformance manifest + evolve-constitution update → validate baseline +6. Polish → clean sweep → PR ready + +### Single-Developer Sequence (Recommended) + +```text +T001 → T002 → T003 → T004 → T005 → T006 → T007 → T008 → T009 → T010 → T011 → T012 → T013 → T014 → T015 → T016 +``` + +--- + +**Checkpoint**: Phase complete — 2026-06-03 + +## Notes + +- No [P] tasks share files — all parallel tasks touch distinct files +- §VII commit discipline: each logical unit (registry, pr-review update, known-limitations, conformance manifest) should be its own commit +- All new `.md` files must pass markdownlint before the PR is opened (tracked as T004, T006, T009, T012, T014) +- Trust-tier insertion in pr-review (T005) is purely additive — verify no existing content is removed; use the exact anchor text in T005 and check heading count after insertion +- Baseline conformance check (T013) may surface existing gaps in command templates; document findings without blocking this PR's merge +- **Contributor obligation (ongoing)**: Run `/devspark.checklist` against `.documentation/memory/prompt-conformance-manifest.md` before any PR that modifies files in `templates/commands/` — this is the re-run trigger for the conformance baseline +- **markdownlint environment**: Requires Node.js + `npx`, or a locally installed `markdownlint-cli2` binary — document this prerequisite in CONTRIBUTING.md if not already present +- **Direct constitution edits**: If `constitution.md` is amended without `/devspark.evolve-constitution`, the author must manually update `severity-registry.md` and check `known-limitations.md` in the same PR (documented as L-006) diff --git a/.documentation/specs/pr-review/pr-48.md b/.documentation/specs/pr-review/pr-48.md new file mode 100644 index 00000000..732f5af0 --- /dev/null +++ b/.documentation/specs/pr-review/pr-48.md @@ -0,0 +1,219 @@ +# Pull Request Review: feat: AGT-inspired governance improvements + +## Review Metadata + +- **PR Number**: #48 +- **Source Branch**: 001-agt-governance-improvements +- **Target Branch**: main +- **Review Date**: 2026-06-03 23:55:00 UTC +- **Last Updated**: 2026-06-04 00:10:00 UTC +- **Reviewed Commit**: 1cfd3c003a2940fde3055541b2ee0ae9b2daf220 +- **Reviewer**: devspark.pr-review +- **Constitution Version**: 1.4.0 + +## Revision Log + +| Rev | Commit | Date | Critical | High | Medium | Low | CON | Test Command | Result | +|-----|--------|------|----------|------|--------|-----|-----|--------------|--------| +| 1 | 1cfd3c0 | 2026-06-03 | 0 | 1 | 1 | 1 | 0 | npx markdownlint-cli2 "**/*.md" | pass (0 errors, 381 files) | +| 2 | 050e145 | 2026-06-04 | 0 | 0 | 0 | 0 | 0 | npx markdownlint-cli2 "**/*.md" | pass (0 errors, 381 files) | + +## PR Summary + +- **Author**: @markhazleton +- **Created**: 2026-06-03 +- **Status**: OPEN +- **Files Changed**: 13 +- **Commits**: 3 +- **Lines**: +1644 -0 + +## Stats + +| Metric | Value | +|--------|-------| +| Files changed | 13 | +| Lines added | +1644 | +| Lines removed | 0 | +| Net lines | +1644 | +| Commit snapshot | `1cfd3c0` | + +## Executive Summary + +- ✅ **Constitution Compliance**: PASS (8/8 principles checked) +- 📋 **Spec Lifecycle**: Complete +- 📝 **Task Completion**: 16/16 tasks complete +- 🔒 **Security**: No issues found +- 📊 **Code Quality**: 1 recommendation +- 🧪 **Testing**: PASS (markdownlint 0 errors, 381 files) +- 📝 **Documentation**: PASS +- 🏛️ **Constitution Improvements**: 0 CON findings + +**Overall Assessment**: A well-executed spec-driven feature delivering four additive governance improvements. All changes are pure Markdown — no runtime code, no new tool dependencies. One HIGH finding on the pr-review.md trust-tier step (partial-compliance missing from the YAML example) and one MEDIUM on the conformance manifest baseline comment format. One LOW style note. + +**Approval Recommendation**: ✅ APPROVE — all findings resolved in 050e145. + +## Action Items + +### Immediate Actions (Blocking — must resolve before merge) + +- [x] **H-01** `templates/commands/pr-review.md:step-1b` — Trust-tier YAML example hardcodes `{head_branch}` placeholder but partial-compliance branches get no finding; the step description says to emit a finding "for no-compliance" only, but the reviewer-alert blockquote fires unconditionally. A partial-compliance branch would receive the alert without a finding, which contradicts FR-004's intent. — *Fixed in 050e145: moved ⚠️ alert blockquote inside no-compliance conditional (step 5); added explicit partial-compliance inline note* + +### Recommended Improvements + +- [x] **M-01** `.documentation/memory/prompt-conformance-manifest.md:Baseline` — The baseline comment block uses HTML comment syntax (``) which is valid but the closing `-->` is on a line after the last content line. Minor but could confuse readers about where the comment ends vs. content begins. — *Fixed in 050e145: removed blank lines inside HTML comment block* +- [x] **L-01** `.documentation/memory/severity-registry.md` — The "Companion Documents" section at the bottom links to `known-limitations.md` and `severity-registry.md` (self-link) and `.documentation/memory/constitution.md` (absolute-style path). Relative links would be more portable (e.g., `constitution.md` not `.documentation/memory/constitution.md`) since all three files are in the same directory. — *Fixed in 050e145: changed to relative path `constitution.md`; self-link was already absent* + +## What's Good + +- **Surgical precision**: All three commits are logically isolated and commit messages clearly explain the "why". §VII honored throughout. +- **Completeness**: The severity registry correctly captures all 8 distinct severity-bearing entries from the constitution (§I–§IV SHOWSTOPPER, §VI HIGH, §VII MEDIUM, §VIII HIGH+MEDIUM) with no gaps or additions. +- **Self-referential honesty**: L-006 in known-limitations.md documents the very bypass mechanism that could undermine the registry — exactly the kind of intellectual honesty the AGT analysis recommended. +- **Deterministic anchors**: The conformance manifest's string-match anchors (constitution.md + non-negotiable within 15 lines, handoffs: in frontmatter, output verb) make the check reproducible without tooling. +- **markdownlint clean**: 381 files, 0 errors after fixing research.md and the CLAUDE.md pre-existing issues. + +## Findings Detail + +### Critical Issues (Blocking) + +None found. + +### High Priority Issues + +| ID | Status | Principle | File:Line | Issue | Fix | +|----|--------|-----------|-----------|-------|-----| +| H-01 | ✅ Resolved | §II Explicit Over Implied | `templates/commands/pr-review.md:step-1b` | The reviewer-alert blockquote (⚠️ No spec artifacts detected) fires unconditionally in the step text, but the step logic says to emit the YAML finding "for no-compliance branches" only. A partial-compliance branch would trigger the alert without the finding, creating an implicit/inferred behavior gap. The blockquote should be nested inside the step-5 no-compliance condition, not at the top level of the step. | Move the `> ⚠️ No spec artifacts detected` blockquote inside the step-5 conditional block so it only renders when a no-compliance finding is emitted. | + +### Medium Priority Suggestions + +| ID | Status | Principle | File:Line | Issue | Recommendation | +|----|--------|-----------|-----------|-------|----------------| +| M-01 | ✅ Resolved | §VIII Markdown Quality | `.documentation/memory/prompt-conformance-manifest.md:Baseline` | The `` HTML comment block spans multiple lines ending with `-->` on its own line after a blank line. While valid HTML comment syntax, the blank line inside the comment (`\n\n`) may confuse readers about the comment boundary. | Remove the blank line inside the HTML comment block so the `-->` immediately follows the last content line. | + +### Low Priority Improvements + +| ID | Status | Principle | File:Line | Issue | Recommendation | +|----|--------|-----------|-----------|-------|----------------| +| L-01 | ✅ Resolved | §V Simplicity | `.documentation/memory/severity-registry.md:Companion Documents` | Self-link to `severity-registry.md` in its own Companion Documents section is redundant. The absolute-style path `.documentation/memory/constitution.md` in a link from within `.documentation/memory/` is also non-portable if the memory directory is ever moved. | Remove the self-link; use relative path `constitution.md` (not `.documentation/memory/constitution.md`) in the companion links. | + +### Constitution Improvements + +None found. + +## Constitution Alignment Details + +| Principle | Status | Evidence | Notes | +|-----------|--------|----------|-------| +| §I Backward Compatibility (NON-NEGOTIABLE) | ✅ Pass | All 13 files are additive; no existing files restructured or behavior changed | Constitution companion section added before version line — non-breaking | +| §II Explicit Over Implied (NON-NEGOTIABLE) | ⚠️ Partial | Trust-tier step is explicit for no-compliance; reviewer alert placement ambiguous for partial-compliance | H-01 — fix alert placement | +| §III Ownership Boundary (NON-NEGOTIABLE) | ✅ Pass | All new files in `.documentation/memory/` (repo-owned) and `templates/commands/` (framework); no `.devspark/` writes | Verified across all 13 changed files | +| §IV Governance Authority | ✅ Pass | Registry is a companion document; constitution remains authoritative; amendment checklist items added to evolve-constitution | Constitution referenced explicitly in all new files | +| §V Simplicity | ✅ Pass | No new tool dependencies; `/devspark.checklist` reused; Markdown + YAML only | Self-link in registry is minor redundancy (L-01) | +| §VI Platform Parity (MUST) | ✅ N/A | No new scripts added in this PR | Not applicable | +| §VII PR Review Artifact Commit Discipline (MUST) | ✅ Pass | Three clean logical commits; this review file will be committed in isolation | Commit log shows correct separation: governance memory → command templates → spec artifacts | +| §VIII Markdown Quality (MUST) | ✅ Pass | `npx markdownlint-cli2 "**/*.md"` — 0 errors, 381 files | Verified in T014; CLAUDE.md pre-existing errors also fixed | + +## Security Checklist + +- [x] No hardcoded secrets or credentials +- [x] Input validation present where needed (N/A — pure Markdown) +- [x] Authentication/authorization checks appropriate (N/A) +- [x] No SQL injection vulnerabilities (N/A) +- [x] No XSS vulnerabilities (N/A) +- [x] Dependencies reviewed for vulnerabilities (N/A — no new dependencies) + +## Testing Coverage + +**Status**: ADEQUATE + +markdownlint CI validates all Markdown files. The conformance manifest establishes a baseline for command template validation. No runtime code exists to test. + +## Test Inventory + +No test files changed in this PR (pure Markdown feature). + +## Documentation Status + +**Status**: ADEQUATE + +All new governance artifacts are self-documenting. Constitution updated with Companion Documents section. Spec artifacts (spec, plan, tasks, research, gates) are complete and committed. + +## Changed Files Summary + +| File | Tier | Changes | Type | Findings | +|------|------|---------|------|---------| +| `.documentation/memory/constitution.md` | P1 | +7 -0 | Modified | None | +| `.documentation/memory/severity-registry.md` | P1 | +85 -0 | Added | L-01 | +| `.documentation/memory/known-limitations.md` | P2 | +117 -0 | Added | None | +| `.documentation/memory/prompt-conformance-manifest.md` | P2 | +173 -0 | Added | M-01 | +| `templates/commands/pr-review.md` | P1 | +50 -0 | Modified | H-01 | +| `templates/commands/evolve-constitution.md` | P1 | +2 -0 | Modified | None | +| `.documentation/specs/001-agt-governance-improvements/spec.md` | P3 | +220 -0 | Added | None | +| `.documentation/specs/001-agt-governance-improvements/plan.md` | P3 | +250 -0 | Added | None | +| `.documentation/specs/001-agt-governance-improvements/tasks.md` | P3 | +320 -0 | Added | None | +| `.documentation/specs/001-agt-governance-improvements/research.md` | P3 | +80 -0 | Added | None | +| `.documentation/specs/001-agt-governance-improvements/checklists/requirements.md` | P3 | +50 -0 | Added | None | +| `.documentation/specs/001-agt-governance-improvements/gates/analyze.md` | P3 | +120 -0 | Added | None | +| `.documentation/specs/001-agt-governance-improvements/gates/critic.md` | P3 | +170 -0 | Added | None | + +## Behavioral Changes + +None detected — pure Markdown additions. No runtime behavior changed. + +## Shared Review Resolution Contract + +```yaml +findings: + - finding_id: H-01 + severity: high + description: > + The reviewer-alert blockquote in pr-review.md step 1b fires unconditionally + at the top level of the step, but the trust-tier YAML finding only fires for + no-compliance branches. A partial-compliance branch receives the alert without + a finding, creating an implicit behavior gap that violates §II Explicit Over Implied. + recommended_action: > + Move the '> ⚠️ No spec artifacts detected' blockquote inside the step-5 + no-compliance conditional block so it only renders alongside the YAML finding. + execution_mode: selective + status: resolved + outcome: "Fixed in 050e145: moved alert inside no-compliance conditional; added partial-compliance inline note" + + - finding_id: M-01 + severity: medium + description: > + The HTML comment block in prompt-conformance-manifest.md baseline section + contains a blank line before the closing '-->' which may confuse readers + about where the comment ends. + recommended_action: > + Remove the blank line inside the HTML comment block so '-->' immediately + follows the last content line. + execution_mode: auto + status: resolved + outcome: "Fixed in 050e145: removed blank lines inside HTML comment block" + + - finding_id: L-01 + severity: low + description: > + severity-registry.md Companion Documents section contains a self-link and + uses an absolute-style path for constitution.md link. + recommended_action: > + Remove the self-link to severity-registry.md; use relative path 'constitution.md' + instead of '.documentation/memory/constitution.md'. + execution_mode: auto + status: resolved + outcome: "Fixed in 050e145: changed to relative path constitution.md; self-link was already absent" +``` + +## Approval Decision + +**Recommendation**: ⚠️ REQUEST CHANGES + +**Reasoning**: All 3 findings resolved in fix commit 050e145. H-01 (trust-tier alert now conditionally scoped to no-compliance only with explicit partial-compliance inline note), M-01 (HTML comment blank lines removed), L-01 (relative path in severity-registry companion links). No constitution violations remain. All changes are additive Markdown with zero markdownlint errors across 381 files. + +**Estimated Rework Time**: N/A — complete + +--- + +*Review generated by devspark.pr-review v1.2* +*Constitution-driven code review for DevSpark* +*To re-review after fixes: `/devspark.pr-review #48 re-review`* +*When addressing these findings, run `/devspark.address-pr-review 48`. The review file must be committed on its own — this rule is enforced by §VII.* diff --git a/templates/commands/evolve-constitution.md b/templates/commands/evolve-constitution.md index dcb7b7e2..fab3552c 100644 --- a/templates/commands/evolve-constitution.md +++ b/templates/commands/evolve-constitution.md @@ -356,6 +356,8 @@ Select one: - [ ] Evidence justifies the change - [ ] Impact assessment is realistic - [ ] Adoption plan is achievable +- [ ] If the amendment adds, removes, or modifies a severity marker, `.documentation/memory/severity-registry.md` is updated in the same PR (FR-009) +- [ ] Check whether the amendment implies new governance limitations; if so, update `.documentation/memory/known-limitations.md` in the same PR (FR-006) ## Voting Record diff --git a/templates/commands/pr-review.md b/templates/commands/pr-review.md index e69ce05c..37f94d58 100644 --- a/templates/commands/pr-review.md +++ b/templates/commands/pr-review.md @@ -95,6 +95,40 @@ If the script fails: For single quotes in args like "I'm reviewing", use escape syntax: e.g 'I'\''m reviewing' (or double-quote if possible: "I'm reviewing"). +### 1b. Trust-Tier Classification + +Detect workflow compliance for the PR's source branch before loading the constitution: + +1. Extract `head_branch` from PR context. +2. Derive spec dir: `.documentation/specs/{head_branch}/` +3. Check file existence: + - `spec.md` present? + - `plan.md` present? + - `tasks.md` present? +4. Classify trust tier: + - All 3 present → **full-compliance** (standard review depth) + - `spec.md` only, or `spec.md` + `plan.md` → **partial-compliance** (note gap; moderate scrutiny) + - None present → **no-compliance** (elevated scrutiny; emit MEDIUM finding below) + - Branch name does not match `NNN-*` pattern → **no-compliance** (note naming convention gap) +5. For **no-compliance** branches only, emit the following finding and include the reviewer alert below. Do NOT emit this finding or alert for full-compliance or partial-compliance branches. + +```yaml +findings: + - finding_id: trust-tier-01 + severity: medium + description: "Branch has no spec artifacts under .documentation/specs/{head_branch}/. Constitution §Development Workflow requires features to be spec-driven: specify first, plan second, implement third." + recommended_action: "Run /devspark.specify to create the spec, then /devspark.plan and /devspark.tasks before merging." + execution_mode: manual + status: open + outcome: "" +``` + + > ⚠️ **No spec artifacts detected** — apply heightened attention to all findings in this + > report. The absence of a spec means requirements and acceptance criteria have not been + > formally defined; findings may undercount issues. + + For **partial-compliance** branches (spec.md present but plan.md or tasks.md missing), note the gap inline in the review output without emitting a separate finding: "Partial spec compliance detected — plan.md or tasks.md missing. Standard depth review applied." + ### 2. Load Constitution Read and parse `/.documentation/memory/constitution.md`: @@ -103,6 +137,7 @@ Read and parse `/.documentation/memory/constitution.md`: - Identify MUST requirements (non-negotiable/mandatory) - Identify SHOULD requirements (recommended) - Note constitution version and amendment date +- If `.documentation/memory/severity-registry.md` exists, load it and use its `§{section}.{LEVEL}` entries to validate finding codes when emitting findings - Build a checklist of principles to evaluate If constitution doesn't exist: @@ -738,6 +773,18 @@ Use this scenario-to-severity mapping table to anchor classification. When two t | Style / naming / docs | LOW | Optional improvement | | Constitution needs updating (not code) | CON | Governance improvement | +#### Severity Code Format + +Every finding that references a constitution principle MUST include a severity code in the +format `§{section}.{LEVEL}` matching an entry in `.documentation/memory/severity-registry.md`. + +**Examples**: `§VI.HIGH` (platform parity), `§VII.MEDIUM` (review file commit discipline), +`§VIII.HIGH` (markdownlint CI block), `§I.SHOWSTOPPER` (backward compatibility violation) + +For findings not mapped to any constitution section (e.g., security observations, code-quality +issues not covered by the constitution): emit the finding without a `§` code and flag it as +a `CON` candidate for `/devspark.evolve-constitution`. + Summary tiers: - **CRITICAL**: Violates MUST principle, blocks functionality, security risk, breaks production