cleargate 0.8.1 → 0.10.0

package/templates/cleargate-planning/.cleargate/knowledge/readiness-gates.md

@@ -70,6 +70,12 @@ The asymmetry exists because Proposal documents are human-authored strategy arti
       check: "section(4) has ≥1 listed-item"
     - id: interrogation-resolved
       check: "body does not contain 'Unresolved'"
+    - id: discovery-checked
+      check: "frontmatter(.).context_source != null"
+    - id: reuse-audit-recorded
+      check: "body contains '## Existing Surfaces'"
+    - id: simplest-form-justified
+      check: "body contains '## Why not simpler?'"
 ```
 
 ```yaml
@@ -87,6 +93,8 @@ The asymmetry exists because Proposal documents are human-authored strategy arti
       check: "body does not contain marker 'TBD'"
     - id: interrogation-resolved
       check: "body does not contain 'Unresolved'"
+    - id: discovery-checked
+      check: "frontmatter(.).context_source != null"
 ```
 
 ```yaml
@@ -104,6 +112,12 @@ The asymmetry exists because Proposal documents are human-authored strategy arti
       check: "section(4) has ≥1 listed-item"
     - id: gherkin-present
       check: "body contains 'Scenario:'"
+    - id: discovery-checked
+      check: "frontmatter(.).context_source != null"
+    - id: reuse-audit-recorded
+      check: "body contains '## Existing Surfaces'"
+    - id: simplest-form-justified
+      check: "body contains '## Why not simpler?'"
 ```
 
 ```yaml
@@ -117,6 +131,10 @@ The asymmetry exists because Proposal documents are human-authored strategy arti
       check: "body does not contain marker 'TBD'"
     - id: sandbox-paths-declared
       check: "section(2) has ≥1 listed-item"
+    - id: discovery-checked
+      check: "frontmatter(.).context_source != null"
+    - id: reuse-audit-recorded
+      check: "body contains '## Existing Surfaces'"
 ```
 
 ```yaml
@@ -130,4 +148,17 @@ The asymmetry exists because Proposal documents are human-authored strategy arti
       check: "frontmatter(.).severity != null"
     - id: no-tbds
       check: "body does not contain marker 'TBD'"
