v0.13.0

.dependency-cruiser-known-violations.json

@@ -0,0 +1 @@
+[]

.dependency-cruiser.cjs

@@ -0,0 +1,145 @@
+// Enforces the agent-analyzability import graph: the layer DAG and no-cycles
+// invariant from docs/agent-analyzability.md. `npm run arch:check` runs this.
+// Layer paths (downward-only imports):
+//   4 CLI       src/cli/**, src/cli.ts
+//   3 Runtime   src/runtime/**            (may reuse compile only through the
+//                                          single public entry src/transpiler.ts)
+//   2 Compile   src/transpile/**, src/transpiler.ts
+//   1 Parse/fmt src/parse/**, src/parser.ts, src/format/**
+//   0 Shared    src/types.ts, src/errors.ts, src/diagnostics.ts, src/version.ts,
+//               src/env-reserved.ts, src/inline-script-name.ts
+// The table in docs/agent-analyzability.md is authoritative; keep these in sync.
+
+const LAYER0 =
+  "^src/(types|errors|diagnostics|version|env-reserved|inline-script-name)\\.ts$";
+const LAYER1 = "^src/(parse/|parser\\.ts$|format/)";
+const LAYER2 = "^src/(transpile/|transpiler\\.ts$)";
+const LAYER3 = "^src/runtime/";
+const LAYER4 = "^src/(cli/|cli\\.ts$)";
+
+// CLI slice isolation: these vertical slices must not import each other's
+// private files. Cross-slice reuse goes through src/cli/shared/** or lower-layer
+// public entries. See docs/agent-analyzability.md "CLI slice isolation".
+// `commands` is the composition root: it wires the other slices together, so it
+// is allowed to import them. CLI_PEER_SLICE (commands excluded) is the set of
+// slices that must NOT import each other — peer coupling is the real
+// analyzability problem the rule targets.
+const CLI_SLICE = "^src/cli/(commands|run|serve|mcp|exec|telemetry)/";
+const CLI_PEER_SLICE = "^src/cli/(run|serve|mcp|exec|telemetry)/";
+
+module.exports = {
+  forbidden: [
+    {
+      name: "no-circular",
+      comment:
+        "Cycles break the 'direct deps' interfaces suffice' analyzability story: each side needs the other's body.",
+      severity: "error",
+      from: {},
+      to: { circular: true },
+    },
+    {
+      name: "layer0-shared-leaf-no-upward",
+      comment:
+        "Shared leaf (layer 0) may import only other layer-0 files, never parse/format/transpile/runtime/cli.",
+      severity: "error",
+      from: { path: LAYER0 },
+      to: { path: `${LAYER1}|${LAYER2}|${LAYER3}|${LAYER4}` },
+    },
+    {
+      name: "layer1-parse-format-no-upward",
+      comment:
+        "Parse/format (layer 1) may import only layer 0, never transpile/runtime/cli.",
+      severity: "error",
+      from: { path: LAYER1 },
+      to: { path: `${LAYER2}|${LAYER3}|${LAYER4}` },
+    },
+    {
+      name: "layer2-transpile-no-upward",
+      comment:
+        "Compile (layer 2) must not import runtime or cli (generalizes no-runtime-imports.test.ts).",
+      severity: "error",
+      from: { path: LAYER2 },
+      to: { path: `${LAYER3}|${LAYER4}` },
+    },
+    {
+      name: "layer3-runtime-no-cli",
+      comment: "Runtime (layer 3) must not import cli (layer 4).",
+      severity: "error",
+      from: { path: LAYER3 },
+      to: { path: LAYER4 },
+    },
+    {
+      name: "layer3-runtime-only-transpile-public-graph",
+      comment:
+        "Runtime may reuse the transpile package only through its single public entry (src/transpiler.ts, which re-exports the module-graph API), never src/transpile/** internals (validators, emit, module-graph.ts, etc.).",
+      severity: "error",
+      from: { path: LAYER3 },
+      to: { path: "^src/transpile/" },
+    },
+    {
+      name: "no-deep-imports-into-parse",
+      comment:
+        "Parse is a deep module: code OUTSIDE the parse package imports only its public entry (src/parser.ts), never src/parse/** internals. Add a named re-export to src/parser.ts instead of reaching in.",
+      severity: "error",
+      from: { pathNot: "^src/(parse/|parser\\.ts$)" },
+      to: { path: "^src/parse/" },
+    },
+    {
+      name: "no-deep-imports-into-transpile",
+      comment:
+        "Transpile is a deep module: code OUTSIDE the transpile package imports only its single public entry (src/transpiler.ts, which re-exports the module-graph API), never module-graph/validator/emit/build internals. Add a named re-export to src/transpiler.ts instead of reaching in.",
+      severity: "error",
+      from: { pathNot: "^src/(transpile/|transpiler\\.ts$)" },
+      to: { path: "^src/transpile/" },
+    },
+    {
+      name: "no-deep-imports-into-runtime",
+      comment:
+        "Runtime is a deep module: code OUTSIDE the runtime package imports only its public entries — src/runtime/index.ts (production surface) or src/runtime/testing.ts (named test seams for cross-package *.test.ts) — never src/runtime/** internals (docker, docker-inplace, embedded-assets, kernel/*). Add a named re-export to src/runtime/index.ts (production) or src/runtime/testing.ts (test-only seams) instead of reaching in.",
+      severity: "error",
+      from: { pathNot: "^src/runtime/" },
+      to: { path: "^src/runtime/", pathNot: "^src/runtime/(index|testing)\\.ts$" },
+    },
+    {
+      name: "no-deep-imports-into-format",
+      comment:
+        "Format is a deep module: code OUTSIDE the format package imports only its public entry (src/format/index.ts), never src/format/** internals (emit.ts). Add a named re-export to src/format/index.ts instead of reaching in.",
+      severity: "error",
+      from: { pathNot: "^src/format/" },
+      to: { path: "^src/format/", pathNot: "^src/format/index\\.ts$" },
+    },
+    {
+      name: "no-cross-cli-slice-imports",
+      comment:
+        "Peer CLI slices (run/serve/mcp/exec/telemetry) are vertical features that must not import each other's private files. Cross-slice reuse goes through src/cli/shared/** or a lower-layer public entry. `commands` is the composition root and is deliberately absent from `from` (CLI_PEER_SLICE): it may import any slice to wire them together. The $1 backreference lets same-slice imports through: to.pathNot excludes the slice captured in from.path.",
+      severity: "error",
+      from: { path: CLI_PEER_SLICE },
+      to: { path: CLI_SLICE, pathNot: "^src/cli/$1/" },
+    },
+    {
+      name: "no-orphans",
+      comment:
+        "Orphan modules (no incoming or outgoing deps) are usually dead code or a missing wiring.",
+      severity: "warn",
+      from: {
+        orphan: true,
+        pathNot: [
+          "\\.d\\.ts$",
+          "(^|/)tsconfig\\.json$",
+          "\\.test\\.ts$",
+          "\\.acceptance\\.test\\.ts$",
+        ],
+      },
+      to: {},
+    },
+  ],
+  options: {
+    doNotFollow: { path: "node_modules" },
+    tsConfig: { fileName: "tsconfig.json" },
+    tsPreCompilationDeps: true,
+    enhancedResolveOptions: {
+      exportsFields: ["exports"],
+      conditionNames: ["import", "require", "node", "default", "types"],
+    },
+  },
+};

