Develop

.claude/settings.local.json

@@ -0,0 +1,33 @@
+{
+  "permissions": {
+    "allow": [
+      "Skill(update-config)",
+      "Bash(python -m json.tool)",
+      "Bash(python:*)",
+      "Bash(node:*)",
+      "Bash(openssl rand:*)",
+      "Bash(curl -s 'http://PAYTON-LEGION2:7147/health?nonce=__TRACKED_VAR__')",
+      "Bash(curl:*)",
+      "Bash(start:*)",
+      "Bash(gsudo:*)",
+      "Bash(grep -E \"\\\\.ps1$\")",
+      "Bash(dotnet build:*)",
+      "Bash(break)",
+      "Bash(printf '{\"schemaVersion\":1,\"generatedUtc\":\"2026-04-06T20:00:00Z\",\"generatedBy\":\"manual-fix\",\"operation\":\"update\",\"serviceName\":\"McpServer\",\"executable\":\"McpServer.Support.Mcp.exe\",\"port\":7147}')",
+      "Bash(tasklist)",
+      "Bash(\"C:/ProgramData/McpServer/tools/ngrok.exe\" http:*)",
+      "Bash(\"C:/ProgramData/McpServer/tools/ngrok.exe\" api:*)",
+      "Bash(C:/ProgramData/McpServer/tools/ngrok.exe version:*)",
+      "Bash(NGROK_AUTHTOKEN=39PlC1rVQvxL7JLCUnvZ7BwWP1h_5EKMeqsnVoTTrLfuR79h3 \"C:/ProgramData/McpServer/tools/ngrok.exe\" http 7147 --log stdout --log-format json)",
+      "Bash(grep -h \"Route\\\\|HttpGet\\\\|HttpPost\\\\|HttpPut\\\\|HttpDelete\" /f/GitHub/McpServer/src/McpServer.Support.Mcp/Controllers/*.cs)",
+      "Bash(sed 's/.*Name = \"//')",
+      "Bash(sed 's/\".*//')",
+      "Bash(az pipelines:*)",
+      "Bash(az devops:*)",
+      "Bash(pwsh -ExecutionPolicy Bypass -File F:/GitHub/McpServer/check-markers.ps1)",
+      "Bash(grep -v \"^Loaded\\\\|^$\\\\|Snippet\\\\|-------\\\\|aliases\\\\|common\\\\|repos\\\\|bing\\\\|chocolatey\\\\|clean\\\\|devmode\\\\|gh_comp\\\\|github\\\\|module-loader\\\\|oh-my-posh\\\\|set-version\\\\|update-snippets\\\\|CommandType\\\\|----------\\\\|Alias\\\\|Name \\\\|----\\\\|Snippets\\\\|profileup\\\\|snipup\\\\|snipps\\\\|hub\\\\|modrl\\\\|posh\\\\|repos\\\\|ch \\\\|dn \\\\|dt \\\\|np \\\\|ng \\\\|pp \\\\|pps\\\\|psg\\\\|scp\\\\|wg \\\\|als\\\\|clean\\\\|devmode\\\\|audio\\\\|pwg\")",
+      "Bash(pwsh -NoProfile -NonInteractive -ExecutionPolicy Bypass -File F:/GitHub/McpServer/check-markers.ps1)",
+      "Bash(pwsh -NoProfile -NonInteractive -ExecutionPolicy Bypass -File F:/GitHub/McpServer/create-graphrag-todos.ps1)"
+    ]
+  }
+}

.claude/tmp/todo-update.json

