mikoshi-construct 0.2.0 → 0.3.0

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "mikoshi-construct",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Bootstrap for AI-native software projects. Start with a proven engineering workflow instead of an empty repository.",
   "author": "Eli Tabrisov",
   "license": "MIT",
-  "homepage": "https://github.com/E1i/mikoshi-construct#readme",
+  "homepage": "https://e1i.github.io/mikoshi-construct/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/E1i/mikoshi-construct.git"
@@ -49,24 +49,28 @@
     "tsup": "^8.5.1",
     "tsx": "^4.23.13",
     "typescript": "^5.9.3",
+    "vitepress": "2.0.0-alpha.20",
     "vitest": "^5.0.0",
     "yaml": "^2.9.1"
   },
   "scripts": {
     "build": "tsup",
+    "changeset": "changeset",
+    "ci": "pnpm run quality",
+    "composition:check": "tsx scripts/composition/check.ts",
+    "composition:render": "tsx scripts/composition/sync-docs.ts",
     "dev": "tsx src/cli.ts",
+    "docs:build": "vitepress build docs",
+    "docs:dev": "vitepress dev docs",
+    "docs:preview": "vitepress preview docs",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
-    "typecheck": "tsc --noEmit",
+    "privacy:check": "tsx scripts/privacy/check.ts",
+    "quality": "pnpm composition:check && pnpm privacy:check && pnpm lint && pnpm typecheck && pnpm test",
+    "release": "pnpm build && changeset publish",
     "test": "vitest run",
     "test:watch": "vitest",
-    "quality": "pnpm composition:check && pnpm privacy:check && pnpm lint && pnpm typecheck && pnpm test",
-    "composition:render": "tsx scripts/composition/sync-docs.ts",
-    "composition:check": "tsx scripts/composition/check.ts",
-    "privacy:check": "tsx scripts/privacy/check.ts",
-    "ci": "pnpm run quality",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "pnpm build && changeset publish"
+    "typecheck": "tsc --noEmit",
+    "version-packages": "changeset version"
   }
 }

package/templates/ai/claude/_claude/commands/plan.md

@@ -12,6 +12,8 @@ Rules:
 - Two to six tasks. Each task is independently verifiable by the harness and leaves the tree green.
 - Each task has two to four acceptance criteria that a harness run or a test can confirm. "Works" is
   not a criterion; "GET /v1/things returns 200 with the `Thing` schema and the contract test passes" is.
+- A criterion is verified by what the task changes itself. If satisfying it needs an action outside the
+  task, it belongs to that task, not this one.
 - Order tasks so the contract and composition changes come first, then implementation, then anything
   that consumes the new behaviour.
 - Classify each task `low`, `medium` or `high` with the rules in `architecture/principles.md`

package/templates/ai/claude/_claude/skills/implement/SKILL.md

@@ -31,6 +31,15 @@ repository's CLAUDE.md and `construct.json`.
    only when a rejected response is expected to be a transient shape error rather than a bad brief.
    The user's `/implement` invocation is the opt-in the tool requires. Note the run identifier the
    Workflow tool reports when it launches the run and again when it completes; step 4 records it.
+   The design step runs inside the ladder, not before it, and its outcome is one of the `attempts`
+   like any other. The statuses a run can return are:
+   - `done` — a rung passed the harness and every design step the run took completed.
+   - `degraded` — a rung passed the harness, but a design step was rejected by the schema and the
+     run continued without it. The result's `effort` is the class that actually executed.
+   - `design incomplete` — a high-effort run whose architect was rejected by the schema. No
+     implementer ran without a spec; the result carries the validator's text in `validationError`.
+   - `failed` — every rung ran and the harness stayed red; `lastFailure` carries the excerpt.
+   - `blocked` — the last rung stopped on a question; `question` carries it verbatim.
 4. Record the run: append one JSON line to `.construct/runs.jsonl` (create the directory if needed)
    with exactly these fields and no others:
    - `run` — the Workflow run identifier from step 3. It is the key `construct cost` joins the entry
@@ -38,13 +47,15 @@ repository's CLAUDE.md and `construct.json`.
      unjoinable, which is the truth about it.
    - `at` — the ISO timestamp.
    - `task` — the task text, first 120 characters.
