import{_ as s,o as t,c as i,ag as a}from"./chunks/framework.CmQHR1bQ.js";const k=JSON.parse('{"title":"QUALITY_GATES.md — Specification Quality Criteria","description":"","frontmatter":{},"headers":[],"relativePath":"governance/QUALITY_GATES.md","filePath":"governance/QUALITY_GATES.md"}'),n={name:"governance/QUALITY_GATES.md"};function o(l,e,d,r,p,h){return t(),i("div",null,[...e[0]||(e[0]=[a(`<h1 id="quality-gates-md-—-specification-quality-criteria" tabindex="-1">QUALITY_GATES.md — Specification Quality Criteria <a class="header-anchor" href="#quality-gates-md-—-specification-quality-criteria" aria-label="Permalink to &quot;QUALITY_GATES.md — Specification Quality Criteria&quot;">​</a></h1><p><strong>Date</strong>: 2026-02-21 <strong>Status</strong>: ACTIVE <strong>Purpose</strong>: Define what makes a spec &quot;complete&quot; and &quot;correct&quot;</p><hr><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Every specification must pass five gates before being marked ACTIVE or CLOSED.</p><hr><h2 id="gate-1-completeness-checklist" tabindex="-1">Gate 1: Completeness Checklist <a class="header-anchor" href="#gate-1-completeness-checklist" aria-label="Permalink to &quot;Gate 1: Completeness Checklist&quot;">​</a></h2><p>Every spec must include:</p><ul><li>[ ] <strong>Header section</strong> (title, date, status, owner, tags)</li><li>[ ] <strong>Executive summary</strong> (1-2 sentences: what does this spec define?)</li><li>[ ] <strong>Scope</strong> (what is IN scope, what is OUT of scope)</li><li>[ ] <strong>Key concepts</strong> (domain terminology with definitions)</li><li>[ ] <strong>Data model</strong> (tables, schemas, or conceptual structures)</li><li>[ ] <strong>API/Interfaces</strong> (if applicable: request/response shapes)</li><li>[ ] <strong>Determinism contract</strong> (if applicable: side effects, external calls)</li><li>[ ] <strong>Relationships to other specs</strong> (explicit cross-references)</li><li>[ ] <strong>Open questions</strong> (if any: linked to NEXT_STEPS.md)</li><li>[ ] <strong>Success criteria</strong> (how to test/validate the spec)</li></ul><p><strong>Validation command</strong>: <code>task spec:validate</code></p><p><strong>Example PASS</strong>:</p><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># TECHNICAL_SPEC.md</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold;">**Date**</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: 2026-02-21</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold;">**Status**</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: ACTIVE</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold;">**Owner**</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: Venture Platform Team</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## Executive Summary</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Defines the control-plane architecture for the Venture agent platform...</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## Scope</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> IN: Event envelope schema, policy bundle versioning, tool allowlists</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OUT: Individual tool implementations (covered in TRACK_C_CONTROL_PLANE.md)</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## Key Concepts</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold;"> **EventEnvelopeV1**</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: Signed container for all external effects</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold;"> **PolicyBundle**</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: Versioned set of policies governing agent actions</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">...</span></span></code></pre></div><p><strong>Example FAIL</strong>:</p><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># TECHNICAL_SPEC.md</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(Missing header, scope, success criteria)</span></span></code></pre></div><hr><h2 id="gate-2-traceability-next-steps-md-→-specs" tabindex="-1">Gate 2: Traceability (NEXT_STEPS.md → Specs) <a class="header-anchor" href="#gate-2-traceability-next-steps-md-→-specs" aria-label="Permalink to &quot;Gate 2: Traceability (NEXT_STEPS.md → Specs)&quot;">​</a></h2><p>Every task in NEXT_STEPS.md must reference at least one spec section.</p><p><strong>Validation command</strong>: <code>task spec:gaps</code></p><p><strong>Example PASS</strong>:</p><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># NEXT_STEPS.md</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">#### 1. Venture Control-Plane Scaffolding</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold;">**Depends on:**</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> TECHNICAL_SPEC, TRACK_C_CONTROL_PLANE, TRACK_A_ARTIFACT_DETERMINISM_SPEC</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold;">**Concrete tasks:**</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">1.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Implement EventEnvelopeV1 (API_EVENTS_SPEC, section 2.1)</span></span></code></pre></div><p><strong>Example FAIL</strong>:</p><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># NEXT_STEPS.md</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">#### 1. Venture Control-Plane Scaffolding</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Implement some stuff. (No spec reference)</span></span></code></pre></div><hr><h2 id="gate-3-markdown-lint-0-errors" tabindex="-1">Gate 3: Markdown Lint (0 Errors) <a class="header-anchor" href="#gate-3-markdown-lint-0-errors" aria-label="Permalink to &quot;Gate 3: Markdown Lint (0 Errors)&quot;">​</a></h2><p>All markdown must conform to markdownlint rules (see quality-gate.yml).</p><p><strong>Validation command</strong>: <code>task lint:markdown</code></p><p><strong>Common violations</strong>:</p><table tabindex="0"><thead><tr><th>Error</th><th>Fix</th></tr></thead><tbody><tr><td><code>MD013: Line too long (&gt; 120 chars)</code></td><td>Wrap text; code blocks OK</td></tr><tr><td><code>MD041: First line in file should be top-level heading</code></td><td>Start file with <code># Title</code></td></tr><tr><td><code>MD025: Multiple top-level headings</code></td><td>Use <code>##</code> for sections, not <code>#</code></td></tr><tr><td><code>MD034: Bare URLs</code></td><td>Use markdown links: <code>[Title](URL)</code></td></tr><tr><td><code>MD031: Fenced code blocks should be surrounded by blank lines</code></td><td>Add blank line before/after <code>\`\`\`</code></td></tr></tbody></table><hr><h2 id="gate-4-link-validity-0-broken-links" tabindex="-1">Gate 4: Link Validity (0 Broken Links) <a class="header-anchor" href="#gate-4-link-validity-0-broken-links" aria-label="Permalink to &quot;Gate 4: Link Validity (0 Broken Links)&quot;">​</a></h2><p>All references to specs, sections, and files must be resolvable.</p><p><strong>Validation command</strong>: <code>task spec:index</code></p><p><strong>Examples</strong>:</p><table tabindex="0"><thead><tr><th>Good</th><th>Bad</th></tr></thead><tbody><tr><td><code>See TRACK_C_CONTROL_PLANE.md (section 2.3)</code></td><td><code>See the control plane spec</code></td></tr><tr><td><code>[Policy bundle](TECHNICAL_SPEC.md#policy-bundle)</code></td><td><code>[Policy bundle](TECHNICAL_SPEC.md)</code></td></tr><tr><td><code>Link to NEXT_STEPS.md task 1</code></td><td><code>Link to the roadmap somewhere</code></td></tr></tbody></table><p><strong>Note</strong>: Internal links use markdown anchor format: <code>[Text](FILE.md#anchor-id)</code>. Anchors are generated from heading text (lowercase, spaces → hyphens).</p><hr><h2 id="gate-5-open-questions-assigned" tabindex="-1">Gate 5: Open Questions Assigned <a class="header-anchor" href="#gate-5-open-questions-assigned" aria-label="Permalink to &quot;Gate 5: Open Questions Assigned&quot;">​</a></h2><p>Every unresolved question must have:</p><ol><li><strong>Owner</strong> (name or team)</li><li><strong>Due date</strong> (YYYY-MM-DD)</li><li><strong>Status</strong> (OPEN | RESOLVED | ESCALATED)</li></ol><p><strong>Location</strong>: NEXT_STEPS.md &quot;Unresolved Open Questions&quot; section</p><p><strong>Validation</strong>: Manual review (not automated)</p><p><strong>Example PASS</strong>:</p><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## Unresolved Open Questions</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">#### Q1. Artifact Determinism for Non-Deterministic Providers</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold;">**Owner:**</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Venture Artifact Team</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold;">**Due:**</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> 2026-02-28</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold;">**Status:**</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OPEN</span></span></code></pre></div><p><strong>Example FAIL</strong>:</p><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## Unresolved Open Questions</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">#### Q1. How do we handle non-determinism?</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(No owner, no due date)</span></span></code></pre></div><hr><h2 id="spec-to-implementation-traceability" tabindex="-1">Spec-to-Implementation Traceability <a class="header-anchor" href="#spec-to-implementation-traceability" aria-label="Permalink to &quot;Spec-to-Implementation Traceability&quot;">​</a></h2><p>When implementing a spec:</p><ol><li><strong>Claim the task</strong> in WORK_STREAM.md: <code>status: CLAIMED | owner: @you</code></li><li><strong>Reference the spec section</strong> in commit message or code comment</li><li><strong>Mark complete</strong>: <code>status: COMPLETED | completed: YYYY-MM-DD</code></li></ol><p><strong>Format</strong>:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>git commit -m &quot;Implement EventEnvelopeV1 validation</span></span>
<span class="line"><span></span></span>
<span class="line"><span>- API_EVENTS_SPEC.md, section 2.1</span></span>
<span class="line"><span>- Validates event_id, event_type, trace_id, workflow_id, task_id, payload, created_at</span></span>
<span class="line"><span>- Property tests for schema conformance</span></span>
<span class="line"><span></span></span>
<span class="line"><span>Closes: WORK_STREAM.md | venture-p0-task-1&quot;</span></span></code></pre></div><hr><h2 id="revision-workflow" tabindex="-1">Revision Workflow <a class="header-anchor" href="#revision-workflow" aria-label="Permalink to &quot;Revision Workflow&quot;">​</a></h2><h3 id="minor-updates-typo-clarification" tabindex="-1">Minor Updates (typo, clarification) <a class="header-anchor" href="#minor-updates-typo-clarification" aria-label="Permalink to &quot;Minor Updates (typo, clarification)&quot;">​</a></h3><ol><li>Edit spec directly</li><li>Update <code>**Date**: YYYY-MM-DD</code> field</li><li>Run <code>task quality</code> to verify no regressions</li><li>Commit: <code>fix: [spec-name] — [brief description]</code></li></ol><h3 id="major-updates-api-change-redesign" tabindex="-1">Major Updates (API change, redesign) <a class="header-anchor" href="#major-updates-api-change-redesign" aria-label="Permalink to &quot;Major Updates (API change, redesign)&quot;">​</a></h3><ol><li>Change <code>**Status**: DRAFT</code></li><li>Record decision rationale in <code>docs/adr/ADR-NNN-[slug].md</code></li><li>Update all cross-references in dependent specs</li><li>Run <code>task quality</code> to verify traceability</li><li>Change <code>**Status**: ACTIVE</code> when ready</li><li>Commit: <code>update: [spec-name] for [reason]</code></li></ol><h3 id="spec-retirement" tabindex="-1">Spec Retirement <a class="header-anchor" href="#spec-retirement" aria-label="Permalink to &quot;Spec Retirement&quot;">​</a></h3><ol><li>Change <code>**Status**: ARCHIVED</code></li><li>Add note: <code>Superseded by [NEW_SPEC.md] as of YYYY-MM-DD</code></li><li>Update all cross-references to point to new spec</li><li>Do NOT delete file (keep for historical reference)</li></ol><hr><h2 id="common-spec-pitfalls" tabindex="-1">Common Spec Pitfalls <a class="header-anchor" href="#common-spec-pitfalls" aria-label="Permalink to &quot;Common Spec Pitfalls&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Pitfall</th><th>Fix</th></tr></thead><tbody><tr><td>Spec describes implementation details</td><td>Move to docs/guides/ or code comments; spec should describe contract only</td></tr><tr><td>Circular dependencies between specs</td><td>Break cycle: make one spec depend on abstract interface defined elsewhere</td></tr><tr><td>&quot;TBD&quot; or &quot;TK&quot; sections left in</td><td>Move to NEXT_STEPS.md &quot;Open Questions&quot;; mark spec as DRAFT</td></tr><tr><td>Handwave requirements (&quot;obviously&quot;, &quot;clearly&quot;)</td><td>Define explicitly with examples; add to NEXT_STEPS.md if unclear</td></tr><tr><td>Copy-pasted text from other specs</td><td>Link instead: &quot;See X, section Y.Z for definition&quot;</td></tr><tr><td>No success criteria</td><td>Define how to test/validate: &quot;Pass if X test succeeds&quot;</td></tr></tbody></table><hr><h2 id="success-metrics" tabindex="-1">Success Metrics <a class="header-anchor" href="#success-metrics" aria-label="Permalink to &quot;Success Metrics&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Metric</th><th>Target</th><th>Validation</th></tr></thead><tbody><tr><td>Spec completeness</td><td>100% (all 8 gates per spec)</td><td><code>task spec:validate</code></td></tr><tr><td>Coverage (NEXT_STEPS → specs)</td><td>100% (every task traced)</td><td><code>task spec:gaps</code></td></tr><tr><td>Markdown lint</td><td>0 errors</td><td><code>task lint:markdown</code></td></tr><tr><td>Broken links</td><td>0</td><td><code>task spec:index</code></td></tr><tr><td>Open questions assigned</td><td>100%</td><td>Manual review NEXT_STEPS.md</td></tr></tbody></table><hr><h2 id="quick-reference-full-validation" tabindex="-1">Quick Reference: Full Validation <a class="header-anchor" href="#quick-reference-full-validation" aria-label="Permalink to &quot;Quick Reference: Full Validation&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Check everything</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">task</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> quality</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Outputs:</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># - spec:validate failures (missing required sections)</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># - spec:gaps failures (untraced requirements)</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># - lint:markdown failures (style/format issues)</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># - spec:index failures (broken links)</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># - gate output (summary)</span></span></code></pre></div><p>If all pass: specs are ready for implementation in sibling projects.</p>`,69)])])}const g=s(n,[["render",o]]);export{k as __pageData,g as default};