.github/workflows/ci.yml

@@ -20,6 +20,12 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Enforce agent-analyzability import graph (layer DAG, no cycles)
+        run: npm run arch:check
+
+      - name: Enforce agent-analyzability caps (max-dependencies, max-lines)
+        run: npm run lint
+
       - name: Run core test suite (unit and acceptance)
         run: npm test
 
@@ -268,6 +274,11 @@ jobs:
           set -euo pipefail
           export DEBIAN_FRONTEND=noninteractive
           export JAIPH_UNSAFE=true
+          # wsl.exe does not forward the parent runner's env into this Linux
+          # session, so CI (which docs/install treats as "trusted toolchain,
+          # checksum-only OK when minisign is absent") must be re-set here —
+          # this WSL shell IS the CI runner, just one hop removed.
+          export CI=true
           SUDO=
           if [ "$(id -u)" -ne 0 ]; then
             SUDO=sudo

.github/workflows/nightly-engineer.yml

@@ -2,18 +2,6 @@ name: Nightly Engineer Run
 
 on:
   workflow_dispatch:
-    inputs:
-      engineer_type:
-        description: "Engineer role (auto uses task classification)"
-        required: false
-        default: "auto"
-        type: choice
-        options:
-          - auto
-          - surgical
-          - reductionist
-          - optimizer
-          - stabilizer
 
 permissions:
   contents: write