@@ -0,0 +1,100 @@
+{
+    "description": [
+      "Create a Claude Code plugin at .claude/plugins/mcpserver/ that automates MCP server session bootstrapping and provides skills for common workflows.",
+      "Connects Claude Code to 45 MCP tools via Streamable HTTP at /mcp-transport (no API key needed).",
+      "Provides bootstrap hook for automatic health verification and context injection.",
+      "User-invoked skills: /mcpserver:status, /mcpserver:todo, /mcpserver:deploy, /mcpserver:tunnel.",
+      "Model-invoked skills: session logging workflow, TODO workflow, requirements tracking.",
+      "Custom agent: mcp-context-researcher for context search and GraphRAG research.",
+      "",
+      "## Implementation Phases",
+      "",
+      "### Phase 1: Core Infrastructure (3 files)",
+      "- .claude-plugin/plugin.json - Plugin manifest (fields: name, description, version, author with name/email). No homepage field.",
+      "- .mcp.json - MCP transport connection. FLAT format: { server-name: { type: http, url: ... } }. No mcpServers wrapper.",
+      "- README.md - Plugin documentation",
+      "",
+      "### Phase 2: Session Bootstrap (2 files) - REVISED",
+      "- hooks/hooks.json - Hook registration. Top-level has description + hooks object. Valid events: PreToolUse, PostToolUse, Stop, UserPromptSubmit. SessionStart does NOT exist.",
+      "- hooks/hooks-handlers/session-start.ps1 - Bootstrap script. Reads AGENTS-README-FIRST.yaml, verifies /health with nonce, injects context or MCP_UNTRUSTED warning.",
+      "- DESIGN DECISION NEEDED: Use UserPromptSubmit hook (fires on first prompt, auto-bootstrap) OR create a /mcpserver:start user-invoked skill for explicit bootstrap. UserPromptSubmit fires on EVERY prompt so script must be idempotent and fast (check cached state).",
+      "- Hook entry fields: type, command, timeout ONLY. No shell field. Use $CLAUDE_PLUGIN_ROOT for paths.",
+      "",
+      "### Phase 3: User-Invoked Skills (4 files)",
+      "- skills/status/SKILL.md - /mcpserver:status. Frontmatter: name, description, argument-hint, allowed-tools: [Bash, Read]",
+      "- skills/todo/SKILL.md - /mcpserver:todo. Frontmatter: name, description, argument-hint, allowed-tools: [Bash, Read]",
+      "- skills/deploy/SKILL.md - /mcpserver:deploy. Frontmatter: name, description, argument-hint, allowed-tools: [Bash, Read]",
+      "- skills/tunnel/SKILL.md - /mcpserver:tunnel. Frontmatter: name, description, argument-hint, allowed-tools: [Bash, Read]",
+      "- NOTE: User-invoked is determined by presence of argument-hint field. No user_invoked: true field exists.",
+      "",
+      "### Phase 4: Model-Invoked Skills (3 files)",
+      "- skills/mcp-session-logging/SKILL.md - Only name + description in frontmatter. No argument-hint = model-invoked.",
+      "- skills/mcp-todo-workflow/SKILL.md - TODO CRUD, ID format rules, GitHub sync behavior",
+      "- skills/mcp-requirements/SKILL.md - FR/TR/TEST format, docs/Project/ locations",
+      "",
+      "### Phase 5: Custom Agent (1 file)",
+      "- agents/mcp-context-researcher.md - Frontmatter must include: name, description, tools (comma-separated), model (sonnet), color (cyan)",
+      "",
+      "### Phase 6: Housekeeping (1 task)",
+      "- Update .gitignore with .claude/*.local.md and .claude/*.local.json patterns",
+      "",
+      "## Key Design Decisions",
+      "- .mcp.json uses FLAT format with localhost:7147/mcp-transport (no API key, portable)",
+      "- Bootstrap hook uses UserPromptSubmit (not SessionStart which does not exist). Script must be idempotent.",
+      "- Hook commands reference plugin root via ${CLAUDE_PLUGIN_ROOT} variable, not hardcoded paths",
+      "- Model-invoked skills provide naming conventions and workflow guides",
+      "- API key included in hook context output for REST API fallback calls",
+      "",
+      "## Audit Corrections Applied (2026-04-06)",
+      "- CRITICAL: SessionStart is not a valid hook event. Changed to UserPromptSubmit or explicit /mcpserver:start skill.",
+      "- CRITICAL: shell field does not exist in hook entries. Removed.",
+      "- CRITICAL: .mcp.json must use flat format, not mcpServers wrapper.",
+      "- MODERATE: user_invoked: true is not a valid field. Use argument-hint presence instead.",
+      "- MODERATE: homepage is not a valid plugin.json field. Removed.",
+      "- MODERATE: Added allowed-tools to all user-invoked skills.",
+      "- MODERATE: Added model, color, tools fields to agent definition.",
+      "- MINOR: Added .gitignore task for plugin local config files.",
+      "- MINOR: Use ${CLAUDE_PLUGIN_ROOT} in hook commands instead of hardcoded paths.",
+      "- MINOR: Added top-level description field to hooks.json spec.",
+      "",
+      "## Verification",
+      "1. Bootstrap hook fires on first prompt and injects MCP server context",
+      "2. /mcpserver:status shows health, workspace, tunnel status",
+      "3. /mcpserver:todo lists TODOs via MCP tools",
+      "4. mcp-session-logging skill activates when logging turns",
+      "5. mcp-todo-workflow skill activates with correct naming conventions",
+      "6. All 45 MCP tools visible in Claude tool list"
+    ],
+    "technicalDetails": [
+      "13 files + 1 gitignore update across 6 phases.",
+      "Plugin follows Claude Code plugin format: .claude-plugin/plugin.json manifest, .mcp.json (FLAT format) for MCP server connections, hooks/hooks.json for lifecycle hooks, skills/name/SKILL.md for slash commands and model-invoked skills, agents/name.md for custom agents.",
+      "Valid hook events: PreToolUse, PostToolUse, Stop, UserPromptSubmit. SessionStart does NOT exist.",
+      "Hook entry fields: type (command), command (string, supports ${CLAUDE_PLUGIN_ROOT}), timeout (int seconds). No shell field.",
+      "User-invoked skills identified by argument-hint presence, not a user_invoked field.",
+      "Agent frontmatter supports: name, description, tools (comma-separated), model (sonnet/haiku/opus/inherit), color.",
+      "plugin.json valid fields: name, description, version, author (name/email). No homepage.",
+      ".mcp.json flat format: { server-name: { type: http, url: ... } }. No mcpServers wrapper.",
+      "Uses pwsh.exe -NoProfile -NonInteractive for all PowerShell.",
+      "Full plan at .claude/plans/flickering-cooking-finch.md"
+    ],
+    "implementationTasks": [
+      {"task": "DESIGN DECISION: Choose bootstrap strategy - UserPromptSubmit hook vs /mcpserver:start skill", "done": false},
+      {"task": "Create .claude-plugin/plugin.json manifest (fields: name, description, version, author)", "done": false},
+      {"task": "Create .mcp.json with FLAT format Streamable HTTP transport config", "done": false},
+      {"task": "Create hooks/hooks.json with UserPromptSubmit registration (fields: type, command, timeout only)", "done": false},
+      {"task": "Create hooks/hooks-handlers/session-start.ps1 idempotent bootstrap script using ${CLAUDE_PLUGIN_ROOT}", "done": false},
+      {"task": "Create skills/status/SKILL.md with argument-hint and allowed-tools", "done": false},
+      {"task": "Create skills/todo/SKILL.md with argument-hint and allowed-tools", "done": false},
+      {"task": "Create skills/deploy/SKILL.md with argument-hint and allowed-tools", "done": false},
+      {"task": "Create skills/tunnel/SKILL.md with argument-hint and allowed-tools", "done": false},
+      {"task": "Create skills/mcp-session-logging/SKILL.md model-invoked skill (name + description only)", "done": false},
+      {"task": "Create skills/mcp-todo-workflow/SKILL.md model-invoked skill", "done": false},
+      {"task": "Create skills/mcp-requirements/SKILL.md model-invoked skill", "done": false},
+      {"task": "Create agents/mcp-context-researcher.md with tools, model, color fields", "done": false},
+      {"task": "Create README.md plugin documentation", "done": false},
+      {"task": "Update .gitignore with .claude/*.local.md and .claude/*.local.json patterns", "done": false},
+      {"task": "Test hook ${CLAUDE_PLUGIN_ROOT} variable expansion on Windows", "done": false},
+      {"task": "Verify plugin loads and all 45 MCP tools appear in Claude Code session", "done": false}
+    ],
+    "note": "Audited 2026-04-06. 3 critical corrections (SessionStart invalid, shell field invalid, mcp.json format), 4 moderate (user_invoked field, homepage, allowed-tools, agent fields), 3 minor (gitignore, CLAUDE_PLUGIN_ROOT, hooks.json description)."
+  }

