archgen-mcp 0.0.6 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/README.md +14 -9
  2. package/assets/briefs/investigate.md +16 -17
  3. package/assets/briefs/review.md +41 -29
  4. package/assets/briefs/survey.md +17 -20
  5. package/assets/briefs/verifier.md +52 -40
  6. package/assets/harness-mcp.json +285 -55
  7. package/assets/platform-capabilities.json +387 -71
  8. package/assets/references/artifact-templates.md +68 -219
  9. package/assets/references/interview.md +83 -199
  10. package/assets/references/mcp-and-skills.md +35 -125
  11. package/assets/references/orchestration.md +96 -209
  12. package/assets/references/platforms.md +41 -108
  13. package/assets/skill-registry.json +10 -1
  14. package/assets/templates/adr.md +3 -3
  15. package/assets/templates/architecture.yaml +31 -28
  16. package/assets/templates/edge-matrix.md +8 -8
  17. package/assets/templates/mermaid.md +3 -10
  18. package/assets/templates/prd.md +15 -15
  19. package/assets/templates/tasks.yaml +25 -18
  20. package/bin/archgen-mcp.mjs +6 -4
  21. package/package.json +2 -2
  22. package/src/cli.mjs +1 -2
  23. package/src/context.mjs +55 -45
  24. package/src/core/brief-context.mjs +106 -0
  25. package/src/core/brief-scope.mjs +218 -0
  26. package/src/core/briefs.mjs +121 -0
  27. package/src/core/codegraph-manager.mjs +124 -48
  28. package/src/core/compat.mjs +13 -3
  29. package/src/core/doc-navigator.mjs +127 -24
  30. package/src/core/errors.mjs +1 -1
  31. package/src/core/fs-safety.mjs +98 -10
  32. package/src/core/graph.mjs +8 -3
  33. package/src/core/harness-wiring.mjs +194 -37
  34. package/src/core/jsonc-config.mjs +706 -0
  35. package/src/core/mcp-server-manager.mjs +2 -3
  36. package/src/core/plan-coverage.mjs +43 -6
  37. package/src/core/plan-grapher.mjs +13 -5
  38. package/src/core/platform-caps.mjs +9 -2
  39. package/src/core/resume-snapshot.mjs +16 -4
  40. package/src/core/scope.mjs +39 -5
  41. package/src/core/skill-manager.mjs +181 -13
  42. package/src/core/skill-roots.mjs +92 -0
  43. package/src/core/status-mutator.mjs +34 -3
  44. package/src/core/tokens.mjs +78 -0
  45. package/src/core/validator.mjs +16 -3
  46. package/src/core/verifier.mjs +3 -9
  47. package/src/core/worker-contract.mjs +161 -20
  48. package/src/core/yaml.mjs +31 -6
  49. package/src/server.mjs +0 -3
  50. package/src/tools/_register.mjs +5 -4
  51. package/src/tools/codegraph.mjs +0 -2
  52. package/src/tools/docs.mjs +6 -6
  53. package/src/tools/help.mjs +18 -35
  54. package/src/tools/plan.mjs +58 -7
  55. package/src/tools/setup.mjs +7 -3
  56. package/src/tools/skills.mjs +67 -5
  57. package/src/tools/tasks.mjs +82 -23
  58. package/src/core/ui-channel.mjs +0 -171
  59. package/src/tools/ui.mjs +0 -67
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": 2,
2
+ "version": 3,
3
3
  "_readme": [
4
4
  "Capability-skill registry — the SINGLE source of truth for which external",
5
5
  "skill a task needs, where it comes from, and how it is installed.",
@@ -35,6 +35,7 @@
35
35
  "skills": [
36
36
  {
37
37
  "id": "ui-baseline",
38
+ "domain": "Design",
38
39
  "slug": "baseline-ui",
39
40
  "family": "ui-skills",
40
41
  "repo": "ibelick/ui-skills",
@@ -44,6 +45,7 @@
44
45
  },
45
46
  {
46
47
  "id": "ui-motion",
48
+ "domain": "Motion",
47
49
  "slug": "fixing-motion-performance",
48
50
  "family": "ui-skills",
49
51
  "repo": "ibelick/ui-skills",
@@ -53,6 +55,7 @@
53
55
  },
54
56
  {
55
57
  "id": "ui-interaction",
58
+ "domain": "Accessibility",
56
59
  "slug": "fixing-accessibility",
57
60
  "family": "ui-skills",
58
61
  "repo": "ibelick/ui-skills",
@@ -62,6 +65,7 @@
62
65
  },
63
66
  {
64
67
  "id": "ui-metadata",
68
+ "domain": "Metadata",
65
69
  "slug": "fixing-metadata",
66
70
  "family": "ui-skills",
67
71
  "repo": "ibelick/ui-skills",
@@ -71,6 +75,7 @@
71
75
  },
72
76
  {
73
77
  "id": "ui-improve",
78
+ "domain": "UI polish",
74
79
  "slug": "improve-ui",
75
80
  "family": "ui-skills",
76
81
  "repo": "ibelick/ui-skills",
@@ -80,6 +85,7 @@
80
85
  },
81
86
  {
82
87
  "id": "ui-canvas",
88
+ "domain": "Component canvas",
83
89
  "slug": "component-canvas",
84
90
  "family": "ui-skills",
85
91
  "repo": "ibelick/ui-skills",
@@ -89,6 +95,7 @@
89
95
  },
90
96
  {
91
97
  "id": "design-system",
98
+ "domain": "Design system",
92
99
  "slug": "create-design-md",
93
100
  "family": "ui-skills",
94
101
  "repo": "ibelick/ui-skills",
@@ -98,6 +105,7 @@
98
105
  },
99
106
  {
100
107
  "id": "ui-create-canvas",
108
+ "domain": "Canvas scaffold",
101
109
  "slug": "create-canvas",
102
110
  "family": "ui-skills",
103
111
  "repo": "ibelick/ui-skills",
@@ -109,6 +117,7 @@
109
117
  "routing": {
110
118
  "_readme": "The ui-skills-root entry routes a task to the right specialised skill. It is the fallback when a task touches UI but matches no specific skill above.",
111
119
  "id": "ui-router",
120
+ "domain": "UI",
112
121
  "slug": "ui-skills-root",
113
122
  "family": "ui-skills",
114
123
  "repo": "ibelick/ui-skills",
@@ -1,8 +1,8 @@
1
1
  # NNNN. <decision title>
2
2
  Date: YYYY-MM-DD · Status: accepted
3
3
  ## Context
4
- <forces at play>
4
+ <forces and constraints at play>
5
5
  ## Decision
6
- <what we chose>
6
+ <chosen option and rationale>
7
7
  ## Consequences
8
- <positive / negative / neutral>
8
+ <positive, negative, and neutral trade-offs>
@@ -1,58 +1,61 @@
1
+ # schema_version: 1
2
+ # generator: archgen
3
+ # generated_at: 2026-08-26T09:00:00.000Z
1
4
  name: Acme Shop
2
- slug: acme-shop # becomes .archgen/acme-shop/
5
+ slug: acme-shop # maps to .archgen/acme-shop/
3
6
  stack:
4
7
  language: typescript
5
8
  runtime: node20
6
9
  framework: nextjs
7
10
  database: postgres
8
- structure: # planned folder tree — planned BEFORE code exists
11
+ structure: # planned folder tree defined BEFORE coding
9
12
  - path: src/features/<feature>/
10
- purpose: feature modules (api, internal, tests colocated)
13
+ purpose: feature modules (api, internal, colocated tests)
11
14
  - path: src/shared/
12
- purpose: cross-feature utilities, no feature imports
15
+ purpose: cross-feature utilities; MUST NOT import from features/
13
16
  - path: src/config/
14
- purpose: env parsing + constants
15
- naming_conventions: # filled during generation; referenced by EVERY task
16
- file_naming: kebab-case files, feature folder mirrors module name
17
- dir_layout: "<module>/{api,internal,tests}; shared code only in src/shared/"
18
- symbol_casing: PascalCase types, camelCase functions, SCREAMING_SNAKE env
19
- test_placement: colocated <name>.test.ts next to unit under test
17
+ purpose: typed env parsing + constants
18
+ naming_conventions: # referenced by every task step and file_ownership entry
19
+ file_naming: kebab-case files; feature folder matches module name
20
+ dir_layout: "<module>/{api,internal,tests}; shared utilities in src/shared/ only"
21
+ symbol_casing: PascalCase types, camelCase functions, SCREAMING_SNAKE env vars
22
+ test_placement: colocated <name>.test.ts beside unit under test
20
23
  modules:
21
24
  - name: catalog
22
25
  responsibility: product browsing + search
23
26
  owns: ["src/features/catalog/**"]
24
- depends_on_modules: [] # acyclic; drives task depends_on edges
25
- key_interfaces: # what OTHER modules may import — nothing else
27
+ depends_on_modules: [] # DAG; drives task depends_on edges
28
+ key_interfaces: # ONLY exports other modules may import
26
29
  - CatalogApi (src/features/catalog/api/index.ts)
27
30
  - name: checkout
28
- responsibility: cart → payment orchestration
31
+ responsibility: cart -> payment orchestration
29
32
  owns: ["src/features/checkout/**"]
30
33
  depends_on_modules: [catalog]
31
34
  key_interfaces:
32
35
  - CheckoutApi (src/features/checkout/api/index.ts)
33
- data_contracts: # schemas/entities; field tables, not prose
36
+ data_contracts:
34
37
  orders:
35
- storage: postgres table orders (migration migrations/NNNN_orders.sql)
38
+ storage: postgres table orders (migrations/NNNN_orders.sql)
36
39
  fields:
37
- - {field: id, type: uuid, required: true, notes: pk}
38
- - {field: session_id, type: uuid, required: true, notes: fk sessions}
39
- - {field: total_cents, type: integer, required: true, notes: ">= 0"}
40
- - {field: status, type: "enum(pending,paid,failed)", required: true}
41
- - {field: created_at, type: timestamptz, required: true, notes: db default now()}
42
- api_contracts: # endpoint/method/auth/payload/error-shape tables
40
+ - { field: id, type: uuid, required: true, notes: pk }
41
+ - { field: session_id, type: uuid, required: true, notes: fk sessions }
42
+ - { field: total_cents, type: integer, required: true, notes: ">= 0" }
43
+ - { field: status, type: "enum(pending,paid,failed)", required: true }
44
+ - { field: created_at, type: timestamptz, required: true, notes: db default now() }
45
+ api_contracts:
43
46
  payments:
44
47
  - endpoint: /api/checkout/pay
45
48
  method: POST
46
49
  auth: session cookie; 401 when absent
47
- request_payload: {order_id: uuid}
50
+ request_payload: { order_id: uuid }
48
51
  success: "200 {payment_id: uuid, status: paid}"
49
- error_shape: {code: string, message: string, retryable: boolean}
50
- environment_matrix: # vars per env; unparsed vars fail fast in src/config/
51
- - {var: DATABASE_URL, dev: local docker postgres, ci: ephemeral service, prod: secret ref, required: true}
52
- - {var: PAYMENT_API_KEY, dev: stub key, ci: stub key, prod: secret ref, required: true}
53
- decisions: # ADR-lite; full ADRs live in decisions/
52
+ error_shape: { code: string, message: string, retryable: boolean }
53
+ environment_matrix: # unparsed vars fail fast at startup in src/config/
54
+ - { var: DATABASE_URL, dev: local docker postgres, ci: ephemeral service, prod: secret ref, required: true }
55
+ - { var: PAYMENT_API_KEY, dev: stub key, ci: stub key, prod: secret ref, required: true }
56
+ decisions: # summary index; full records live in decisions/NNNN-title.md
54
57
  - id: D1
55
58
  title: Postgres over MongoDB
56
- context: transactional orders + reporting queries
59
+ context: ACID order transactions + relational reporting
57
60
  decision: Postgres 16 with Prisma
58
61
  consequences: schema migrations required per release
@@ -1,8 +1,8 @@
1
- | Case | Input/state | Expected behavior | Covered by |
2
- | ---- | ------------------------------- | ------------------------------------ | ---------- |
3
- | E1 | empty/null: cart with 0 items | 200, total 0, no gateway call | PAY-2#1 |
4
- | E2 | boundary: qty = max allowed 999 | accepted; 1000 rejected with 422 | PAY-2#1 |
5
- | E3 | concurrent: same order paid 2x | idempotency key → single charge | PAY-2#1 |
6
- | E4 | authz denied: expired session | 401 error_shape, no state change | PAY-2#2 |
7
- | E5 | failure/retry: gateway 5xx x3 | backoff retry then PaymentFailed | PAY-2#2 |
8
- | E6 | i18n: locale de-DE, ¥-less cur | EUR formatting, correct decimal comma| PAY-2#3 |
1
+ | Case | Input/state | Expected behavior | Covered by |
2
+ | ---- | ------------------------------- | ------------------------------------- | ---------- |
3
+ | E1 | empty/null: cart with 0 items | 200, total 0, no gateway call | PAY-2#1 |
4
+ | E2 | boundary: qty = max allowed 999 | accepted; 1000 rejected with 422 | PAY-2#1 |
5
+ | E3 | concurrent: same order paid 2x | idempotency key -> single charge | PAY-2#1 |
6
+ | E4 | authz denied: expired session | 401 error_shape, no state mutation | PAY-2#2 |
7
+ | E5 | failure/retry: gateway 5xx x3 | exponential backoff then PaymentFailed| PAY-2#2 |
8
+ | E6 | i18n: locale de-DE, zero-dec ¥ | EUR comma decimal; JPY integer math | PAY-2#4 |
@@ -18,15 +18,9 @@ graph LR
18
18
 
19
19
  ## Per-module diagram (LARGE)
20
20
 
21
- For EACH `modules:` entry in architecture.yaml, one small flowchart of its
22
- internal components plus its `depends_on_modules` edges (arrow points from
23
- consumer to provider). Plus ONE integration diagram wiring all modules —
24
- edges between modules only, no internals. HARD LIMIT: ≤15 nodes per diagram;
25
- split into two diagrams rather than cramming. Internals stay ≤6 nodes per
26
- module.
27
-
28
- Catalog module (internal + inbound depends_on edge):
21
+ Rules: One flowchart per `modules:` entry in `architecture.yaml` showing internal components ($\le 6$ nodes) + inbound `depends_on_modules` edges (consumer $\rightarrow$ provider), plus ONE integration diagram wiring modules as atomic nodes. **Hard limit:** $\le 15$ nodes per diagram.
29
22
 
23
+ Catalog module (internals + inbound `depends_on` edge):
30
24
  ```mermaid
31
25
  graph LR
32
26
  subgraph catalog
@@ -36,8 +30,7 @@ graph LR
36
30
  checkout -.->|depends_on CatalogApi| routes
37
31
  ```
38
32
 
39
- Integration (modules as atoms, mirrors depends_on_modules):
40
-
33
+ Integration (module-level DAG mirroring `depends_on_modules`):
41
34
  ```mermaid
42
35
  graph LR
43
36
  accounts --> catalog
@@ -1,31 +1,31 @@
1
1
  # PRD — <project name>
2
2
 
3
3
  ## Problem statement & goals
4
- - <pain, quantified where possible>
5
- - Goals: <3–5 outcome bullets, each measurable>
4
+ - <quantified user/system pain>
5
+ - Goals: <3–5 measurable outcome bullets>
6
6
 
7
7
  ## Non-goals
8
- - <explicitly out; prevents scope creep mid-execution>
8
+ - <explicit exclusions to prevent scope creep>
9
9
 
10
10
  ## Personas / stakeholders
11
- - <persona>: <need>, <success looks like>
11
+ - <persona>: <core job-to-be-done> -> <measurable success state>
12
12
 
13
- ## Functional requirements — <module-name> (repeat per module)
14
- - FR-<MODULE>-01: <single verifiable behavior statement>
15
- - FR-<MODULE>-02: ...
16
- <!-- ids are immutable once tasks reference them -->
13
+ ## Functional requirements — <module-name> (repeat per module)
14
+ - FR-<MODULE>-01: <single objectively verifiable behavior>
15
+ - FR-<MODULE>-02: <single objectively verifiable behavior>
16
+ <!-- FR IDs are immutable once cited in tasks.yaml -->
17
17
 
18
- ## Non-functional requirements (measurable targets, no adjectives)
18
+ ## Non-functional requirements (concrete numbers mandatory; no adjectives)
19
19
  - Perf: p95 API latency < 300 ms at 50 rps; LCP < 2.5 s
20
- - Security: authz check on every endpoint; no secrets in repo; OWASP top-10 reviewed
21
- - i18n: all user-facing strings externalized; ICU plurals; RTL-safe layouts
22
- - A11y: WCAG 2.1 AA; full keyboard nav; contrast ≥ 4.5:1
20
+ - Security: authz enforced on all routes; zero secrets in repo; OWASP Top 10 mitigated
21
+ - i18n: externalized copy; ICU pluralization; RTL-safe layout
22
+ - A11y: WCAG 2.2 AA compliance; full keyboard navigation; contrast >= 4.5:1
23
23
 
24
24
  ## Success metrics
25
- - <metric>: <baseline> → <target> within <window>
25
+ - <metric>: <baseline> -> <target> within <evaluation window>
26
26
 
27
27
  ## Risks & mitigations
28
- - <risk> → <mitigation>, <owner task id or ADR ref>
28
+ - <risk> -> <mitigation>, owned by <task ID or ADR ref>
29
29
 
30
30
  ## Open questions
31
- - <question> — owner <name/role>, blocks <task id | none>
31
+ - <question> — owner: <name/role>, blocks: <task ID | none>
@@ -1,40 +1,47 @@
1
- # comment lines are preserved by archgen_tasks{set_status} — annotate freely
1
+ # schema_version: 1
2
+ # generator: archgen
3
+ # generated_at: 2026-08-26T09:00:00.000Z
4
+ # comment lines are preserved by archgen_tasks{set_status}
2
5
  tasks:
3
- # Core pipeline — do first
6
+ # Wave 1 — Foundation
4
7
  - id: C
5
- title: Scaffold project skeleton + config loading
8
+ title: Scaffold project skeleton + typed config loader
6
9
  depends_on: []
7
- file_ownership: ["src/config/**", "package.json"] # FULL repo-root-relative paths, never bare filenames
10
+ file_ownership: ["src/config/**", "package.json"] # full repo-root-relative paths ONLY
8
11
  acceptance:
9
12
  - "npm run build exits 0"
10
- - "config loads from env with typed schema"
13
+ - "config loads from env and fails fast on missing required vars"
14
+
15
+ # Wave 2 — Core domain
11
16
  - id: B
12
17
  title: Catalog API endpoints
13
18
  depends_on: [C]
14
19
  file_ownership: ["src/features/catalog/**"]
15
20
  acceptance:
16
- - "GET /products returns seeded list"
21
+ - "GET /products returns seeded catalog list with 200 status"
22
+
23
+ # Wave 3 — Feature integration
17
24
  - id: A
18
25
  title: Checkout flow wired to catalog
19
26
  depends_on: [B]
20
27
  parallel_group: wave-final
21
- file_ownership: ["src/features/checkout/**"]
22
- artifacts: ["docs/checkout-flow.md"]
28
+ file_ownership: ["src/features/checkout/**", "docs/checkout-flow.md"]
29
+ artifacts: ["docs/checkout-flow.md"] # must be a subset of file_ownership
23
30
  acceptance:
24
- - "e2e test completes purchase with stub payment"
31
+ - "e2e test completes purchase flow against stub payment gateway"
25
32
 
26
- # LARGE-grade example task (same schema, richer acceptance — sits beside the
27
- # minimal ones above, never replaces them):
33
+ # LARGE-scope task example (traces edge-matrix rows E1-En and PRD FR-* IDs)
28
34
  - id: PAY-2
29
- title: Order payment capture with retry
35
+ title: Order payment capture with exponential backoff retry
30
36
  depends_on: [A]
31
37
  parallel_group: wave-payments
32
38
  file_ownership:
33
- - src/features/checkout/internal/capture.ts # full path per naming_conventions.dir_layout
34
- - src/features/checkout/internal/capture.test.ts # colocated per naming_conventions.test_placement
39
+ - src/features/checkout/internal/capture.ts # per naming_conventions.dir_layout
40
+ - src/features/checkout/internal/capture.test.ts # per naming_conventions.test_placement
41
+ - docs/payment-retry.md
35
42
  artifacts: ["docs/payment-retry.md"]
36
43
  acceptance:
37
- - "capture() sends idempotency key; double submit charges once (E3)"
38
- - "gateway 5xx retries 3x exponential backoff, then raises PaymentFailed (E5)"
39
- - "denied card → 402 with error_shape from ../architecture.yaml api_contracts.payments (FR-PAYMENTS-02)"
40
- - "amounts render via session locale, cents-safe integer math (E6)"
44
+ - "capture() sends idempotency key; duplicate submission charges once (E3)"
45
+ - "gateway 5xx retries 3x with exponential backoff, then raises PaymentFailed (E5)"
46
+ - "declined card returns 402 matching ../architecture.yaml api_contracts.payments.error_shape (FR-PAYMENTS-02)"
47
+ - "currency amounts format via session locale using integer cents math (E6)"
@@ -16,11 +16,13 @@ import { createServer } from '../src/server.mjs';
16
16
  import { runCli } from '../src/cli.mjs';
17
17
 
18
18
  const argv = process.argv.slice(2);
19
- const CLI_COMMANDS = new Set(['exec', 'bootstrap', 'doctor', 'uninstall-mcp', 'help']);
20
19
  const first = argv[0];
21
- // 'serve' is the default, but any explicit CLI command OR any flag means the
22
- // caller wants the command-line facade, not the JSON-RPC stream.
23
- const wantsCli = first === 'serve' ? false : CLI_COMMANDS.has(first) || (first !== undefined && first.startsWith('-'));
20
+ // The stdio server is the DEFAULT, and only for no argument at all or the
21
+ // explicit word 'serve'. Anything else is the command-line facade — a known
22
+ // command, a flag, or an unknown word, which must say "unknown command"
23
+ // rather than silently start a server and block on stdin (which is what it
24
+ // used to do, making the mistake look like a hang).
25
+ const wantsCli = !(first === undefined || first === 'serve');
24
26
 
25
27
  if (wantsCli) {
26
28
  const code = await runCli(argv);
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "archgen-mcp",
3
- "version": "0.0.6",
4
- "description": "MCP server for archgen \u2014 the single runtime that owns architecture-plan validation, wave execution, artifact navigation, CodeGraph bootstrap, harness MCP wiring, and live UI control for coding agents.",
3
+ "version": "0.1.0",
4
+ "description": "MCP server for archgen \u2014 the single runtime that owns architecture-plan validation, wave execution, artifact navigation, CodeGraph bootstrap and harness MCP wiring for coding agents.",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "bin": {
package/src/cli.mjs CHANGED
@@ -1,10 +1,9 @@
1
1
  // cli.mjs — the command-line facade over the MCP server.
2
2
  //
3
- // WHY A CLI FACADE: three consumers need the same capability, and they must
3
+ // WHY A CLI FACADE: two consumers need the same capability, and they must
4
4
  // never drift apart:
5
5
  // - agents -> MCP over stdio
6
6
  // - the CLI installer -> `archgen-mcp bootstrap`
7
- // - the VS Code extension -> `archgen-mcp exec archgen_tasks '{"action":"next",…}'`
8
7
  //
9
8
  // `exec` runs the SAME tool handlers the MCP server exposes — there is no
10
9
  // second implementation of any capability, only a second way to reach it.
package/src/context.mjs CHANGED
@@ -11,7 +11,8 @@ import { homedir } from 'node:os';
11
11
  import { dirname, isAbsolute, join, resolve } from 'node:path';
12
12
  import { fileURLToPath } from 'node:url';
13
13
  import { invalidInput } from './core/errors.mjs';
14
- import { containPath } from './core/fs-safety.mjs';
14
+ import { assertWithinRoot, containPath } from './core/fs-safety.mjs';
15
+ import { GLOBAL_SKILL_ROOTS, PROJECT_SKILL_ROOTS, skillSearchPaths } from './core/skill-roots.mjs';
15
16
 
16
17
  const HERE = dirname(fileURLToPath(import.meta.url));
17
18
 
@@ -39,34 +40,14 @@ export function serverVersion() {
39
40
  /**
40
41
  * Skill install locations, project-local first.
41
42
  *
42
- * Mirrors references/platforms.md § "Skill install paths". A drift test
43
- * (packages/mcp/test/core/skill-resolution.test.mjs) asserts this list stays
44
- * in sync with the doc, so the two can never silently diverge.
43
+ * Mirrors references/platforms.md § "Skill install paths". The canonical list
44
+ * lives in core/skill-roots.mjs so the archgen skill and the CAPABILITY
45
+ * skills are resolved against the same roots — one list, one answer.
45
46
  */
46
- export const PROJECT_SKILL_DIRS = [
47
- '.agents/skills/archgen',
48
- '.claude/skills/archgen',
49
- '.github/skills/archgen',
50
- '.gemini/skills/archgen',
51
- '.cursor/skills/archgen',
52
- '.opencode/skills/archgen',
53
- '.codex/skills/archgen',
54
- '.kiro/skills/archgen',
55
- '.trae/skills/archgen',
56
- '.windsurf/skills/archgen',
57
- ];
47
+ export const PROJECT_SKILL_DIRS = PROJECT_SKILL_ROOTS.map((r) => join(r, 'archgen'));
58
48
 
59
49
  /** User-global skill locations (same shape, under $HOME). */
60
- export const GLOBAL_SKILL_DIRS = [
61
- '.agents/skills/archgen',
62
- '.claude/skills/archgen',
63
- '.config/opencode/skills/archgen',
64
- '.gemini/skills/archgen',
65
- '.copilot/skills/archgen',
66
- '.codex/skills/archgen',
67
- '.kiro/skills/archgen',
68
- '.trae/skills/archgen',
69
- ];
50
+ export const GLOBAL_SKILL_DIRS = GLOBAL_SKILL_ROOTS.map((r) => join(r, 'archgen'));
70
51
 
71
52
  /**
72
53
  * Locate the installed archgen skill.
@@ -89,23 +70,12 @@ export function resolveSkill(projectRoot, home = homedir(), env = process.env) {
89
70
  if (existsSync(join(abs, 'SKILL.md'))) return { path: abs, version: readSkillVersion(abs), scope: 'override' };
90
71
  }
91
72
 
92
- // Walk UP from the project root: a monorepo may install the skill at its root
93
- // while the agent works in a nested package.
94
- let dir = resolve(projectRoot);
95
- for (;;) {
96
- for (const rel of PROJECT_SKILL_DIRS) {
97
- const abs = join(dir, rel);
98
- if (existsSync(join(abs, 'SKILL.md'))) return { path: abs, version: readSkillVersion(abs), scope: 'project' };
99
- }
100
- const parent = dirname(dir);
101
- if (parent === dir) break;
102
- dir = parent;
103
- }
104
-
105
- if (home) {
106
- for (const rel of GLOBAL_SKILL_DIRS) {
107
- const abs = join(home, rel);
108
- if (existsSync(join(abs, 'SKILL.md'))) return { path: abs, version: readSkillVersion(abs), scope: 'global' };
73
+ // The project chain (walking UP) and the user-global roots come from the
74
+ // ONE skill-root list, so the archgen skill and the capability skills are
75
+ // resolved against the same places.
76
+ for (const candidate of skillSearchPaths(projectRoot, 'archgen', { home })) {
77
+ if (existsSync(join(candidate.dir, 'SKILL.md'))) {
78
+ return { path: candidate.dir, version: readSkillVersion(candidate.dir), scope: candidate.scope };
109
79
  }
110
80
  }
111
81
 
@@ -148,19 +118,59 @@ export function loadAsset(name) {
148
118
 
149
119
  /**
150
120
  * The per-call context: project root + resolved skill + versions.
121
+ *
122
+ * THE ANCHOR. `anchorRoot` is the boundary the server works inside. It is
123
+ * set when the server starts — the directory the server was launched in, or
124
+ * the project the CLI named — and it does NOT change per call.
125
+ *
126
+ * `projectRoot` selects a directory INSIDE the anchor. It is a selector, not
127
+ * a boundary: naming a different root cannot move the edge of what the
128
+ * server may read or write. Before this, every containment check was
129
+ * relative to a root the MODEL chose, so the guard defended nothing — a
130
+ * model that named `/etc` simply moved the boundary to `/etc`.
151
131
  */
152
132
  export class Context {
153
133
  /**
154
- * @param {{projectRoot?: string, home?: string, env?: Record<string, string|undefined>}} [opts]
134
+ * @param {{projectRoot?: string, anchorRoot?: string, home?: string, env?: Record<string, string|undefined>}} [opts]
155
135
  */
156
136
  constructor(opts = {}) {
157
137
  this.env = opts.env ?? process.env;
158
138
  this.home = opts.home ?? homedir();
159
- this.projectRoot = resolve(opts.projectRoot ?? this.env.ARCHGEN_PROJECT_ROOT ?? process.cwd());
139
+ // The anchor is the server's DECLARED root: what the server was started
140
+ // with. The cwd is only the fallback for a server started without one.
141
+ this.anchorRoot = resolve(
142
+ opts.anchorRoot ?? opts.projectRoot ?? this.env.ARCHGEN_PROJECT_ROOT ?? process.cwd(),
143
+ );
144
+ this.projectRoot = resolve(opts.projectRoot ?? this.anchorRoot);
160
145
  this.skill = resolveSkill(this.projectRoot, this.home, this.env);
161
146
  this.serverVersion = serverVersion();
162
147
  }
163
148
 
149
+ /**
150
+ * A context for a directory inside the anchor.
151
+ *
152
+ * The candidate is resolved and proved to be inside the anchor; a path
153
+ * outside it is refused with PERMISSION_DENIED. The returned context
154
+ * keeps the SAME anchor, so containment checks made with it cannot be
155
+ * widened either.
156
+ *
157
+ * @param {string} candidate
158
+ * @returns {Context}
159
+ */
160
+ withProjectRoot(candidate) {
161
+ if (typeof candidate !== 'string' || candidate.trim() === '') {
162
+ throw invalidInput('projectRoot must be a non-empty string', { projectRoot: candidate });
163
+ }
164
+ const abs = resolve(this.anchorRoot, candidate);
165
+ assertWithinRoot(this.anchorRoot, abs);
166
+ return new Context({
167
+ projectRoot: abs,
168
+ anchorRoot: this.anchorRoot,
169
+ env: this.env,
170
+ home: this.home,
171
+ });
172
+ }
173
+
164
174
  /**
165
175
  * Resolve a caller-supplied path and prove it stays inside the project root.
166
176
  * Relative paths are resolved against the project root.
@@ -0,0 +1,106 @@
1
+ // brief-context.mjs — what a dispatch brief carries besides its task.
2
+ //
3
+ // WHY A SEPARATE MODULE: the brief TEMPLATE holds the protocol (what to
4
+ // examine, what to return). The CONTEXT holds the facts (which files exist,
5
+ // which sections they have, what the tools already said). They change for
6
+ // different reasons and at different times, so they are assembled separately
7
+ // and composed once.
8
+ //
9
+ // THE RENDERING RULE: everything here is computed BY THE TOOL, not requested
10
+ // by the orchestrator. The old review brief said "attach the mermaid graph
11
+ // and the docs-validate result", which cost two tool calls per gate round —
12
+ // and the graph call failed on every plan, so the reviewer ran without it.
13
+ // Rendering it once, into the brief, removes the extra calls AND the
14
+ // dependency.
15
+ import { existsSync } from 'node:fs';
16
+ import { join } from 'node:path';
17
+ import { docIndex } from './doc-navigator.mjs';
18
+ import { planGraph } from './plan-grapher.mjs';
19
+
20
+ /**
21
+ * The archgen calls each brief kind is ALLOWED to make.
22
+ *
23
+ * The list is exhaustive on purpose: a sub-agent that runs the archgen tool
24
+ * suite is re-deriving facts the brief already carries, and can drift from
25
+ * the protocol the orchestrator is following.
26
+ */
27
+ const ALLOWED_CALLS = {
28
+ verifier: ["archgen_plan{action:'verify'}", "archgen_docs{action:'validate'}"],
29
+ review: [],
30
+ survey: [],
31
+ investigate: ["archgen_plan{action:'impact'}"],
32
+ };
33
+
34
+ /** The archgen calls each brief kind may make — the single source of truth. */
35
+ export { ALLOWED_CALLS };
36
+
37
+ /**
38
+ * Build the context block for one brief.
39
+ *
40
+ * @param {string} kind the brief kind
41
+ * @param {{slug: string, slugDir: string, plansDir: string, tasksYaml: string}} scope
42
+ * @param {{projectRoot: string}} ctx
43
+ * @returns {{
44
+ * scope: object,
45
+ * allowedCalls: string[],
46
+ * evidence: {files: Array<{path: string, sections: Array<{slug: string, title: string}>}>, fileCount: number}|null,
47
+ * graph: string|null,
48
+ * docsValidation: {valid: boolean, broken: unknown[], warnings: unknown[]}|null,
49
+ * }}
50
+ */
51
+ export function buildBriefContext(kind, scope, ctx) {
52
+ const out = {
53
+ scope,
54
+ allowedCalls: ALLOWED_CALLS[kind] ?? [],
55
+ evidence: null,
56
+ graph: null,
57
+ docsValidation: null,
58
+ };
59
+
60
+ // The evidence map: every markdown artifact under the slug, with its
61
+ // section anchors. A MAP, not a copy — the agent reads the sections it
62
+ // needs and never re-reads the whole plan.
63
+ try {
64
+ if (existsSync(scope.slugDir)) {
65
+ const digest = docIndex(scope.slugDir, { mode: 'digest', projectRoot: ctx.projectRoot });
66
+ const files = (digest.data.files ?? []).map((f) => ({
67
+ path: f.path,
68
+ sections: (f.sections ?? []).map((s) => ({ slug: s.slug, title: s.title })),
69
+ }));
70
+ out.evidence = { files, fileCount: files.length };
71
+ }
72
+ } catch {
73
+ out.evidence = null; // a missing artifact space is not a brief failure
74
+ }
75
+
76
+ // The dependency graph — rendered once, so the reviewer reads it instead of
77
+ // spending a tool call to fetch it.
78
+ try {
79
+ if (existsSync(scope.tasksYaml)) {
80
+ const g = planGraph(scope.tasksYaml, {
81
+ mermaid: true,
82
+ status: true,
83
+ projectRoot: ctx.projectRoot,
84
+ });
85
+ out.graph = typeof g.data === 'string' ? g.data : null;
86
+ }
87
+ } catch {
88
+ out.graph = null; // a plan that cannot be graphed is reported by the verifier
89
+ }
90
+
91
+ // The reference-integrity result — the deterministic floor's second half.
92
+ try {
93
+ if (existsSync(scope.slugDir)) {
94
+ const v = docIndex(scope.slugDir, { mode: 'validate', projectRoot: ctx.projectRoot });
95
+ out.docsValidation = {
96
+ valid: v.data.valid === true,
97
+ broken: v.data.broken ?? [],
98
+ warnings: v.data.warnings ?? [],
99
+ };
100
+ }
101
+ } catch {
102
+ out.docsValidation = null;
103
+ }
104
+
105
+ return out;
106
+ }