@@ -83,13 +71,9 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-
-          engineer_type="${{ inputs.engineer_type }}"
-          if [ "${engineer_type}" = "auto" ]; then
-            ./.jaiph/engineer.jh
-          else
-            ./.jaiph/engineer.jh -- "${engineer_type}"
-          fi
+          # Queue-driven entry: picks first #dev-ready QUEUE.md task and
+          # auto-classifies the engineer role (no role CLI arg).
+          ./.jaiph/engineer.jh
 
       - name: Create worktree patch artifact
         if: always()
@@ -190,6 +174,6 @@ jobs:
           Automated engineer run from workflow dispatch.
 
           - Base branch: `nightly`
-          - Engineer type: `${{ inputs.engineer_type }}`
+          - Entry: queue-driven `.jaiph/engineer.jh` (auto-classified role)
           EOF
           )" --head "${branch_name}" --base nightly

.github/workflows/release.yml

@@ -202,10 +202,11 @@ jobs:
           set -euo pipefail
           rm -f SHA256SUMS.minisig
           if [ -z "${MINISIGN_SECRET_KEY}" ]; then
-            echo "MINISIGN_SECRET_KEY secret is not set — skipping detached signature." >&2
-            echo "Set the secret to enable signed releases (see docs/contributing.md)." >&2
-            echo "Installers fail closed without SHA256SUMS.minisig; do not upload an empty stub" >&2
-            echo "(GitHub rejects 0-byte release assets with HTTP 400 Bad Content-Length)." >&2
+            echo "MINISIGN_SECRET_KEY secret is not set — refusing to publish an unsigned release." >&2
+            echo "Installers fail closed without SHA256SUMS.minisig (finding M-5): publishing" >&2
+            echo "unsigned would strip the only out-of-band integrity check for every consumer." >&2
+            echo "Set the MINISIGN_SECRET_KEY secret to enable signed releases (docs/contributing.md)." >&2
+            exit 1
           else
             command -v minisign >/dev/null
             key_file="$(mktemp)"

.jaiph/engineer.jh

@@ -1,8 +1,14 @@
 #!/usr/bin/env jaiph
 
 #
-# Picks the first pending task from QUEUE.md, implements it, verifies CI,
-# updates docs, removes from queue, and publishes a workspace patch artifact.
+# Implement a task: code, CI, docs, commit patch.
+#
+# CLI / overnight (queue-driven):
+#   jaiph run .jaiph/engineer.jh
+#   → default → implement_from_queue (first #dev-ready QUEUE.md task).
+#
+# Hub / serve / mcp (task parameter, no QUEUE.md):
+#   export workflow implement_from_task(task) — used by .jaiph/main.jh engineer(task)
 #
 import "jaiphlang/artifacts" as artifacts
 import "jaiphlang/claude" as claude
@@ -33,15 +39,20 @@ const safety_constraints = """
     Nested sessions share runtime resources and can crash active sessions.
   - Do not attempt to bypass nested-session guards (for example by unsetting
     environment variables such as CLAUDECODE).
+  - Do not modify QUEUE.md in any way (no deleting the current task, no
+    rewriting headers/bodies, no reordering). QUEUE.md process rule 4 is
+    for orchestration only: after a successful implement, the workflow calls
+    queue.remove_completed_task. If you believe a task is done, finish
+    acceptance work and stop — do not edit the queue file yourself.
   - Any violation of these constraints is an immediate task failure; stop and report.
 """
 
 const definition_of_done = """
-  Definition of done (QUEUE.md rule 7, verbatim):
-  "Acceptance criteria are non-negotiable. A task is not done until every
+  Definition of done:
+  Acceptance criteria are non-negotiable. A task is not done until every
   acceptance bullet is verified by a test that fails when the contract is
-  violated. 'It works on my machine' or 'the existing tests pass' is not
-  acceptance."
+  violated. "It works on my machine" or "the existing tests pass" is not
+  acceptance.
 """
 
 const code_philosophy = """
@@ -71,6 +82,17 @@ const code_philosophy = """
      logs, or platform-dependent text) and add an inline comment explaining why.
   9. Source code and docs/architecture.md are the single source of truth. Don't trust
      documentation blindly.