.codex-turn-id

@@ -0,0 +1 @@
+req-20260406T204350Z-implement-repl-marker-api-key-fallback

.gitignore

@@ -198,20 +198,20 @@ publish/
 # in these scripts will be unencrypted
 PublishScripts/
 
-# NuGet Packages
-*.nupkg
-# NuGet Symbol Packages
-*.snupkg
-# The packages folder can be ignored because of Package Restore
-**/[Pp]ackages/*
-# except build/, which is used as an MSBuild target.
-!**/[Pp]ackages/build/
-# Uncomment if necessary however generally it will be regenerated when needed
-#!**/[Pp]ackages/repositories.config
-# NuGet v3's project.json files produces more ignorable files
-*.nuget.props
-*.nuget.targets
-# Local NuGet package feed
+# NuGet Packages
+*.nupkg
+# NuGet Symbol Packages
+*.snupkg
+# The packages folder can be ignored because of Package Restore
+**/[Pp]ackages/*
+# except build/, which is used as an MSBuild target.
+!**/[Pp]ackages/build/
+# Uncomment if necessary however generally it will be regenerated when needed
+#!**/[Pp]ackages/repositories.config
+# NuGet v3's project.json files produces more ignorable files
+*.nuget.props
+*.nuget.targets
+# Local NuGet package feed
 local-packages/
 
 # Microsoft Azure Build Output