-   - `effort` — the class you chose in step 1.
-   - `status` — `done`, `failed` or `blocked`, from the result.
-   - `rung` — the effort of the rung that finished: `effort` from the result when it is `done`,
+   - `effort` — the class the run performed: the result's `effort` when it carries one, and only
+     then the class you chose in step 1. A run whose design step did not complete is never written
+     down as `high`; the result has already degraded it.
+   - `status` — the result's status verbatim, one of the five in step 3.
+   - `rung` — the effort of the rung that finished: `effort` from the result when it carries one,
      otherwise the `effort` of the last entry in `attempts`.
    - `attempts` — the result's `attempts` array verbatim; each entry carries its `rung`, `effort`,
-     `outcome` and the `reason` that separates an invalid response shape from a red harness from a
-     blocked report.
+     `outcome` and the `reason` that separates an invalid response shape from a red harness, from a
+     blocked report and from a design the schema rejected.
    - `agents`, `tokens`, `toolUses`, `seconds` — the Workflow tool's own accounting for the run,
      exactly as it reported it. Write `"unknown"` for a token figure it did not report, never `0`.
    The ledger carries counts and reasons only — never a prompt, a response or any other message
@@ -54,7 +65,10 @@ repository's CLAUDE.md and `construct.json`.
    gitignored.
 5. Relay the result: status, the effort rung that succeeded and how many attempts it took, the
    files changed, and the harness tail. When the status is `blocked`, put the architect's or
-   implementer's question to the user verbatim. When `failed`, give the last failure excerpt.
+   implementer's question to the user verbatim. When `failed`, give the last failure excerpt. When
+   `design incomplete`, say that the design step did not complete and give `validationError` as the
+   runtime reported it; when `degraded`, say which design step was rejected and that the reported
+   class is the one that executed, not the one that was requested.
    Unless `construct.json` sets `report.usage` to `false`, end with one usage line for this run,
    from the Workflow tool's own accounting: agents, subagent tokens, tool uses, wall time — so the
    cost of the rung that succeeded is on record next to the result. When `construct` is on the PATH,

package/templates/ai/claude/scripts/construct/implement.workflow.mjs