+    - id: discovery-checked
+      check: "frontmatter(.).context_source != null"
+```
+
+```yaml
+- work_item_type: sprint
+  transition: ready-for-execution
+  severity: enforcing
+  criteria:
+    - id: risk-table-populated
+      check: "body contains '| Mitigation'"
+    - id: discovery-checked
+      check: "frontmatter(.).context_source != null"
 ```

package/templates/cleargate-planning/.cleargate/knowledge/sprint-closeout-checklist.md

@@ -0,0 +1,71 @@
+# Sprint Closeout Doc & Metadata Refresh Checklist
+
+> Read at sprint close (Gate 4 ack). Each item names a surface that may need
+> updating based on what shipped this sprint. Trigger conditions tell you when
+> review is required vs when the surface can be skipped.
+>
+> Use `node .cleargate/scripts/prep_doc_refresh.mjs <sprint-id>` to generate
+> a per-sprint tailored checklist that pre-checks items based on actual
+> changed files in the sprint window.
+
+### 1. Project READMEs
+| Surface | Trigger condition |
+|---|---|
+| `README.md` | Any feature shipped that changes user-visible product behavior |
+| `cleargate-cli/README.md` | Any change to `cleargate-cli/src/commands/*.ts` |
+| `cleargate-planning/README.md` | Any change under `cleargate-planning/` |
+| `mcp/README.md` | Any change under `mcp/src/` (note: nested repo; check separately) |
+| `admin/README.md` | Any change under `admin/` (currently stub) |
+
+### 2. CHANGELOG files (Common-Changelog format per STORY-016-03)
+| Surface | Trigger condition |
+|---|---|
+| `cleargate-cli/CHANGELOG.md` | Any user-visible change in `cleargate-cli/` (CLI surface, error messages, package contents) |
+| `mcp/CHANGELOG.md` | Any user-visible change in `mcp/` (if file exists) |
+
+### 3. Manifest / package metadata
+| Surface | Trigger condition |
+|---|---|
+| `cleargate-planning/MANIFEST.json` | Any change to `.claude/agents/*.md`, `.cleargate/templates/*`, `.cleargate/knowledge/*`, or `.cleargate/scripts/*`. Run `cleargate doctor` to verify scaffold registry. |
+| `cleargate-cli/package.json` | Version bump only if releasing this sprint (release lane is separate from sprint close) |
+| `mcp/package.json` | Version bump only if releasing this sprint |
+
+### 4. CLAUDE.md "Active state" subsection
+| Surface | Trigger condition |
+|---|---|
+| `CLAUDE.md` lines containing "Active state (as of YYYY-MM-DD)" | Any EPIC / CR / Bug / Hotfix archived this sprint, OR any stack version bumped |
+| `cleargate-planning/CLAUDE.md` mirror | Same edit as live (CLEARGATE-tag-block region only — outside-block diverges intentionally) |
+
+### 5. Wiki surfaces (auto-rebuilt by PostToolUse hooks; verify after close)
+| Surface | Verify by |
+|---|---|
+| `.cleargate/wiki/active-sprint.md` | Read top of file; confirm sprint ID, status, and date are current |
+| `.cleargate/wiki/index.md` | Read; confirm new artifacts (epics, stories, CRs) appear in the relevant sections |
+| `.cleargate/wiki/product-state.md` | Read; confirm shipped capabilities are listed |
+| `.cleargate/wiki/roadmap.md` | Read; confirm closed sprint moved from Active to Completed section |
+
+### 6. INDEX surfaces (manual updates)
+| Surface | Trigger condition |
+|---|---|
+| `.cleargate/INDEX.md` | If maintained as a curated roadmap; update when sprint closes |
+| `.cleargate/delivery/INDEX.md` | Update epic/sprint map when new artifacts archived |
+
+### 7. Frontmatter version stamps
+| Surface | Action |
+|---|---|
+| Any `.cleargate/templates/*.md` modified this sprint | Run `cleargate stamp <path>` to bump `updated_at_version` |
+| `.cleargate/knowledge/cleargate-protocol.md` (post-EPIC-024 slim) | Same |
+| `.cleargate/knowledge/cleargate-enforcement.md` (post-EPIC-024 split) | Same |
+| Any other `.cleargate/knowledge/*.md` modified | Same |
+
+### 8. Knowledge doc cross-references
+| Surface | Action |
+|---|---|
+| Any knowledge doc that cites `§N` of protocol or enforcement.md | Verify post-rewrite resolution still works (covered for SPRINT-17 specifically by STORY-024-02; revisit if any future § reorganization happens) |
+
+### 9. Mirror parity audit
+| Surface | Action |
+|---|---|
+| `cleargate-planning/.claude/` | `diff -r .claude/agents/ cleargate-planning/.claude/agents/` empty (excluding skills/ flashcards/, hooks/, settings.json which differ intentionally) |
+| `cleargate-planning/.cleargate/templates/` | `diff -r .cleargate/templates/ cleargate-planning/.cleargate/templates/` empty |
+| `cleargate-planning/.cleargate/knowledge/` | `diff -r .cleargate/knowledge/ cleargate-planning/.cleargate/knowledge/` empty |

package/templates/cleargate-planning/.cleargate/scripts/assert_story_files.mjs

@@ -71,7 +71,7 @@ function extractDeliverablesSection(content) {
  *
  * STORY before CR/BUG/EPIC/HOTFIX, PROPOSAL before PROP — BUG-010 longest-first rule.
  */
-function extractWorkItemIds(text) {
+export function extractWorkItemIds(text) {
   const re = /(STORY-\d+-\d+|(CR|BUG|EPIC|HOTFIX)-\d+|(PROPOSAL|PROP)-\d+)/g;
   const raw = [];
   let m;
@@ -87,7 +87,7 @@ function extractWorkItemIds(text) {
  * Check whether pending-sync OR archive contains a file matching <ID>_*.md
  * Returns the matching absolute path or null.
  */
-function findWorkItemFile(repoRoot, workItemId) {
+export function findWorkItemFile(repoRoot, workItemId) {
   const searchDirs = [
     path.join(repoRoot, '.cleargate', 'delivery', 'pending-sync'),
     path.join(repoRoot, '.cleargate', 'delivery', 'archive'),
@@ -207,6 +207,28 @@ function main() {
 
   const sprintFilePath = path.resolve(args[0]);
 
+  // CR-027: --emit-json flag — extract work-item IDs and print JSON to stdout.
+  // Used by sprint.ts checkPerItemReadinessGates (path-a shell-out protocol).
+  // When this flag is present, skip the file-presence/approval triage and exit 0.
+  if (args.includes('--emit-json')) {
+    let content;
+    try {
+      content = fs.readFileSync(sprintFilePath, 'utf8');
+    } catch (err) {
+      process.stderr.write(`Error: cannot read sprint file: ${err.message}\n`);
+      process.exit(2);
+    }
+    const section = extractDeliverablesSection(content);
+    if (section === null) {
+      // No §1 section found — emit empty list (not an error for this flag)
+      process.stdout.write(JSON.stringify({ workItemIds: [] }) + '\n');
+      process.exit(0);
+    }
+    const workItemIds = extractWorkItemIds(section);
+    process.stdout.write(JSON.stringify({ workItemIds }) + '\n');
+    process.exit(0);
+  }
+
   // Allow test-isolation override of execution_mode
   const execMode = process.env.CLEARGATE_EXEC_MODE ?? 'v2';