@@ -488,29 +488,36 @@ $RECYCLE.BIN/
 # Vim temporary swap files
 *.swp
 
-# MCP server marker files (runtime artifacts for agent port discovery)
-.mcp-server.yaml
-.mcp-server.json
-.mcpServer/
-.mcpSession/
-
-# SQLite database files (runtime data)
-*.db
-*.db-shm
-*.db-wal
-
-# Build / publish output
-_publish/
-_site/
-
-# Local scratch files
-_tmp*
-_temp*
-.version
-
-AGENTS-README-FIRST.yaml
-
-# MCP Data
+# MCP server marker files (runtime artifacts for agent port discovery)
+.mcp-server.yaml
+.mcp-server.json
+.mcpServer/
+.mcpSession/
+
+# SQLite database files (runtime data)
+*.db
+*.db-shm
+*.db-wal
+
+# Build / publish output
+_publish/
+_publish-launcher/
+_site/
+
+# Local scratch files
+_tmp*
+_temp*
+.version
+
+AGENTS-README-FIRST.yaml
+
+# MCP Data
 mcp-data/
 /src/McpServer.Support.Mcp/Properties/launchSettings.json
 /src/McpServer.AgentFramework.SampleHost/Properties/launchSettings.json
+
+# Local workspace bootstrap marker (per-checkout, not source)
+todo-bootstrap.marker
+
+# Local scratch / test cache
+/cache/

.markdown-link-check.json

@@ -0,0 +1,12 @@
+{
+  "ignorePatterns": [
+    { "pattern": "^http://localhost" },
+    { "pattern": "^http://PAYTON-" },
+    { "pattern": "^https?://nuke\\.build/?$" }
+  ],
+  "replacementPatterns": [],
+  "retryOn429": true,
+  "retryCount": 3,
+  "fallbackRetryDelay": "30s",
+  "aliveStatusCodes": [200, 206, 301, 302, 308, 401, 403, 429]
+}

.markdownlint-cli2.yaml

@@ -11,3 +11,11 @@ config:
   MD040: false
   MD042: false
   MD060: false
+  MD024:
+    siblings_only: true
+ignores:
+  # Server-generated wiki export: shape is controlled by RequirementsDocumentService
+  # and regenerated on every requirements ingest, so hand-edits never survive.
+  # Lint coverage for the same content already runs on the source docs under
+  # docs/Project/{Functional,Technical,Testing}-Requirements.md.
+  - "docs/Project/wiki/**"

.nuke/build.schema.json

@@ -37,6 +37,7 @@
         "Test",
         "TestGraphRagSmoke",
         "TestMultiInstance",
+        "UpdateService",
         "ValidateConfig",
         "ValidateTraceability"
       ]