@@ -2,7 +2,7 @@ export const meta = {
   name: 'implement',
   description: 'Implement a task at low effort, verify with the harness, escalate on repeated failure or ambiguity',
   phases: [
-    { title: 'Design', detail: 'architect, only for high effort or after a blocked or failed attempt' },
+    { title: 'Design', detail: 'architect inside the run, for high effort before the first rung and after a blocked or failed attempt' },
     { title: 'Implement', detail: 'implementer at the current rung' },
     { title: 'Verify', detail: 'harness against the working tree' },
   ],
@@ -53,6 +53,8 @@ const SPEC = {
 }
 
 const DEFAULT_RETRY_LIMIT = 0
+const DESIGN_EFFORT = 'xhigh'
+const EFFORT_WITHOUT_DESIGN = { high: 'medium', xhigh: 'medium' }
 
 const task = args.task
 const acceptance = args.acceptance ?? []
@@ -125,22 +127,58 @@ function implementerPrompt(spec, feedback) {
 
 let spec = null
 let feedback = null
+let designComplete = false
+let designFailed = false
+let designError = ''
 const attempts = []
 
+function performedEffort(effort) {
+  return designComplete ? effort : (EFFORT_WITHOUT_DESIGN[effort] ?? effort)
+}
 
-if (args.effort === 'high') {
+async function design(rung, reason, label) {
   phase('Design')
-  spec = await ask(architectPrompt('The task is classified as high effort; design it before any implementation.'), {
+  const result = await ask(architectPrompt(reason), {
     agentType: 'architect',
-    effort: 'xhigh',
+    effort: DESIGN_EFFORT,
     phase: 'Design',
-    label: 'design',
+    label,
     schema: SPEC,
   })
+  if (result == null) {
+    designComplete = false
+    designFailed = true
+    designError = lastValidationError ?? ''
+    attempts.push({ rung, effort: DESIGN_EFFORT, outcome: 'design schema invalid', reason: designError })
+    log(`${label}: the design step did not complete`)
+    return false
+  }
+  spec = result
+  designComplete = true
+  attempts.push({ rung, effort: DESIGN_EFFORT, outcome: 'designed', reason: '' })
+  return true
+}
+
+function designIncomplete(effort, question) {
+  return {
+    status: 'design incomplete',
+    effort: performedEffort(effort),
+    attempts,
+    validationError: designError,
+    question: question ?? '',
+    lastFailure: feedback ?? '',
+  }
 }
 
 for (const [index, effort] of rungs.entries()) {
   const rung = index + 1
+
+  if (rung === 1 && args.effort === 'high') {
+    const designed = await design(rung, 'The task is classified as high effort; design it before any implementation.', 'design')
+    if (!designed)
+      return designIncomplete(effort)
+  }
+
   phase('Implement')
   log(`rung ${rung}/${rungs.length} @ ${effort}: implementing`)
   const report = await ask(implementerPrompt(spec, feedback), {
@@ -159,15 +197,11 @@ for (const [index, effort] of rungs.entries()) {
     attempts.push({ rung, effort, outcome: 'blocked', reason: report.question, question: report.question })
     if (rung === rungs.length)
       return { status: 'blocked', question: report.question, attempts }
-    spec = await ask(architectPrompt(`The implementer stopped on this question:\n${report.question}`), {
-      agentType: 'architect',
-      effort: 'xhigh',
-      phase: 'Design',
-      label: `design after blocked ${rung}`,
-      schema: SPEC,
-    })
+    const designed = await design(rung, `The implementer stopped on this question:\n${report.question}`, `design after blocked ${rung}`)
+    if (!designed && args.effort === 'high')
+      return designIncomplete(effort, report.question)
     feedback = null
-    log(`rung ${rung}/${rungs.length} @ ${effort}: blocked, architect answered`)
+    log(`rung ${rung}/${rungs.length} @ ${effort}: blocked, architect ${designed ? 'answered' : 'did not answer'}`)
     continue
   }
 
@@ -194,8 +228,8 @@ for (const [index, effort] of rungs.entries()) {
 
   if (passed) {
     return {
-      status: 'done',
-      effort,
+      status: designFailed && !designComplete ? 'degraded' : 'done',
+      effort: performedEffort(effort),
       attempts,
       files: report.files,
       summary: report.summary,
@@ -214,16 +248,11 @@ for (const [index, effort] of rungs.entries()) {
     feedback = `Security invariant failed: ${verdict.securityFinding}\n${feedback}`
 
   if (rung === rungs.length - 1) {
-    phase('Design')
     log(`rung ${rung}/${rungs.length} failed twice: architect redesigns before the last rung`)
-    spec = await ask(architectPrompt(`Two rungs have failed the harness. Latest failure:\n${feedback}\n\nDecide whether the approach, the contract or the boundary is wrong before the last attempt.`), {
-      agentType: 'architect',
-      effort: 'xhigh',
-      phase: 'Design',
-      label: 'design before last rung',
-      schema: SPEC,
-    })
+    const designed = await design(rung, `Two rungs have failed the harness. Latest failure:\n${feedback}\n\nDecide whether the approach, the contract or the boundary is wrong before the last attempt.`, 'design before last rung')
+    if (!designed && args.effort === 'high')
+      return designIncomplete(effort)
   }
 }
 
-return { status: 'failed', attempts, lastFailure: feedback }
+return { status: 'failed', attempts, lastFailure: feedback, effort: performedEffort(rungs[rungs.length - 1]) }

package/templates/base/architecture/decisions/README.md

@@ -0,0 +1,26 @@
+# Decisions
+
+One file per decision that shapes what this project is allowed to claim. A decision lands here when
+reversing it would cost more than making it did, or when a later reader would otherwise re-open it
+from scratch. Read this directory before re-opening a question it already answers, and add a record
+rather than restating a decision in a plan or a commit message.
+
+Each record carries four sections: the context it was taken in, the decision itself, the
+consequences it accepts, and how it is enforced.
+
+Enforcement is named on a scale, so the strength of a decision is visible rather than implied:
+
+| Level | Enforced by |
+|---|---|
+| L0 | text only — nothing checks it |
+| L1 | review — a human is the check |
+| L2 | a local hook — bypassable with `--no-verify` |
+| L3 | CI — it runs on every push |
+| L4 | CI that blocks the merge |
+
+A decision enforced only by review says so; that is the honest answer, not a gap to hide.
+
+Records are named `NNNN-a-short-title.md` and numbered in the order they were taken.
+
+| # | Decision | Enforced at |
+|---|---|---|

package/templates/base/architecture/principles.md

@@ -68,7 +68,9 @@ isolated and manageable — and to treat accidental complexity as a defect.
   reconsider the decomposition, coupling or abstraction instead of pushing through.
 
 The checklists that turn these principles into questions to answer before a change are in
-[checklists.md](checklists.md).
+[checklists.md](checklists.md). A decision that shapes what this project may claim is recorded once in
+[decisions/](decisions/README.md), with the level at which it is enforced, instead of being restated in
+a plan or a commit message.
 
 ## Security