@bytesbrains/pi-project-gate 1.2.1

package/AGENTS.md

@@ -0,0 +1,159 @@
+# Project Gate — Agent Usage Guide
+
+> You are an AI agent. Use project-gate tools to manage issues, validate work readiness, and track progress.
+
+## Golden Rules
+
+> **⚠️ DO NOT start work on an issue without calling `project_check()` first.**
+> This ensures the issue has required sections, no blockers, and you haven't exceeded WIP limits.
+
+> **📝 Use `project_create_issue()` to create issues — never use raw `curl` or the browser.**
+> This ensures issue templates are validated and governance gates are enforced.
+
+## Workflow
+
+```
+project_check(issue_id="42")     ← validate: template? deps resolved? not taken?
+  │
+  ▼
+project_start(issue_id="42")     ← WIP check, dep check, mark started
+  │
+  ▼
+contrib_start_work(issue_id="42") ← create branch
+  │
+  ▼
+[implement + test]
+  │
+  ▼
+contrib_propose(message="...")   ← validate + commit
+  │
+  ▼
+contrib_submit(title="...")      ← push + PR
+  │
+  ▼
+[CI + review gates pass → merged]
+  │
+  ▼
+project_status()                  ← verify WIP freed, blockers clear
+```
+
+## Issue Template Requirements
+
+Issues MUST have these sections (configurable in `.projectrc.yml`):
+
+```markdown
+## Problem
+What is the problem we're solving?
+
+## Proposed Solution
+How should we solve it?
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+Complexity: medium
+Area: backend
+Depends on #41
+```
+
+The `project_check()` tool validates these sections exist. If missing, it blocks work start.
+
+## WIP Limits
+
+Default: max 3 open PRs per agent. Configured via `maxWip` in `.projectrc.yml`.
+
+If you have 3 open PRs, `project_start()` will refuse to start new work.
+
+## Dependency Blocking
+
+Issues can declare dependencies using:
+
+```
+Depends on #123
+Blocked by #456
+Requires #789
+```
+
+If any dependency is still open, `project_start()` blocks work.
+
+## Managing Issues (CRUD)
+
+### Create an Issue
+
+Always use `project_create_issue()` instead of raw curl or browser:
+
+```
+project_create_issue(
+  title="Add dark mode toggle",
+  body="## Problem\nNo dark mode support.\n\n## Proposed Solution\nAdd a toggle in settings.\n\n## Acceptance Criteria\n- [ ] Toggle switches themes\n- [ ] Persists preference",
+  labels=["enhancement", "frontend"],
+  milestone="v2.0"
+)
+```
+
+The body is validated against required sections (configurable in `.projectrc.yml`).
+
+### Update an Issue
+
+Modify any aspect of an existing issue:
+
+```
+project_update_issue(
+  issue_id="42",
+  state="closed"
+)
+
+project_update_issue(
+  issue_id="42",
+  title="Updated title",
+  labels=["bug", "high-priority"],
+  assignee="nandal"
+)
+```
+
+Only the fields you provide are changed. Omitted fields are left as-is.
+
+### List/Search Issues
+
+Find issues with flexible filters:
+
+```
+project_list_issues()                              ← all open issues
+project_list_issues(state="closed")                ← closed issues
+project_list_issues(labels="bug,high-priority")    ← by labels
+project_list_issues(milestone="v2.0")              ← by milestone
+project_list_issues(assignee="nandal")             ← by assignee
+project_list_issues(q="dark mode")                 ← text search
+project_list_issues(state="open", limit=50)        ← pagination
+```
+
+### Get Issue Details
+
+Fetch full issue info including comments:
+
+```
+project_get_issue(issue_id="42")                   ← full details + comments
+project_get_issue(issue_id="42", include_comments=false)  ← body only
+```
+
+## Release Notes
+
+Generate release notes from conventional commits:
+
+```
+project_release_notes()                        ← latest tag to HEAD
+project_release_notes(from="v1.0.0")           ← specific tag to HEAD
+project_release_notes(from="v1.0.0", to="v1.1.0") ← between two tags
+```
+
+## When Things Go Wrong
+
+| Problem | Solution |
+|---|---|
+| Issue missing sections | Add required sections to the issue body, or use `project_update_issue()` |
+| WIP limit reached | Close or merge an existing PR first |
+| Blocked by dependency | Help resolve the blocking issue or wait for it to be merged |
+| No complexity label | Add `Complexity: small/medium/large/epic` to issue body |
+| Cannot find an issue | Use `project_list_issues(q="keyword")` to search |
+| Need to close an issue | Use `project_update_issue(issue_id="42", state="closed")` |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nandal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# Project Gate for Pi
+
+[![npm version](https://img.shields.io/npm/v/pi-project-gate)](https://www.npmjs.com/package/pi-project-gate)
+[![license](https://img.shields.io/npm/l/pi-project-gate)](./LICENSE)
+
+> Project orchestration gate for AI agents — structured issues, WIP limits, dependency blocking, and auto-generated release notes. **Agents work from issues, not vibes.**
+
+## Philosophy
+
+`pi-contrib-gate` handles the *contribution* side (branch → commit → PR).  
+`pi-review-gate` handles the *review* side (check → approve → merge).  
+`pi-project-gate` handles the *project* side (issue → plan → release).
+
+## Install
+
+```bash
+pi install npm:pi-project-gate
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `project_check(issue_id)` | Validate issue readiness — template, complexity, dependencies |
+| `project_start(issue_id)` | Start work on an issue — checks WIP, dependencies, template |
+| `project_status()` | Project board — active issues, WIP counts, blockers |
+| `project_release_notes(from, to)` | Generate release notes from conventional commits |
+
+## Gates
+
+| Gate | Config | Description |
+|---|---|---|
+| Issue template | `requiredSections` | Block work start if issue is missing required sections |
+| WIP limit | `maxWip` | Max concurrent open PRs per agent (default: 3) |
+| Dependency blocking | `dependencyPattern` | Prevent starting issues with unresolved dependencies |
+| Complexity tracking | `complexityLevels` | Ensure issues are scoped with complexity labels |
+| Release notes | `releaseNoteGroups` | Auto-generate grouped release notes from conventional commits |
+
+## Configuration
+
+Create `.projectrc.yml`:
+
+```yaml
+# Max open PRs per agent
+maxWip: 3
+
+# Required sections in issue body (comma-separated)
+requiredSections: "## Problem,## Proposed Solution,## Acceptance Criteria"
+
+# Complexity levels
+complexityLevels: trivial,small,medium,large,epic
+
+# Area labels for categorization
+areas: backend,frontend,infra,docs,tooling
+
+# Grouping order for release notes
+releaseNoteGroups: feat,fix,perf,refactor,chore,docs,test,ci,build
+
+# Include commit hashes in release notes
+releaseNoteIncludeHashes: false
+
+# Regex pattern for issue dependencies
+dependencyPattern: "(?:Depends on|Blocked by|Requires)\\s+#(\\d+)"
+```
+
+## Workflow
+
+```
+project_check(#42)               ← validate issue readiness
+  │
+  ▼
+project_start(#42)               ← start work (WIP + deps checked)
+  │
+  ▼
+contrib_start_work(#42)          ← create branch
+  │
+  ▼
+[implement]
+  │
+  ▼
+contrib_propose(...)             ← validate + commit
+  │
+  ▼
+contrib_submit(...)              ← push + create PR
+  │
+  ▼
+[CI + review gates pass]
+  │
+  ▼
+MERGED → project_status()        ← WIP freed, blockers resolved
+```
+
+## Release Notes
+
+```bash
+# Generate notes from last tag to HEAD
+project_release_notes()
+
+# Generate notes between two tags
+project_release_notes(from="v1.0.0", to="v1.1.0")
+```
+
+Example output:
+
+```
+# Release v1.1.0 (2026-05-14)
+
+### 🚀 Features
+- **auth**: add OAuth2 support
+- **api**: new user endpoint
+
+### 🐛 Bug Fixes
+- fix null pointer in login flow
+- fix race condition in task queue
+
+### 🔧 Chores
+- update dependencies
+```
+
+## Integration
+
+Install all three gates for full agent governance:
+
+```bash
+pi install npm:pi-contrib-gate
+pi install npm:pi-review-gate
+pi install npm:pi-project-gate
+```
+
+## License
+
+MIT © [nandal](https://github.com/nandal)

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@bytesbrains/pi-project-gate",
+  "version": "1.2.1",
+  "description": "Project orchestration gate for AI agents \u2014 structured issues, WIP limits, dependency blocking, and auto-generated release notes.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "governance",
+    "project-management",
+    "release-notes",
+    "issue-tracking"
+  ],
+  "author": "nandal <nandal@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nandal/pi-ext",
+    "directory": "project-gate"
+  },
+  "homepage": "https://github.com/nandal/pi-ext/tree/main/project-gate",
+  "bugs": {
+    "url": "https://github.com/nandal/pi-ext/issues"
+  },
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.9"
+  }
+}

package/src/__tests__/project-gate.test.ts

@@ -0,0 +1,300 @@
+import { describe, it, expect } from "vitest";
+import { loadConfig, DEFAULT_CONFIG } from "../config";
+import { validateIssueTemplate, parseDependencies, parseConventionalCommits } from "../validate";
+import { exec } from "../helpers";
+import { createTool, updateTool, listTool, getTool } from "../tools/issues";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+// ═══════════════════════════════════════
+// Config
+// ═══════════════════════════════════════
+describe("ProjectConfig", () => {
+  it("returns defaults when no config", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "project-test-"));
+    const config = loadConfig(tmp);
+    expect(config.maxWip).toBe(3);
+    expect(config.requiredSections).toContain("## Problem");
+    expect(config.requiredSections).toContain("## Proposed Solution");
+    expect(config.requiredSections).toContain("## Acceptance Criteria");
+    expect(config.complexityLevels).toContain("medium");
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("parses projectrc.yml", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "project-test-"));
+    fs.writeFileSync(path.join(tmp, ".projectrc.yml"), [
+      "maxWip: 5",
+      'requiredSections: "## Problem,## Solution"',
+      'areas: "backend,frontend,infra"',
+      "releaseNoteIncludeHashes: true",
+    ].join("\n"));
+    const config = loadConfig(tmp);
+    expect(config.maxWip).toBe(5);
+    expect(config.requiredSections).toEqual(["## Problem", "## Solution"]);
+    expect(config.areas).toEqual(["backend", "frontend", "infra"]);
+    expect(config.releaseNoteIncludeHashes).toBe(true);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+});
+
+// ═══════════════════════════════════════
+// Issue template validation
+// ═══════════════════════════════════════
+describe("validateIssueTemplate", () => {
+  const config = {
+    ...DEFAULT_CONFIG,
+    requiredSections: ["## Problem", "## Proposed Solution", "## Acceptance Criteria"],
+  };
+
+  it("passes a complete template", () => {
+    const body = "## Problem\nSomething is broken\n\n## Proposed Solution\nFix it\n\n## Acceptance Criteria\n- [ ] Tests pass";
+    expect(validateIssueTemplate(body, config).ok).toBe(true);
+  });
+
+  it("fails when missing a section", () => {
+    const body = "## Problem\nSomething is broken\n\n## Proposed Solution\nFix it";
+    const result = validateIssueTemplate(body, config);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.missingSections).toContain("## Acceptance Criteria");
+    }
+  });
+
+  it("fails when all sections missing", () => {
+    const body = "Just a description with no sections";
+    const result = validateIssueTemplate(body, config);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.missingSections.length).toBe(3);
+    }
+  });
+
+  it("passes with custom required sections", () => {
+    const customConfig = { ...config, requiredSections: ["## Description"] };
+    expect(validateIssueTemplate("## Description\nSome text", customConfig).ok).toBe(true);
+  });
+});
+
+// ═══════════════════════════════════════
+// Dependency parsing
+// ═══════════════════════════════════════
+describe("parseDependencies", () => {
+  const config = {
+    ...DEFAULT_CONFIG,
+    dependencyPattern: "(?:Depends on|Blocked by|Requires)\\s+#(\\d+)",
+  };
+
+  it("parses Depends on", () => {
+    const deps = parseDependencies("Depends on #42", config);
+    expect(deps).toEqual(["42"]);
+  });
+
+  it("parses Blocked by", () => {
+    const deps = parseDependencies("Blocked by #123", config);
+    expect(deps).toEqual(["123"]);
+  });
+
+  it("parses Requires", () => {
+    const deps = parseDependencies("Requires #789", config);
+    expect(deps).toEqual(["789"]);
+  });
+
+  it("parses multiple dependencies", () => {
+    const deps = parseDependencies("Depends on #42 and Blocked by #123", config);
+    expect(deps).toContain("42");
+    expect(deps).toContain("123");
+    expect(deps.length).toBe(2);
+  });
+
+  it("returns empty for no dependencies", () => {
+    expect(parseDependencies("No dependencies here", config)).toEqual([]);
+  });
+
+  it("is case insensitive", () => {
+    const deps = parseDependencies("depends on #42 and blocked by #99", config);
+    expect(deps).toContain("42");
+    expect(deps).toContain("99");
+  });
+
+  it("deduplicates", () => {
+    const deps = parseDependencies("Depends on #42 and Depends on #42", config);
+    expect(deps).toEqual(["42"]);
+  });
+});
+
+// ═══════════════════════════════════════
+// Conventional commit parsing
+// ═══════════════════════════════════════
+describe("parseConventionalCommits", () => {
+  it("parses feat commits", () => {
+    const log = "commit abc12345\nfeat(api): add new endpoint\n---";
+    const commits = parseConventionalCommits(log);
+    expect(commits.length).toBe(1);
+    expect(commits[0].type).toBe("feat");
+    expect(commits[0].scope).toBe("api");
+    expect(commits[0].subject).toBe("add new endpoint");
+    expect(commits[0].hash).toBe("abc12345");
+  });
+
+  it("parses fix commits without scope", () => {
+    const log = "commit def67890\nfix: resolve null pointer\n---";
+    const commits = parseConventionalCommits(log);
+    expect(commits.length).toBe(1);
+    expect(commits[0].type).toBe("fix");
+    expect(commits[0].scope).toBe("");
+    expect(commits[0].subject).toBe("resolve null pointer");
+  });
+
+  it("skips non-conventional commits", () => {
+    const log = "commit ghi11111\nUpdated some stuff\n---";
+    const commits = parseConventionalCommits(log);
+    expect(commits.length).toBe(0);
+  });
+
+  it("parses multiple commits", () => {
+    const log = "commit aaa11111\nfeat: first feature\n---\n\ncommit bbb22222\nfix: bug fix\n---";
+    const commits = parseConventionalCommits(log);
+    expect(commits.length).toBe(2);
+    expect(commits[0].type).toBe("feat");
+    expect(commits[1].type).toBe("fix");
+  });
+
+  it("handles chore and refactor types", () => {
+    const log = "commit ccc33333\nchore(deps): update packages\n---\n\ncommit ddd44444\nrefactor: clean up\n---";
+    const commits = parseConventionalCommits(log);
+    expect(commits.length).toBe(2);
+    expect(commits[0].type).toBe("chore");
+    expect(commits[1].type).toBe("refactor");
+  });
+});
+
+// ═══════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════
+describe("exec helper", () => {
+  it("returns ok for valid command", () => {
+    const r = exec("echo project-test");
+    expect(r.ok).toBe(true);
+    expect(r.stdout).toBe("project-test");
+  });
+
+  it("returns not ok for invalid command", () => {
+    const r = exec("nonexistent-cmd-xyz-999 2>/dev/null");
+    expect(r.ok).toBe(false);
+  });
+});
+
+// ═══════════════════════════════════════
+// New config fields for issue CRUD
+// ═══════════════════════════════════════
+describe("issue config defaults", () => {
+  it("has default issue labels", () => {
+    expect(DEFAULT_CONFIG.issueLabels).toContain("enhancement");
+    expect(DEFAULT_CONFIG.issueLabels).toContain("bug");
+    expect(DEFAULT_CONFIG.issueLabels).toContain("documentation");
+    expect(DEFAULT_CONFIG.issueLabels).toContain("question");
+  });
+
+  it("has create flags defaulting to false", () => {
+    expect(DEFAULT_CONFIG.issueCreateRequireComplexity).toBe(false);
+    expect(DEFAULT_CONFIG.issueCreateRequireArea).toBe(false);
+  });
+
+  it("parses issueLabels from projectrc.yml", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "project-test-"));
+    fs.writeFileSync(path.join(tmp, ".projectrc.yml"), [
+      'issueLabels: "enhancement,bug,frontend,backend"',
+    ].join("\n"));
+    const config = loadConfig(tmp);
+    expect(config.issueLabels).toEqual(["enhancement", "bug", "frontend", "backend"]);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("parses issueCreateRequire flags", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "project-test-"));
+    fs.writeFileSync(path.join(tmp, ".projectrc.yml"), [
+      "issueCreateRequireComplexity: true",
+      "issueCreateRequireArea: true",
+    ].join("\n"));
+    const config = loadConfig(tmp);
+    expect(config.issueCreateRequireComplexity).toBe(true);
+    expect(config.issueCreateRequireArea).toBe(true);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+});
+
+// ═══════════════════════════════════════
+// Tool definitions
+// ═══════════════════════════════════════
+describe("issue CRUD tool definitions", () => {
+  it("createTool has proper metadata", () => {
+    expect(createTool.name).toBe("project_create_issue");
+    expect(createTool.label).toBe("Create Issue");
+    expect(createTool.description).toContain("Create a new issue");
+    expect(createTool.parameters).toBeDefined();
+  });
+
+  it("updateTool has proper metadata", () => {
+    expect(updateTool.name).toBe("project_update_issue");
+    expect(updateTool.label).toBe("Update Issue");
+    expect(updateTool.description).toContain("Update an existing issue");
+    // issue_id is required, all other fields optional
+    const props = (updateTool.parameters as any)?.properties;
+    expect(props["issue_id"]).toBeDefined();
+    expect(props["title"]).toBeDefined();
+    expect(props["body"]).toBeDefined();
+    expect(props["state"]).toBeDefined();
+    expect(props["labels"]).toBeDefined();
+    expect(props["milestone"]).toBeDefined();
+    expect(props["assignee"]).toBeDefined();
+  });
+
+  it("listTool has proper metadata", () => {
+    expect(listTool.name).toBe("project_list_issues");
+    expect(listTool.label).toBe("List Issues");
+    expect(listTool.description).toContain("Search and list issues");
+    const props = (listTool.parameters as any)?.properties;
+    expect(props["state"]).toBeDefined();
+    expect(props["labels"]).toBeDefined();
+    expect(props["milestone"]).toBeDefined();
+    expect(props["assignee"]).toBeDefined();
+    expect(props["q"]).toBeDefined();
+    expect(props["limit"]).toBeDefined();
+    expect(props["page"]).toBeDefined();
+  });
+
+  it("getTool has proper metadata", () => {
+    expect(getTool.name).toBe("project_get_issue");
+    expect(getTool.label).toBe("Get Issue");
+    expect(getTool.description).toContain("full details");
+    const props = (getTool.parameters as any)?.properties;
+    expect(props["issue_id"]).toBeDefined();
+    expect(props["include_comments"]).toBeDefined();
+  });
+});
+
+// ═══════════════════════════════════════
+// Issue body validation (reused by create/update)
+// ═══════════════════════════════════════
+describe("issue create body validation", () => {
+  const config = {
+    ...DEFAULT_CONFIG,
+    requiredSections: ["## Problem", "## Proposed Solution", "## Acceptance Criteria"],
+  };
+
+  it("accepts a well-formed issue body", () => {
+    const body = "## Problem\nBug exists\n\n## Proposed Solution\nFix it\n\n## Acceptance Criteria\n- [ ] Done";
+    expect(validateIssueTemplate(body, config).ok).toBe(true);
+  });
+
+  it("rejects body missing required sections", () => {
+    const body = "## Problem\nBug exists";
+    const result = validateIssueTemplate(body, config);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.missingSections.length).toBeGreaterThan(0);
+    }
+  });
+});

package/src/config.ts

@@ -0,0 +1,57 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface ProjectConfig {
+  maxWip: number;
+  requiredSections: string[];
+  complexityLevels: string[];
+  areas: string[];
+  issueLabels: string[];
+  issueCreateRequireComplexity: boolean;
+  issueCreateRequireArea: boolean;
+  releaseNoteGroups: string[];
+  releaseNoteIncludeHashes: boolean;
+  dependencyPattern: string;
+}
+
+export const DEFAULT_CONFIG: ProjectConfig = {
+  maxWip: 3,
+  requiredSections: ["## Problem", "## Proposed Solution", "## Acceptance Criteria"],
+  complexityLevels: ["trivial", "small", "medium", "large", "epic"],
+  areas: [],
+  issueLabels: ["enhancement", "bug", "documentation", "question"],
+  issueCreateRequireComplexity: false,
+  issueCreateRequireArea: false,
+  releaseNoteGroups: ["feat", "fix", "perf", "refactor", "chore", "docs", "test", "ci", "build"],
+  releaseNoteIncludeHashes: false,
+  dependencyPattern: "(?:Depends on|Blocked by|Requires)\\s+#(\\d+)",
+};
+
+export function loadConfig(cwd: string): ProjectConfig {
+  const configPath = path.join(cwd, ".projectrc.yml");
+  if (!fs.existsSync(configPath)) return { ...DEFAULT_CONFIG };
+  try {
+    const content = fs.readFileSync(configPath, "utf-8");
+    const result: Record<string, unknown> = {};
+    for (const line of content.split("\n")) {
+      const m = line.match(/^\s*([\w][\w.]*):\s*(.+)$/);
+      if (m) {
+        let val = m[2].trim();
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) val = val.slice(1, -1);
+        result[m[1]] = val;
+      }
+    }
+    return {
+      maxWip: parseInt(result["maxWip"] as string) || DEFAULT_CONFIG.maxWip,
+      requiredSections: (result["requiredSections"] as string)?.split(",").map(s => s.trim()).filter(Boolean) || DEFAULT_CONFIG.requiredSections,
+      complexityLevels: (result["complexityLevels"] as string)?.split(",").map(s => s.trim()).filter(Boolean) || DEFAULT_CONFIG.complexityLevels,
+      areas: (result["areas"] as string)?.split(",").map(s => s.trim()).filter(Boolean) || [],
+      issueLabels: (result["issueLabels"] as string)?.split(",").map(s => s.trim()).filter(Boolean) || DEFAULT_CONFIG.issueLabels,
+      issueCreateRequireComplexity: result["issueCreateRequireComplexity"] === "true",
+      issueCreateRequireArea: result["issueCreateRequireArea"] === "true",
+      releaseNoteGroups: (result["releaseNoteGroups"] as string)?.split(",").map(s => s.trim()).filter(Boolean) || DEFAULT_CONFIG.releaseNoteGroups,
+      releaseNoteIncludeHashes: result["releaseNoteIncludeHashes"] === "true",
+      dependencyPattern: (result["dependencyPattern"] as string) || DEFAULT_CONFIG.dependencyPattern,
+    };
+  } catch { return { ...DEFAULT_CONFIG }; }
+}

package/src/helpers.ts

@@ -0,0 +1,40 @@
+import * as cp from "node:child_process";
+
+export function exec(cmd: string, cwd?: string): { ok: boolean; stdout: string; stderr: string } {
+  try { const r = cp.execSync(cmd, { cwd, encoding: "utf-8", timeout: 30000 }); return { ok: true, stdout: r.trim(), stderr: "" }; }
+  catch (e: any) { return { ok: false, stdout: e.stdout?.trim() || "", stderr: e.stderr?.trim() || e.message }; }
+}
+
+export function currentBranch(cwd: string): string { return exec("git branch --show-current", cwd).stdout; }
+
+export function resolveGitea(cwd: string): { repo: string; token: string } {
+  const remote = exec("git remote get-url gitea 2>/dev/null || git remote get-url origin", cwd);
+  const url = remote.stdout || "";
+  const match = url.match(/[/:]([^/]+)\/([^/]+?)(?:\.git)?$/);
+  const repo = match ? `${match[1]}/${match[2]}` : "factory/wrok.in";
+  const credMatch = url.match(/:\/\/([^:]+):([^@]+)@/);
+  return { repo, token: credMatch ? credMatch[2] : "" };
+}
+
+export async function giteaApi(path: string, method: string, body: Record<string, unknown> | null, opts: { repo: string; token?: string }, _cwd: string): Promise<{ ok: boolean; data: unknown; error?: string }> {
+  const base = `http://127.0.0.1:3001/api/v1/repos/${opts.repo}`;
+  const url = `${base}${path}`;
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (opts.token) headers["Authorization"] = `token ${opts.token}`;
+
+  try {
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      const lines = text.split("\n");
+      return { ok: false, data: null, error: text || lines.slice(0, -1).join("\n") || "API error" };
+    }
+    try { return { ok: true, data: JSON.parse(text) }; } catch { return { ok: true, data: text }; }
+  } catch (e: any) {
+    return { ok: false, data: null, error: e.message || "Network error" };
+  }
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * pi-project-gate — Project Orchestration Gate
+ *
+ * Tools: project_check, project_start, project_status, project_release_notes,
+ *        project_create_issue, project_update_issue, project_list_issues, project_get_issue
+ * Config: .projectrc.yml
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { checkTool, startTool, statusTool, releaseTool } from "./tools/project";
+import { createTool, updateTool, listTool, getTool } from "./tools/issues";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool(checkTool);
+  pi.registerTool(startTool);
+  pi.registerTool(statusTool);
+  pi.registerTool(releaseTool);
+  pi.registerTool(createTool);
+  pi.registerTool(updateTool);
+  pi.registerTool(listTool);
+  pi.registerTool(getTool);
+  pi.on("session_shutdown", () => { delete (globalThis as any).__project_issueId; });
+}

package/src/tools/issues.ts

@@ -0,0 +1,328 @@
+import { Type } from "typebox";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../config";
+import { resolveGitea, giteaApi } from "../helpers";
+import { validateIssueTemplate } from "../validate";
+
+// ─── Create Issue ───────────────────────────────────────────────────────────────
+
+export const createTool = {
+  name: "project_create_issue" as const,
+  label: "Create Issue",
+  description:
+    "Create a new issue with structured body. Validates required template sections before creation.",
+  parameters: Type.Object({
+    title: Type.String({ description: "Issue title" }),
+    body: Type.String({ description: "Issue body in markdown (must include required sections)" }),
+    labels: Type.Optional(Type.Array(Type.String({}), { description: "Labels to apply" })),
+    milestone: Type.Optional(Type.String({ description: "Milestone title or ID" })),
+    assignee: Type.Optional(Type.String({ description: "Username to assign" })),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    const opts = resolveGitea(ctx.cwd);
+
+    // Validate template
+    const tpl = validateIssueTemplate(params.body, config);
+    if (!tpl.ok) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `❌ Issue body is missing required sections:\n  - ${tpl.missingSections.join("\n  - ")}`,
+          },
+        ],
+        isError: true,
+        details: { missingSections: tpl.missingSections },
+      };
+    }
+
+    // Detect complexity from body
+    const complexity = config.complexityLevels.find((l) =>
+      params.body.toLowerCase().includes(l.toLowerCase()),
+    );
+
+    // Build payload
+    const payload: Record<string, unknown> = {
+      title: params.title,
+      body: params.body,
+    };
+    if (params.labels && params.labels.length > 0) payload.labels = params.labels;
+    if (params.milestone) payload.milestone = params.milestone;
+    if (params.assignee) payload.assignee = params.assignee;
+
+    const r = await giteaApi("/issues", "POST", payload, opts, ctx.cwd);
+    if (!r.ok || !r.data) {
+      return {
+        content: [{ type: "text", text: `❌ Failed to create issue: ${r.error || "unknown error"}` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const issue = r.data as Record<string, unknown>;
+    const lines = [
+      `✅ Issue #${issue.number} created: "${issue.title}"`,
+      `   URL: ${issue.html_url || `http://127.0.0.1:3001/${opts.repo}/issues/${issue.number}`}`,
+    ];
+    if (complexity) lines.push(`   Complexity: ${complexity}`);
+    if (params.labels?.length) lines.push(`   Labels: ${params.labels.join(", ")}`);
+    if (params.milestone) lines.push(`   Milestone: ${params.milestone}`);
+    if (params.assignee) lines.push(`   Assignee: ${params.assignee}`);
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { issueId: issue.number, url: issue.html_url },
+    };
+  },
+};
+
+// ─── Update Issue ───────────────────────────────────────────────────────────────
+
+export const updateTool = {
+  name: "project_update_issue" as const,
+  label: "Update Issue",
+  description:
+    "Update an existing issue — title, body, state (open/closed), labels, milestone, or assignee.",
+  parameters: Type.Object({
+    issue_id: Type.String({ description: "Issue number or ID" }),
+    title: Type.Optional(Type.String({ description: "New title" })),
+    body: Type.Optional(Type.String({ description: "New body in markdown" })),
+    state: Type.Optional(
+      Type.String({ description: 'State: "open" or "closed"' }),
+    ),
+    labels: Type.Optional(Type.Array(Type.String({}), { description: "Replacement labels" })),
+    milestone: Type.Optional(Type.String({ description: "Milestone title or ID, or null to remove" })),
+    assignee: Type.Optional(Type.String({ description: "Username to assign, or empty string to unassign" })),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    const opts = resolveGitea(ctx.cwd);
+    const issueId = String(params.issue_id).replace(/^#/, "");
+
+    // Fetch current issue to verify it exists
+    const current = await giteaApi(`/issues/${issueId}`, "GET", null, opts, ctx.cwd);
+    if (!current.ok || !current.data) {
+      return {
+        content: [{ type: "text", text: `❌ Issue #${issueId} not found.` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    // Validate body template if body is being updated
+    if (params.body) {
+      const tpl = validateIssueTemplate(params.body, config);
+      if (!tpl.ok) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `❌ Updated body is missing required sections:\n  - ${tpl.missingSections.join("\n  - ")}`,
+            },
+          ],
+          isError: true,
+          details: { missingSections: tpl.missingSections },
+        };
+      }
+    }
+
+    // Build patch payload — only include fields that were provided
+    const payload: Record<string, unknown> = {};
+    if (params.title !== undefined) payload.title = params.title;
+    if (params.body !== undefined) payload.body = params.body;
+    if (params.state !== undefined) payload.state = params.state;
+    if (params.labels !== undefined) payload.labels = params.labels;
+    if (params.milestone !== undefined) payload.milestone = params.milestone;
+    if (params.assignee !== undefined) payload.assignee = params.assignee;
+
+    if (Object.keys(payload).length === 0) {
+      return {
+        content: [{ type: "text", text: "⚠️ No fields to update." }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const r = await giteaApi(`/issues/${issueId}`, "PATCH", payload, opts, ctx.cwd);
+    if (!r.ok || !r.data) {
+      return {
+        content: [{ type: "text", text: `❌ Failed to update issue: ${r.error || "unknown error"}` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const issue = r.data as Record<string, unknown>;
+    const changes: string[] = [];
+    if (params.title !== undefined) changes.push("title");
+    if (params.body !== undefined) changes.push("body");
+    if (params.state !== undefined) changes.push(`state → ${params.state}`);
+    if (params.labels !== undefined) changes.push("labels");
+    if (params.milestone !== undefined) changes.push("milestone");
+    if (params.assignee !== undefined) changes.push("assignee");
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `✅ Issue #${issueId} updated: "${issue.title}"\n   Changed: ${changes.join(", ")}`,
+        },
+      ],
+      details: { issueId, changed: changes },
+    };
+  },
+};
+
+// ─── List Issues ────────────────────────────────────────────────────────────────
+
+export const listTool = {
+  name: "project_list_issues" as const,
+  label: "List Issues",
+  description:
+    "Search and list issues with optional filters: state, labels, milestone, assignee, keyword, and pagination.",
+  parameters: Type.Object({
+    state: Type.Optional(Type.String({ description: 'Filter by state: "open" or "closed" (default: open)' })),
+    labels: Type.Optional(Type.String({ description: "Comma-separated label names" })),
+    milestone: Type.Optional(Type.String({ description: "Filter by milestone title" })),
+    assignee: Type.Optional(Type.String({ description: "Filter by assignee username" })),
+    q: Type.Optional(Type.String({ description: "Full-text search query (searches title + body)" })),
+    limit: Type.Optional(Type.Number({ description: "Max issues to return (default: 20, max: 100)" })),
+    page: Type.Optional(Type.Number({ description: "Page number (default: 1)" })),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const opts = resolveGitea(ctx.cwd);
+    const queryParts: string[] = [];
+    queryParts.push(`state=${params.state || "open"}`);
+    queryParts.push(`limit=${Math.min(params.limit || 20, 100)}`);
+    queryParts.push(`page=${params.page || 1}`);
+    if (params.labels) queryParts.push(`labels=${encodeURIComponent(params.labels)}`);
+    if (params.milestone) queryParts.push(`milestone=${encodeURIComponent(params.milestone)}`);
+    if (params.assignee) queryParts.push(`assignee=${encodeURIComponent(params.assignee)}`);
+    if (params.q) queryParts.push(`q=${encodeURIComponent(params.q)}`);
+
+    const r = await giteaApi(`/issues?${queryParts.join("&")}`, "GET", null, opts, ctx.cwd);
+    if (!r.ok) {
+      return {
+        content: [{ type: "text", text: `❌ Failed to list issues: ${r.error || "unknown error"}` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const issues = Array.isArray(r.data) ? r.data : [];
+    if (issues.length === 0) {
+      return {
+        content: [{ type: "text", text: "No issues found." }],
+        details: { count: 0 },
+      };
+    }
+
+    const lines = [`📋 Issues (${issues.length} found)`];
+    if (params.q) lines.push(`   Search: "${params.q}"`);
+    lines.push("");
+
+    for (const issue of issues as any[]) {
+      const labels =
+        issue.labels && issue.labels.length > 0
+          ? ` [${issue.labels.map((l: any) => l.name).join(", ")}]`
+          : "";
+      const assignee = issue.assignee ? ` (👤 ${issue.assignee.login})` : "";
+      lines.push(
+        `   #${issue.number} ${issue.state === "closed" ? "🔒" : "🟢"} ${issue.title}${labels}${assignee}`,
+      );
+    }
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { count: issues.length, issues: issues.map((i: any) => i.number) },
+    };
+  },
+};
+
+// ─── Get Issue ───────────────────────────────────────────────────────────────────
+
+export const getTool = {
+  name: "project_get_issue" as const,
+  label: "Get Issue",
+  description:
+    "Get full details of an issue including its body, labels, milestone, assignee, and recent comments.",
+  parameters: Type.Object({
+    issue_id: Type.String({ description: "Issue number or ID" }),
+    include_comments: Type.Optional(
+      Type.Boolean({ description: "Include recent comments (default: true)" }),
+    ),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const opts = resolveGitea(ctx.cwd);
+    const issueId = String(params.issue_id).replace(/^#/, "");
+
+    const r = await giteaApi(`/issues/${issueId}`, "GET", null, opts, ctx.cwd);
+    if (!r.ok || !r.data) {
+      return {
+        content: [{ type: "text", text: `❌ Issue #${issueId} not found.` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const issue = r.data as Record<string, unknown>;
+    const labels = Array.isArray(issue.labels)
+      ? (issue.labels as any[]).map((l) => l.name).join(", ")
+      : "(none)";
+
+    const lines = [
+      `📋 Issue #${issueId}`,
+      `   Title: ${issue.title}`,
+      `   State: ${issue.state}  |  Created: ${String(issue.created_at).slice(0, 10)}`,
+      `   Author: ${(issue.user as any)?.login || "?"}`,
+      `   Assignee: ${(issue.assignee as any)?.login || "(unassigned)"}`,
+      `   Milestone: ${(issue.milestone as any)?.title || "(none)"}`,
+      `   Labels: ${labels}`,
+      `   URL: ${issue.html_url || `http://127.0.0.1:3001/${opts.repo}/issues/${issueId}`}`,
+      "",
+      "─── Body ───",
+      issue.body || "(empty)",
+      "",
+    ];
+
+    // Fetch comments
+    const includeComments = params.include_comments !== false;
+    if (includeComments) {
+      const cr = await giteaApi(
+        `/issues/${issueId}/comments?limit=20`,
+        "GET",
+        null,
+        opts,
+        ctx.cwd,
+      );
+      const comments = Array.isArray(cr.data) ? cr.data : [];
+      if (comments.length > 0) {
+        lines.push(`─── Comments (${comments.length}) ───`);
+        for (const c of comments as any[]) {
+          const date = String(c.created_at).slice(0, 10);
+          const user = c.user?.login || "?";
+          const body = (c.body || "").split("\n").slice(0, 5).join("\n");
+          lines.push(`\n   [${date}] ${user}:`);
+          for (const bl of body.split("\n")) {
+            lines.push(`   ${bl}`);
+          }
+          if ((c.body || "").split("\n").length > 5) lines.push("   ...");
+        }
+      } else {
+        lines.push("─── Comments ───");
+        lines.push("   (none)");
+      }
+    }
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: {
+        issueId,
+        state: issue.state,
+        title: issue.title,
+        url: issue.html_url,
+      },
+    };
+  },
+};

package/src/tools/project.ts

@@ -0,0 +1,113 @@
+import { Type } from "typebox";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../config";
+import { exec, currentBranch, resolveGitea, giteaApi } from "../helpers";
+import { validateIssueTemplate, parseDependencies, parseConventionalCommits } from "../validate";
+
+const LABELS: Record<string, string> = { feat: "🚀 Features", fix: "🐛 Bug Fixes", perf: "⚡ Performance", refactor: "♻️ Refactoring", chore: "🔧 Chores", docs: "📝 Documentation", test: "✅ Tests", ci: "👷 CI/CD", build: "📦 Build", other: "📌 Other" };
+
+export const checkTool = {
+  name: "project_check" as const, label: "Check Issue Readiness",
+  description: "Validate that an issue is ready to be worked on.",
+  parameters: Type.Object({ issue_id: Type.String({}) }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd); const opts = resolveGitea(ctx.cwd);
+    const issueId = params.issue_id.replace(/^#/, "");
+    const r = await giteaApi(`/issues/${issueId}`, "GET", null, opts, ctx.cwd);
+    if (!r.ok || !r.data) return { content: [{ type: "text", text: `Issue #${issueId} not found.` }], isError: true, details: {} };
+    const issue = r.data as Record<string, unknown>;
+    const lines: string[] = []; const issues: string[] = [];
+    lines.push(`📋 Issue #${issueId}: ${issue.title}`);
+    const body = (issue.body as string) || "";
+    const tpl = validateIssueTemplate(body, config);
+    if (!tpl.ok) issues.push(`❌ Missing sections: ${tpl.missingSections.join(", ")}`);
+    else lines.push("   Template: ✅");
+    const complexity = config.complexityLevels.find(l => body.toLowerCase().includes(l.toLowerCase()));
+    lines.push(`   Complexity: ${complexity || "?"}`);
+    const deps = parseDependencies(body, config);
+    if (deps.length > 0) {
+      const blocked: string[] = [];
+      for (const dep of deps) { const dr = await giteaApi(`/issues/${dep}`, "GET", null, opts, ctx.cwd); if (dr.ok && (dr.data as any)?.state === "open") blocked.push(dep); }
+      if (blocked.length > 0) issues.push(`🔒 Blocked by: #${blocked.join(", #")}`);
+      else lines.push("   Dependencies: ✅");
+    }
+    if (issue.assignee) issues.push(`⚠️ Assigned to ${(issue.assignee as any)?.login}`);
+    if (issues.length > 0) { lines.push(""); for (const i of issues) lines.push(`   ${i}`); }
+    const blocked = issues.some(i => i.startsWith("❌") || i.startsWith("🔒"));
+    lines.push("", blocked ? "❌ Not ready." : issues.length === 0 ? "✅ Ready!" : "⚠️ Warnings but can start.");
+    return { content: [{ type: "text", text: lines.join("\n") }], details: { ready: !blocked } };
+  },
+};
+
+export const startTool = {
+  name: "project_start" as const, label: "Start Work",
+  description: "Mark an issue as in-progress. Checks WIP limits, dependencies, template.",
+  parameters: Type.Object({ issue_id: Type.String({}) }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd); const opts = resolveGitea(ctx.cwd);
+    const issueId = params.issue_id.replace(/^#/, "");
+    const r = await giteaApi(`/issues/${issueId}`, "GET", null, opts, ctx.cwd);
+    if (!r.ok || !r.data) return { content: [{ type: "text", text: `Issue #${issueId} not found.` }], isError: true, details: {} };
+    const issue = r.data as Record<string, unknown>;
+    const body = (issue.body as string) || "";
+    const tpl = validateIssueTemplate(body, config);
+    if (!tpl.ok) return { content: [{ type: "text", text: `❌ Missing sections: ${tpl.missingSections.join(", ")}` }], isError: true, details: {} };
+    const deps = parseDependencies(body, config);
+    if (deps.length > 0) {
+      const blocked: string[] = [];
+      for (const dep of deps) { const dr = await giteaApi(`/issues/${dep}`, "GET", null, opts, ctx.cwd); if (dr.ok && (dr.data as any)?.state === "open") blocked.push(dep); }
+      if (blocked.length > 0) return { content: [{ type: "text", text: `🔒 Blocked: #${blocked.join(", #")}` }], isError: true, details: {} };
+    }
+    const wipR = await giteaApi("/pulls?state=open&limit=100", "GET", null, opts, ctx.cwd);
+    const prs = Array.isArray(wipR.data) ? wipR.data : [];
+    const author = (issue.user as any)?.login || "factory";
+    const currentWip = prs.filter((p: any) => p.user?.login === author).length;
+    if (currentWip >= config.maxWip) return { content: [{ type: "text", text: `⚠️ WIP limit reached (${currentWip}/${config.maxWip}).` }], isError: true, details: {} };
+    (globalThis as any).__project_issueId = issueId;
+    return { content: [{ type: "text", text: `✅ Work started on #${issueId}: "${issue.title}" (WIP ${currentWip + 1}/${config.maxWip})` }], details: { issueId } };
+  },
+};
+
+export const statusTool = {
+  name: "project_status" as const, label: "Project Status",
+  description: "Show project board — active issues, WIP, blockers.",
+  parameters: Type.Object({}),
+  async execute(_id: string, _p: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd); const opts = resolveGitea(ctx.cwd);
+    const lines = ["📊 Project Status", ""];
+    const wipR = await giteaApi("/pulls?state=open&limit=100", "GET", null, opts, ctx.cwd);
+    const prs = Array.isArray(wipR.data) ? wipR.data : [];
+    const byAuthor: Record<string, number> = {};
+    for (const pr of prs) { const a = (pr as any).user?.login || "?"; byAuthor[a] = (byAuthor[a] || 0) + 1; }
+    lines.push(`🏗 WIP: ${prs.length} open PRs (limit: ${config.maxWip})`);
+    for (const [a, c] of Object.entries(byAuthor).sort(([, a], [, b]) => b - a)) lines.push(`   ${a}: ${c}/${config.maxWip} ${c >= config.maxWip ? "⚠️" : "✅"}`);
+    const issuesR = await giteaApi("/issues?state=open&limit=10", "GET", null, opts, ctx.cwd);
+    if (issuesR.ok && Array.isArray(issuesR.data)) {
+      const assigned = (issuesR.data as any[]).filter((i: any) => i.assignee).slice(0, 5);
+      if (assigned.length > 0) { lines.push("", "In Progress:"); for (const i of assigned) lines.push(`   - #${i.number} [${i.assignee?.login}] ${i.title}`); }
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }], details: {} };
+  },
+};
+
+export const releaseTool = {
+  name: "project_release_notes" as const, label: "Generate Release Notes",
+  description: "Generate release notes from conventional commits.",
+  parameters: Type.Object({ from: Type.Optional(Type.String({})), to: Type.Optional(Type.String({})) }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    let from = params.from || exec("git describe --tags --abbrev=0 2>/dev/null || echo ''", ctx.cwd).stdout;
+    const to = params.to || "HEAD";
+    if (!from) from = exec("git rev-list --max-parents=0 HEAD", ctx.cwd).stdout;
+    const range = from ? `${from}..${to}` : to;
+    const log = exec(`git log ${range} --format="commit %H%n%B%n---" --no-merges`, ctx.cwd);
+    const commits = parseConventionalCommits(log.stdout || "");
+    const sections: Record<string, string[]> = {};
+    for (const g of config.releaseNoteGroups) sections[g] = [];
+    sections["other"] = [];
+    for (const c of commits) { const prefix = config.releaseNoteIncludeHashes ? `- ${c.hash} ` : "- "; const line = `${prefix}${c.scope ? `**${c.scope}**: ` : ""}${c.subject}`; (sections[c.type] || sections["other"]).push(line); }
+    const lines = [`# Release ${to} (${new Date().toISOString().split("T")[0]})`, ""];
+    for (const [group, entries] of Object.entries(sections)) { if (entries.length === 0) continue; lines.push(`### ${LABELS[group] || group}`, ""); for (const e of entries) lines.push(e); lines.push(""); }
+    return { content: [{ type: "text", text: lines.join("\n") }], details: {} };
+  },
+};

package/src/validate.ts

@@ -0,0 +1,31 @@
+import type { ProjectConfig } from "./config";
+
+export function validateIssueTemplate(body: string, config: ProjectConfig): { ok: true } | { ok: false; missingSections: string[] } {
+  const missing = config.requiredSections.filter(s => !body.includes(s));
+  return missing.length > 0 ? { ok: false, missingSections: missing } : { ok: true };
+}
+
+export function parseDependencies(body: string, config: ProjectConfig): string[] {
+  const pattern = new RegExp(config.dependencyPattern, "gi");
+  const deps = new Set<string>();
+  let match;
+  while ((match = pattern.exec(body)) !== null) deps.add(match[1]);
+  return [...deps];
+}
+
+export interface CommitEntry { hash: string; type: string; scope: string; subject: string; }
+
+export function parseConventionalCommits(log: string): CommitEntry[] {
+  const entries: CommitEntry[] = [];
+  const commits = log.split(/\n(?=commit )/);
+  for (const block of commits) {
+    const hashMatch = block.match(/^commit (\S+)/m);
+    if (!hashMatch) continue;
+    const subjectLine = block.split("\n").find(l => l.trim() && !l.startsWith("commit ") && !l.startsWith("Author:") && !l.startsWith("Date:"));
+    if (!subjectLine) continue;
+    const convMatch = subjectLine.trim().match(/^(feat|fix|perf|refactor|chore|docs|style|test|ci|build|revert)(?:\(([^)]+)\))?:\s(.+)$/);
+    if (!convMatch) continue;
+    entries.push({ hash: hashMatch[1].slice(0, 8), type: convMatch[1], scope: convMatch[2] || "", subject: convMatch[3].trim() });
+  }
+  return entries;
+}