@@ -140,6 +141,10 @@
           "type": "string",
           "description": "GraphRAG query for smoke test"
         },
+        "InstallPath": {
+          "type": "string",
+          "description": "Service installation directory (default: C:\\ProgramData\\McpServer)"
+        },
         "Instance": {
           "type": "string",
           "description": "MCP instance name from appsettings"
@@ -156,14 +161,35 @@
           "type": "string",
           "description": "Package version for NuGet pack (defaults to GitVersion output)"
         },
+        "Port": {
+          "type": "integer",
+          "description": "HTTP port for the service (default: 7147)",
+          "format": "int32"
+        },
         "Publisher": {
           "type": "string",
           "description": "MSIX publisher identity"
         },
+        "PublishSource": {
+          "type": "string",
+          "description": "Path to pre-built publish output (used with --skip-build)"
+        },
         "SecondInstance": {
           "type": "string",
           "description": "Second MCP instance name"
         },
+        "ServiceName": {
+          "type": "string",
+          "description": "Windows service name (default: McpServer)"
+        },
+        "SkipBuild": {
+          "type": "boolean",
+          "description": "Skip build — use existing publish output from --publish-source"
+        },
+        "SkipVersionBump": {
+          "type": "boolean",
+          "description": "Skip GitVersion.yml patch version bump"
+        },
         "Solution": {
           "type": "string",
           "description": "Path to a solution file that is automatically loaded"

AGENTS.md

@@ -10,9 +10,9 @@ On every subsequent user message:
 1. Follow `AGENTS-README-FIRST.yaml` for specific operational instructions.
 2. Complete the user's request.
 
-## Rules
-
-1. `templates/prompt-templates.yaml` (`default-marker-prompt`) is the source of truth for specific agent instructions. `AGENTS-README-FIRST.yaml` is the rendered runtime instruction set.
+## Rules
+
+1. `templates/prompt-templates.yaml` (`default-marker-prompt`) is the source of truth for specific agent instructions. `AGENTS-README-FIRST.yaml` is the rendered runtime instruction set.
 2. Keep this file focused on durable workspace policy and conventions; avoid duplicating marker-file operational procedures.
 3. Use helper modules for session log and TODO operations. Do not make raw API calls.
 4. Persist session log updates immediately after each meaningful change (turn creation, action append, decision, requirement, blocker, file/context update). Do not defer saves.
@@ -21,12 +21,16 @@ On every subsequent user message:
 7. Use **only `pwsh.exe`** for shell commands and script execution; do not use `powershell.exe`.
 8. When you need API schemas, module examples, or compliance rules, load them from `docs/context/` or use `context_search`.
 9. Do not fabricate information. If you made a mistake, acknowledge it. Distinguish facts from speculation.
-10. Prioritize correctness over speed. Do not ship code you have not verified compiles and is logically sound.
-11. When writing session logs or other audit records, agents must identify themselves accurately using their real agent identity in Pascal-Case. Do not use placeholder, legacy, or misleading sourceType values.
-
-## Where Things Live
-
-- `AGENTS-README-FIRST.yaml` — connection details, API key, workspace config (regenerated on server start)
+10. Prioritize correctness over speed. Do not ship code you have not verified compiles and is logically sound.
+11. When writing session logs or other audit records, agents must identify themselves accurately using their real agent identity in Pascal-Case. Do not use placeholder, legacy, or misleading sourceType values.
+
+## Byrd Test Gate
+
+The canonical process is `docs/Development-Process-draft-v3.md`. To leave a Byrd implementation slice, the entire unit test suite for the current iteration and previous iterations must be completely passing. In this workspace, skipped tests are not passing tests: a validation gate requires zero failures and zero skips in the executed scope. Tests should directly track progress; deferred work belongs in MCP TODO/requirements state until that slice starts, not in skipped test placeholders.
+
+## Where Things Live
+
+- `AGENTS-README-FIRST.yaml` — connection details, API key, workspace config (regenerated on server start)
 - `.github/copilot-instructions.md` — build/test commands, architecture overview, coding conventions
 - `docs/context/` — on-demand reference docs (schemas, module docs, compliance rules, action types)
 - `docs/Project/` — requirements docs, TODO.yaml, mapping matrices