+  10. Agent analyzability (import graph). Before changing any src/ import
+     structure, read docs/agent-analyzability.md. Import a package only through
+     its public entry point (e.g. src/parser.ts, src/format/index.ts,
+     src/transpiler.ts, src/runtime/index.ts, src/cli/index.ts) — never reach
+     into another package's private files. Respect the layer DAG: imports point
+     only downward (CLI → Runtime → Compile → Parse/format → Shared leaf); lower
+     layers never import higher ones. Keep files ≤ ~400 lines and low fan-out
+     (≤ 8 runtime imports per file); prefer splitting into sibling files over
+     raising a cap. When package.json defines them, run npm run arch:check and
+     npm run lint in addition to npm run build and npm test; fix any new
+     violations before continuing.
 """
 
 const output_criteria = """
@@ -207,7 +229,6 @@ workflow classify_role(task) {
   config {
     agent.model = "sonnet"
   }
-
   const result = prompt """
     ${classification_prompt}
 
@@ -236,7 +257,6 @@ workflow implement(task, role_name) {
   config {
     agent.model = "opus"
   }
-
   run task_text_has_header(task) catch (err) {
     fail "Provided task does not contain a '## [text]' header"
   }
@@ -262,8 +282,9 @@ workflow implement(task, role_name) {
     - Following the codebase's existing style and conventions precisely.
     - Following the code philosophy above for all new and modified code.
     - Adding or updating tests as needed for acceptance criteria.
-    - Running npm run build, npm test, and npm run test:e2e; fix any failures
-      before continuing.
+    - Running npm run build, npm test, and npm run test:e2e; and, when
+      package.json defines them, npm run arch:check and npm run lint; fix any
+      failures before continuing.
     - Ensuring all acceptance criteria in the task are met.
 
     ${definition_of_done}
@@ -300,27 +321,58 @@ workflow implement(task, role_name) {
   """
 }
 
-workflow default(name) {
-  # ensure git.is_clean
+# Shared post-implement path: CI, docs parity from the task text, commit, artifact.
+# Callers that touch QUEUE.md must do so before this (so the commit includes it).
+workflow verify_docs_and_commit(task) {
+  run ci.ensure_ci_passes()
+  run docs.update_from_task(task)
+  const patch_file = run git.commit(task)
+  run artifacts.save(patch_file)
+  return patch_file
+}
+
+# Task-parameter entry for serve/mcp hub. Does not read or write QUEUE.md.
+export workflow implement_from_task(task) {
+  run common.arg_nonempty(task) catch (err) {
+    fail "engineer.implement_from_task requires a non-empty task parameter (markdown with a ## header)"
+  }
+
   run claude.ensure_usage()
-  const task = run queue.get_first_task()
+
   const task_header = run first_line_task(task)
+  log "Implementing task: ${task_header}"
+
+  const role_name = run classify_role(task)
+  log "Role: ${role_name}"
+
+  run implement(task, role_name)
+
+  const patch_file = run verify_docs_and_commit(task)
+  log "Patch file: ${patch_file}"
+  return patch_file
+}
+
+# Queue-driven entry for CLI / overnight loops. Always auto-classifies the role.
+export workflow implement_from_queue() {
+  run claude.ensure_usage()
+
+  const task = run queue.get_first_task()
   ensure queue.task_is_dev_ready(task)
+  const task_header = run first_line_task(task)
   log "Implementing task: ${task_header}"
 
-  const role_name = match name {
-    "" => run classify_role(task)
-    _ => name
-  }
+  const role_name = run classify_role(task)
   log "Role: ${role_name}"
 
   run implement(task, role_name)
 
-  run ci.ensure_ci_passes()
-  run docs.update_from_task(task)
   run queue.remove_completed_task(task_header)
 
-  const patch_file = run git.commit(task)
-  run artifacts.save(patch_file)
+  const patch_file = run verify_docs_and_commit(task)
+  log "Patch file: ${patch_file}"
   return patch_file
 }
+
+workflow default() {
+  return run implement_from_queue()
+}