@dleangen/cage-issues 0.0.1 → 0.1.0

package/package.json

@@ -1,8 +1,46 @@
 {
   "name": "@dleangen/cage-issues",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "File-based issue tracking for CAGE-enabled projects.",
   "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "cage-issues-mcp": "./dist/mcp/server.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "schemas/"
+  ],
+  "scripts": {
+    "build": "shx rm -rf dist && tsc -b",
+    "lint": "eslint",
+    "posttest": "npm run lint",
+    "test": "mocha --forbid-only \"test/**/*.test.ts\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1",
+    "js-yaml": "^4",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/chai": "^4",
+    "@types/js-yaml": "^4",
+    "@types/mocha": "^10",
+    "@types/node": "^18",
+    "chai": "^4",
+    "eslint": "^9",
+    "eslint-config-prettier": "^10",
+    "mocha": "^11",
+    "shx": "^0.3.3",
+    "ts-node": "^10",
+    "typescript": "^5",
+    "typescript-eslint": "^8"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "keywords": [
     "cage",
     "issues",

package/schemas/backlog.yaml

@@ -0,0 +1,23 @@
+# backlog.yaml — per-topic backlog
+# Place at: topics/{TOPIC}/backlog.yaml
+# Resolved and cancelled issues are removed entirely — not commented out.
+# History is accessed via list_issues.
+
+active:
+  - id: SHELL-2026-0003
+    title: Add a dedicated dev-only /ops/api proxy
+    rationale: >
+      Removes credential sharing in chat; unblocks agent queries against
+      the data API.
+
+up_next:
+  - id: SHELL-2026-0002
+    title: Extend guardedFetch coverage to documentApi
+    rationale: >
+      Follow-on to 0001. Three service files bypass 401 detection.
+
+deferred:
+  - id: SHELL-2026-0001
+    title: CI gradient coordination
+    rationale: >
+      Depends on external coordination. No shell code change needed yet.

package/schemas/config.yaml

@@ -0,0 +1,28 @@
+# config.yaml — root-level user configuration
+# Place this file at the root of your management repository.
+
+priority_labels:
+  p1: p1        # override with e.g. "Blocking"
+  p2: p2        # override with e.g. "High"
+  p3: p3        # override with e.g. "Medium"
+  p4: p4        # override with e.g. "Low"
+
+impact_labels:
+  low: low
+  medium: medium
+  high: high
+  critical: critical
+
+# Project-specific tracks. Generic tracks (Data, Docs, Meta, Issues)
+# are built-in and do not need to be listed here.
+tracks:
+  - id: frontend
+    name: Frontend
+    affects_patterns:
+      - src/
+      - components/
+  - id: api
+    name: API
+    affects_patterns:
+      - api/
+      - routes/

package/schemas/issue.yaml

@@ -0,0 +1,61 @@
+# issue.yaml — full example issue (all fields populated)
+# Filename: {TOPIC}-{YEAR}-{SEQUENCE}.yaml
+# Place at: topics/{TOPIC}/issues/{TOPIC}-{YEAR}-{SEQUENCE}.yaml
+
+# System fields — auto-generated, immutable
+id: SHELL-2026-0003
+date: '2026-06-04'
+
+# Required fields
+title: Add a dedicated dev-only /ops/api proxy
+description: >
+  The dev server currently exposes the API at /api, which requires
+  shared credentials in chat sessions. A dedicated /ops/api proxy
+  would allow agents to query the data API without credential sharing.
+
+# Status
+status: in_progress
+status_history:
+  - status: open
+    timestamp: '2026-06-04T09:00:00Z'
+    by: owner
+  - status: in_progress
+    timestamp: '2026-06-04T14:00:00Z'
+    by: Manager
+
+# Maturity-gating fields
+priority: p2
+what_to_resolve: >
+  Agents can query /ops/api in dev without needing shared credentials.
+  The proxy is dev-only and not present in production builds.
+
+tasks:
+  - id: t1
+    description: Add /ops/api route to vite.config.ts proxy table.
+    status: done
+    priority: must-have
+  - id: t2
+    description: Update agent documentation to reference /ops/api.
+    status: open
+    priority: nice-to-have
+
+affects:
+  - vite.config.ts
+  - docs/agent-api-access.md
+
+signoffs:
+  - role: Architect
+    timestamp: '2026-06-04T15:00:00Z'
+    note: >
+      Reviewed proxy config. Scoped correctly to dev only. No concerns.
+
+# Context fields (all optional)
+focus: dev-tooling
+facet: feature
+impact: medium
+impact_note: Unblocks agent-assisted API queries during development.
+classification: standard
+base_branch: main
+related:
+  - SHELL-2026-0002
+dependencies: []

package/schemas/topic.yaml

@@ -0,0 +1,9 @@
+# topic.yaml — topic registration file
+# Place at: topics/{TOPIC}/topic.yaml
+
+id: SHELL
+name: LandVault Shell Application
+description: >
+  Frontend application and its supporting infrastructure.
+owner: david.leangen@example.com
+status: active   # active | closed

package/skills/display-backlog.md

@@ -0,0 +1,41 @@
+# Skill: Display Backlog
+
+Display a topic's backlog (or an aggregated cross-topic backlog) in a table with Active → Up Next → Deferred sections.
+
+## When to use
+
+- User asks to see the backlog
+- User asks what's queued, what's next, or what's deferred
+- User asks for the current work queue
+
+## Steps
+
+1. Call `get_backlog` with the topic (and optional track filter) the user specified. Omit topic for the cross-topic aggregate.
+2. Render using the format below.
+
+## Format
+
+```
+━━━ Backlog{topic_suffix}{track_suffix} ━━━
+
+── Active ───────────────────────────────────────────
+  {ID}   {title}
+         {rationale}
+
+── Up Next ──────────────────────────────────────────
+  {ID}   {title}
+         {rationale}
+
+── Deferred ─────────────────────────────────────────
+  {ID}   {title}
+         {rationale}
+```
+
+## Rendering rules
+
+- `{topic_suffix}`: ` — {TOPIC}` if scoped to a single topic, empty if aggregate.
+- `{track_suffix}`: ` [track: {track}]` if a track filter was applied.
+- If a section is empty, show `  (none)` on the line below the section header.
+- Rationale text is optional — omit the line if the entry has no rationale.
+- Entry IDs are left-aligned and right-padded so titles line up in a column.
+- Preserve section order: Active first, then Up Next, then Deferred.

package/skills/display-issue.md

@@ -0,0 +1,72 @@
+# Skill: Display Single Issue
+
+Display a single issue in a structured, readable format. Use this whenever the user asks to see, view, or get details on a specific issue.
+
+## When to use
+
+- User asks to see issue SHELL-2026-0003
+- User says "show me that issue"
+- User wants to review an issue before acting on it
+
+## Steps
+
+1. Call `get_issue` with the issue ID.
+2. Render using the format below.
+
+## Format
+
+Render the issue as follows. Omit sections whose fields are all absent.
+
+```
+━━━ {ID} ━━━
+{title}
+
+Status:    {status}          Maturity: {maturity}
+Priority:  {priority_label}  Track:    {track}
+Date:      {date}
+
+{description}
+
+── Resolution Criteria ──────────────────────────────
+{what_to_resolve}
+
+── Tasks ────────────────────────────────────────────
+  [{task_status_icon}] [{task_priority}] {task_description}
+  ...
+
+── Affects ──────────────────────────────────────────
+  - {affects[0]}
+  - {affects[1]}
+  ...
+
+── Context ──────────────────────────────────────────
+Focus:          {focus}
+Facet:          {facet}
+Impact:         {impact_label}  — {impact_note}
+Classification: {classification}
+Base branch:    {base_branch}
+PR:             {pull_request}
+Related:        {related}
+Dependencies:   {dependencies}
+
+── Signoffs ─────────────────────────────────────────
+  ✓ {role}  {timestamp}
+    {note}
+
+── Status History ───────────────────────────────────
+  {timestamp}  {status}  (by {by})
+  ...
+```
+
+## Rendering rules
+
+- `{priority_label}`: look up the user's configured label for the priority value (from `config.yaml`). Fall back to the raw value (p1–p4) if config is unavailable.
+- `{impact_label}`: same pattern for impact values.
+- `{task_status_icon}`: `✓` for done, `→` for in_progress, ` ` (space) for open.
+- `{track}`: show "—" if null.
+- Omit the "Resolution Criteria" section if `what_to_resolve` is absent.
+- Omit the "Tasks" section if `tasks` is empty or absent.
+- Omit the "Affects" section if `affects` is empty or absent.
+- Omit the "Signoffs" section if `signoffs` is empty or absent.
+- Omit individual context fields that are absent.
+- Status history is always shown.

package/skills/display-list.md

@@ -0,0 +1,39 @@
+# Skill: Display List of Issues
+
+Display filtered or search results as a compact table. Use for multi-issue views where the user does not need full detail on each issue.
+
+## When to use
+
+- User lists issues with filters (by status, priority, topic, track, date range)
+- User searches for issues
+- User asks "what's open in SHELL?" or "show me all p1 issues"
+
+## Steps
+
+1. Call `list_issues` or `search_issues` with the parameters the user specified.
+2. Render using the format below.
+
+## Format
+
+```
+━━━ Issues{filter_summary} ━━━
+
+  ID                  St  Pri  Mat      Track     Title
+  ──────────────────  ──  ───  ───────  ────────  ──────────────────────────────
+  SHELL-2026-0003     ●   p2   ready    frontend  Add /ops/api proxy
+  SHELL-2026-0002     ○   p3   defined  docs      Extend guardedFetch coverage
+  ...
+
+{count} issue(s)
+```
+
+## Rendering rules
+
+- `{filter_summary}`: a compact summary of active filters, e.g. ` — SHELL / open / p1`. Omit if no filters.
+- **St (status) icon**: `●` in_progress, `○` open, `✓` resolved, `✗` cancelled.
+- **Mat (maturity)**: show the full word (draft / defined / ready / verified).
+- **Track**: show "—" if null.
+- Sort: by date descending (newest first) unless the user specifies otherwise.
+- For `search_issues` results: preserve relevance ranking order.
+- Truncate very long titles with `…` to keep the table readable.
+- Show the count line at the bottom.

package/skills/display-weekly-summary.md

@@ -0,0 +1,50 @@
+# Skill: Display Weekly Activity Summary
+
+Display a summary of resolved issues over a date range, grouped by topic and track. Used for weekly reviews, standups, and progress reports.
+
+## When to use
+
+- User asks for the weekly summary
+- User asks what was resolved this week (or last week, or a specific date range)
+- User wants a progress report for a time period
+
+## Steps
+
+1. Determine the date range:
+   - "this week" → Monday of current week through today
+   - "last week" → Monday through Sunday of the previous week
+   - Explicit dates → use as given
+2. Call `list_issues` with `status: resolved` and the date range. If the user scoped to a topic, pass it; otherwise omit for all topics.
+3. Render using the format below.
+
+## Format
+
+```
+━━━ Weekly Summary — {date_from} to {date_to} ━━━
+
+{TOPIC} — {topic_name}
+  {track}
+    ✓ {ID}  {title}
+    ✓ {ID}  {title}
+
+{TOPIC} — {topic_name}
+  {track}
+    ✓ {ID}  {title}
+
+──────────────────────────────────────────────────────
+{total} issue(s) resolved
+```
+
+## Rendering rules
+
+- Group first by topic, then by track within each topic.
+- Within each track group, sort issues by resolution date ascending.
+- Show track as "—" for issues with no derived track.
+- If no issues were resolved in the date range, say: `No issues resolved in this period.`
+- The date range header uses ISO dates (YYYY-MM-DD).
+- For cross-topic summaries, order topics alphabetically by ID.
+- Include the total count line at the bottom.
+
+## Note on date filtering
+
+`list_issues` filters on the `date` field (creation date). Resolved issues do not store a separate resolution date in v1. Filter by `date_from`/`date_to` as a proxy; the weekly summary covers issues *created* in the range that are now resolved. Document this limitation if it affects the user's interpretation.

package/.github/workflows/publish.yml

@@ -1,31 +0,0 @@
-name: Publish to npm
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write  # needed to create GitHub Release
-      id-token: write  # needed for npm trusted publishing
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '24'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Publish to npm
-        run: npm publish --access public --provenance
-
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
-        with:
-          generate_release_notes: true