archgen-mcp 0.0.6 → 0.1.0

package/README.md

@@ -4,13 +4,12 @@ The MCP server for [archgen](https://github.com/akashmaurya99/archgen) — it
 owns **every** deterministic capability in the archgen workflow.
 
 The archgen skill is orchestration guidance for an agent; this server is the
-runtime it drives. One implementation, three ways in:
+runtime it drives. One implementation, two ways in:
 
 | Consumer | How it reaches the server |
 |---|---|
-| Coding agents | MCP over stdio — 10 domain tools |
+| Coding agents | MCP over stdio — 8 domain tools + `archgen_help` |
 | `archgen-skill init` / `install` | `archgen-mcp bootstrap` |
-| The VS Code extension | `archgen-mcp exec <tool> '<json>'` |
 
 ## Install
 
@@ -42,9 +41,8 @@ Requires **Node.js >= 20** (the official MCP SDK v2 floor).
 | `archgen_tasks` | next wave · set status · list · resume snapshot · **contract** (the assembled worker prompt) |
 | `archgen_docs` | navigate markdown artifacts: section index, one section, token map, reference integrity |
 | `archgen_registry` | refresh / read the AGENTS.md features registry |
-| `archgen_codegraph` | install + wire + index CodeGraph and its MCP |
+| `archgen_codegraph` | install CodeGraph if it is missing · wire its MCP · index the project |
 | `archgen_setup` | doctor · bootstrap servers · install/remove the MCP · list harnesses · **harness_info** (a platform's capabilities) |
-| `archgen_ui` | drive the VS Code extension in real time |
 | `archgen_skills` | match / install / load external capability skills |
 | `archgen_refs` | load archgen's own protocol documents — section by section |
 | `archgen_help` | the full briefing for one domain |
@@ -90,7 +88,7 @@ The skill declares the server version it needs:
 ```yaml
 metadata:
   requires:
-    archgen_mcp: ">=0.0.6"
+    archgen_mcp: ">=x.y.z"
 ```
 
 `archgen_setup { action: 'doctor' }` reports a mismatch, `bootstrap` warns
@@ -112,14 +110,21 @@ implementation of any capability, only a second way to reach it.
 
 ## Safety
 
+- The server owns a **boundary**: the directory it was started in. A tool's
+  `projectRoot` argument selects a directory *inside* that boundary — it
+  cannot redefine it, so a model cannot move the edge by naming a different
+  root.
 - Every path argument is resolved against the project root and refused if it
-  escapes; symlinked targets are never written through.
+  escapes; symlinked targets are never written through, and a symlinked
+  *parent* is caught by comparing real paths.
+- The artifact space is anchored to the project: a `.archgen` directory
+  elsewhere on the machine is not this project's artifacts.
 - MCP-config writes are approval-gated (`approve: true` / `--yes`); without
   approval the tool reports its **plan** and writes nothing.
 - A config file that cannot be parsed is reported, never rewritten.
 - Writes are atomic (temp file + rename): readers see old-or-new, never a
-  partial file.
-- UI commands are allowlisted, workspace-scoped, expiring, and idempotent.
+  partial file. A read-modify-write — a status update, a config merge — runs
+  under an exclusive lock, so two workers cannot lose each other's change.
 
 ## License
 

package/assets/briefs/investigate.md

@@ -1,22 +1,21 @@
-TASK: Investigate a recurring issue in this repository.
-TRIGGER: the user reports repetitive/recurring issues AFTER implementation waves
-completed. This is NOT a patch-fix task.
+TASK: Investigate a recurring post-execution defect in this repository.
+TRIGGER: User reports repetitive/recurring issues AFTER implementation waves completed. This is NOT a patch-fix task.
+SCOPE: Read-only analysis and reporting (unless the brief explicitly authorizes edits).
 
-DELIVERABLE: all four, or the investigation is incomplete:
-1. ROOT CAUSE — one sentence naming the actual defect (not the symptom).
-2. EVIDENCE — files / lines / repro steps that prove it.
-3. BLAST RADIUS — which tasks and artifacts are affected.
-   Use `archgen_plan { action: 'impact', tasksYaml: <tasks.yaml>, target: <id-or-path> }`.
-4. REMEDIATION — routed through the NORMAL gates: new fix tasks get fresh ids
-   inheriting the affected task's ownership globs.
+DELIVERABLE — all four sections are MANDATORY:
+1. ROOT CAUSE: One sentence identifying the underlying defect (never merely the symptom).
+2. EVIDENCE: Exact file paths, line numbers, and reproduction steps proving the root cause.
+3. BLAST RADIUS: Affected tasks and artifacts computed via `archgen_plan { action: 'impact', tasksYaml: <tasks.yaml>, target: <id-or-path> }`.
+4. REMEDIATION: Proposed fix tasks (new task IDs inheriting affected `file_ownership` globs) routed through normal Verifier, Review, and User gates.
 
 SIZING
-- SMALL scope: the main agent investigates directly.
-- MEDIUM/LARGE: 1–3 investigator sub-agents split by suspected subsystem.
+- SMALL: Main agent investigates directly.
+- MEDIUM / LARGE: 1 investigator by default. Dispatch a 2nd investigator ONLY when the suspected defect spans disjoint subsystems—split strictly by SUBSYSTEM with zero file overlap.
 
 DISCIPLINE
-- Read narrowly around the evidence — no whole-repo sweeps.
-- A patch-fix WITHOUT a root-cause statement is FORBIDDEN under this protocol.
-- Write your notes under .archgen/<slug>/.agent/notes/<topic>.md and your
-  findings under .archgen/<slug>/.agent/reports/investigate-<round>.md.
-  NEVER create ad-hoc folders at the repo root.
+- Read narrowly around evidence paths; avoid whole-repo sweeps.
+- Patch-fixing without a verified root-cause statement is FORBIDDEN.
+- Write working notes to `<slug dir>/.agent/notes/<topic>.md` and final report to `<slug dir>/.agent/reports/investigate-<round>.md`. Never create ad-hoc root directories.
+
+REUSE
+For any follow-up question, verification, or fix touching these files, CONTINUE THIS AGENT'S SESSION rather than spawning a new agent.

package/assets/briefs/review.md

@@ -1,35 +1,47 @@
-TASK: Review the plan in .archgen/<slug>/ READ-ONLY.
-DELIVERABLE: a numbered findings list; each finding = what + where + why.
-You NEVER edit files. You report only.
+TASK: Review the plan in `<slug dir>` READ-ONLY.
+SCOPE: Read-only. NEVER edit files or code; output findings only.
+DELIVERABLE: ONE message in this exact format:
 
-EXAMINE
-- edge cases per module
-- task ordering / parallelization sanity (waves vs real dependencies)
-- cross-module contract mismatches (interfaces, paths, naming)
-- enhancement recommendations
-- documentation completeness
+```
+VERDICT: APPROVE
+COVERAGE:
+| area | status | reason |
+| --- | --- | --- |
+| edge cases per module | PASS | matrices cover empty, boundary, authz, concurrency, retry, and i18n states |
+| task ordering & parallelization | N/A | single sequential wave |
+| cross-module contracts | PASS | every shared interface has a single owning task |
+| enhancement opportunities | PASS | none material for this scope |
+| documentation completeness | PASS | every task has a matching plan section |
+```
 
-CONTEXT TO ATTACH
-- `archgen_plan { action: 'graph', tasksYaml: <tasks.yaml>, format: 'mermaid', status: true }`
-  — the wave-progress render; reviewer reads it to sanity-check ordering.
-- `archgen_docs { action: 'validate', slugDir: <slug dir> }` — the reference
-  integrity result; broken references are findings, not noise.
+or
 
-SIZING
-- SMALL: the main agent's self-review is acceptable when the harness has no
-  reviewer mechanism.
-- MEDIUM: 1 reviewer.
-- LARGE: 1 holistic reviewer on the strongest reasoning tier. A 2nd reviewer
-  ONLY if the plan is genuinely too large for one reviewer's context — split by
-  ARTIFACT/VOLUME (e.g. plans vs docs), never by concern.
+```
+VERDICT: ISSUES
+COVERAGE:
+| area | status | reason |
+| --- | --- | --- |
+| ... all 5 areas above marked PASS, FAIL, or N/A ... |
+FINDINGS:
+1. plans/demo.md § API — response type named inconsistently — client/server contract mismatch — standardize on ApiResponse
+2. docs/prd.md § Grades — FR-GRADE-02 has no owning task — requirement will not be built — add task owning grade-read endpoint
+```
 
-ONE holistic reviewer analyzes ALL issues together: cross-issue reasoning catches
-contradictions a narrow per-concern slice misses, and one reviewer costs far
-fewer tokens than several. NEVER dispatch one sub-agent per individual issue.
+EXAMINE ALL 5 AREAS EVERY RUN:
+1. `edge cases per module`
+2. `task ordering & parallelization` (waves vs real `depends_on` edges)
+3. `cross-module contracts` (interfaces, paths, `naming_conventions`)
+4. `enhancement opportunities`
+5. `documentation completeness`
+
+MANDATORY COVERAGE TABLE: Must appear in every report (even on `APPROVE`). Mark every area `PASS`, `FAIL`, or `N/A` with a 1-line reason. Omitting the table or any row makes the report INCOMPLETE.
+
+SIZING & CONTEXT
+- SMALL: Main-agent self-review permitted if no reviewer sub-agent exists.
+- MEDIUM: 1 holistic reviewer.
+- LARGE: 1 top-tier holistic reviewer (2nd allowed ONLY if context limits force splitting `plans/` vs `docs/`; never split by review area).
+- Use the pre-rendered dependency graph and doc-validation results in the `CONTEXT` block below—make zero `archgen_*` tool calls.
 
 BOUNDS
-- A "more review" approval authorizes EXACTLY ONE additional pass — never a
-  fresh loop, never more reviewers. The stage ends ONLY at zero findings or an
-  explicit user waiver on record.
-- The ORCHESTRATOR fixes the artifacts, re-runs validate + the verifier gate
-  after every change, and re-dispatches. Reviewers never fix.
+- A user "more review" approval grants EXACTLY ONE additional pass. The stage exits only on zero findings or an explicit user waiver.
+- The ORCHESTRATOR applies all fixes and re-runs `validate` + Verifier Gate; reviewers never edit files.

package/assets/briefs/survey.md

@@ -1,22 +1,19 @@
-TASK: Survey this repository to prepare a feature plan for: <feature request>
-DELIVERABLE: write .archgen/<slug>/codebase-map.md containing EXACTLY these
-sections:
-  ## Structure      — top-2-levels folder tree w/ one-line purpose each
-  ## Modules        — table: module | responsibility | key entry points
-  ## Conventions    — naming, error-handling, test layout actually observed
-  ## Affected       — files/modules the feature will touch, with evidence paths
-SCOPE: read-only.
-NAVIGATE: use the CodeGraph MCP tools when available — the index is built once
-at bootstrap and kept live by the server's watcher, so never re-index.
-Otherwise Glob+Grep systematically.
-VERIFY: every claim cites a real path; no guessed APIs. A claim without an
-evidence path is a defect, not a detail.
+TASK: Survey this repository to prepare a feature plan for: `<feature request>`
+SCOPE: Read-only exploration, writing ONLY `<slug dir>/codebase-map.md`.
 
-ACCEPTANCE
-The map is accepted only if every section is present and NON-EMPTY. Anything the
-survey could not determine is written down as an explicit unknown, not omitted —
-an omitted section is indistinguishable from an un-surveyed one.
+DELIVERABLE: Write `<slug dir>/codebase-map.md` containing EXACTLY these four non-empty sections:
+## Structure — Top 2 directory levels with 1-line purpose per folder
+## Modules — Table: `module | responsibility | key entry points`
+## Conventions — Observed file naming, error handling, and test placement patterns
+## Affected — Files/modules impacted by the feature, citing exact evidence paths
 
-THEN: the orchestrator asks ONLY what the survey could not answer. Never
-interrogate the user with what a file already answers — quote the file and ask
-for confirmation instead.
+NAVIGATION & VERIFICATION
+- Prefer CodeGraph MCP tools when `.codegraph/` is present (index is kept live by the watcher—never re-index); otherwise use systematic Glob + Grep.
+- Every architectural claim MUST cite a real repository file path. Never guess APIs.
+- Every section must be present and non-empty; document unresolved items as explicit unknowns rather than omitting sections.
+- Downstream rule: The orchestrator will ask the user ONLY what this map could not answer.
+
+SIZING & REUSE
+- SMALL: Main agent surveys in one pass.
+- MEDIUM / LARGE: 1–2 survey agents split strictly by disjoint SUBSYSTEM (zero file overlap).
+- Continue this agent's session for any follow-up questions covering the surveyed subsystem.

package/assets/briefs/verifier.md

@@ -1,44 +1,56 @@
-TASK: Verify this archgen plan before any execution.
-DELIVERABLE: exactly one line — `APPROVE` or `ISSUES:` followed by a numbered list.
-SCOPE: read-only. You NEVER edit files. You report findings only.
+TASK: Verify the archgen plan in `<slug dir>` before execution.
+SCOPE: Read-only. NEVER edit files; report verdict, coverage table, and findings only.
 
-RUN THESE FIRST (the deterministic floor — every one must pass):
-1. `archgen_plan { action: 'verify', tasksYaml: <tasks.yaml>, planDir: <plans dir> }`
-   — must return verdict APPROVE. It checks cycles, dangling refs, same-wave
-   ownership overlap, missing acceptance criteria and plan<->task coverage.
-2. `archgen_docs { action: 'validate', slugDir: <slug dir> }` (when markdown
-   artifacts exist) — must return valid:true. Broken references BLOCK approval.
+STEP 1 — RUN DETERMINISTIC CHECKS FIRST (both must pass):
+1. `archgen_plan { action: 'verify', tasksYaml: <tasks.yaml>, planDir: <plans dir> }` $\rightarrow$ must return `verdict: 'APPROVE'` (validates DAG, dangling refs, wave ownership disjointness, acceptance presence, and bidirectional plan$\leftrightarrow$task coverage).
+2. `archgen_docs { action: 'validate', slugDir: <slug dir> }` (if markdown artifacts exist) $\rightarrow$ must return `valid: true` (zero broken links or heading anchors).
 
-THEN judge what the tools cannot:
-- Are wave boundaries sensible (no artificial serialization)?
-- Do acceptance criteria objectively verify (a command or an observable)?
-- Is edge-case coverage adequate for the scope class of each task?
-- Is code-standards compliance plausible for the planned structure?
-- CONTRACT-COMPLETENESS sweep — round 1 must confirm OR flag-as-missing every
-  APPLICABLE dimension. Apply a dimension only where the system actually has
-  that concern, but NEVER skip a dimension the system touches:
-  - Functional coverage: every stated requirement has a task + objectively
-    verifiable acceptance.
-  - Security & data protection (if it authenticates, authorizes, encrypts or
-    handles sensitive data): authn/authz flows, session & credential lifecycle,
-    replay/CSRF protection, encryption & privacy boundaries, input validation.
-  - Data integrity: schemas, relationships, validation, migration / back-compat.
-  - State, lifecycle & recovery (if any operation is stateful, long-running or
-    multi-step): checkpointing/resume, idempotency, cleanup, expiry,
-    compensation/rollback semantics.
-  - Resource limits & abuse (if it exposes shared or anonymous resources):
-    quotas, rate limits, retention/deletion, anonymous-abuse controls.
-  - Operational entrypoints: every stack-required build/deploy/test/bootstrap
-    entrypoint is OWNED by some task.
-  - Metric traceability: every PRD success metric maps to a task acceptance
-    criterion with a reproducible command / sample size / data source.
-  - Consistency: cross-contract claims must not contradict each other.
-  These failure classes are the TOP cause of multi-round loops — round 1 MUST
-  sweep the applicable dimensions exhaustively.
+STEP 2 — AUDIT JUDGMENT & CONTRACT COMPLETENESS:
+- Wave boundaries match true dependencies without artificial serialization.
+- Acceptance criteria are objectively verifiable (runnable command or observable output).
+- Edge-case coverage satisfies the scope class (`SMALL` / `MEDIUM` / `LARGE`).
+- Planned structure and naming obey `references/code-standards.md`.
+- **CONTRACT-COMPLETENESS SWEEP** (evaluate every dimension; mark `N/A` only when the system genuinely lacks that surface):
+  1. `functional coverage`: Every requirement maps to a task + objective acceptance check.
+  2. `security & data protection`: Authn/authz flows, session/credential lifecycle, CSRF/replay defense, encryption/privacy boundaries, boundary input validation.
+  3. `data integrity`: Schemas, foreign keys/relations, validation rules, migrations & backward compatibility.
+  4. `state, lifecycle & recovery`: Checkpointing/resume, idempotency, cleanup/TTL, rollback/compensation for stateful or multi-step flows.
+  5. `resource limits & abuse`: Quotas, rate limiting, data retention/deletion, unauthenticated abuse controls.
+  6. `operational entrypoints`: Build, test, deploy, and bootstrap entrypoints are each owned by a task.
+  7. `metric traceability`: Every PRD success metric maps to a task acceptance check with a reproducible command, sample size, or data source.
+  8. `consistency`: Zero contradictions across PRD, `architecture.yaml`, `plans/*.md`, and `tasks.yaml`.
+
+DELIVERABLE — ONE message in this exact format:
+
+```
+VERDICT: APPROVE
+COVERAGE:
+| dimension | status | reason |
+| --- | --- | --- |
+| functional coverage | PASS | all FR IDs map to tasks with runnable checks |
+| security & data protection | N/A | internal CLI with no auth or sensitive data |
+| data integrity | PASS | schemas and migrations are fully typed and owned |
+| state, lifecycle & recovery | FAIL | TASK-07 mutates state without rollback or idempotency |
+| resource limits & abuse | N/A | no shared or public network surface |
+| operational entrypoints | PASS | build, test, and CLI entrypoints have owning tasks |
+| metric traceability | PASS | PRD latency target verified by benchmark acceptance command |
+| consistency | PASS | all contracts align across architecture.yaml and plans |
+```
+
+or
+
+```
+VERDICT: ISSUES
+COVERAGE:
+| dimension | status | reason |
+| --- | --- | --- |
+| ... all 8 dimensions above marked PASS, FAIL, or N/A ... |
+FINDINGS:
+1. tasks.yaml § SCAFFOLD — acceptance #2 has no observable check — worker cannot verify completion — replace with "npm run build exits 0"
+2. plans/demo.md § Risks — config-drift risk has no owning task — mitigation never built — assign mitigation to TASK-01
+```
 
 RULES
-- Run on the STRONGEST reasoning agent the harness offers. NEVER an explore /
-  research / quick / cheap tier: a weak verifier misses real defects AND raises
-  false positives, costing MORE rounds, not fewer.
-- Every finding names the file and the reason. No vague findings.
-- If everything passes, return exactly `APPROVE` and nothing else.
+- **MANDATORY COVERAGE TABLE:** Every report (even `APPROVE`) must include all 8 dimensions marked `PASS`, `FAIL`, or `N/A` with a 1-line reason. Missing rows = INCOMPLETE report (treated as `ISSUES`).
+- **Top-tier holistic agent:** Run on the strongest reasoning model available (never a quick/explore/cheap tier) as ONE holistic agent across the entire plan.
+- **Exhaustive single pass:** Report EVERY defect found in this pass with exact `file § section — defect — impact — fix`. Never hold findings back for a later round.