mikoshi-construct 0.1.3 → 0.3.0

package/README.md

@@ -9,8 +9,14 @@ npx mikoshi-construct init          # interactive: preset, agent, project name
 pnpm install && pnpm run quality    # green before you write a line
 ```
 
-> **v0.1.** Presets `node-backend`, `node-frontend`, `node-library` and `monorepo`. Claude Code gets
+> **v0.3.** Presets `node-backend`, `node-frontend`, `node-library` and `monorepo`. Claude Code gets
 > the full lifecycle; Cursor gets the rules, the conventions and the discovery protocol.
+> `construct sync` moves a repository already carrying a construct onto newer templates.
+
+**Documentation — [e1i.github.io/mikoshi-construct](https://e1i.github.io/mikoshi-construct/)**:
+getting started, [the development cycle](https://e1i.github.io/mikoshi-construct/guide/the-cycle),
+the reasoning budget, [upgrading](https://e1i.github.io/mikoshi-construct/guide/upgrading) and the
+CLI reference.
 
 ## What it does
 
@@ -76,10 +82,14 @@ npx mikoshi-construct init --yes --preset node-frontend --ai both
 
 ```bash
 npx mikoshi-construct doctor     # baseline intact, harness intact, markers filled
+npx mikoshi-construct sync       # what newer templates would change; writes nothing
 npx mikoshi-construct soulkill   # what the detector sees; writes nothing
 npx mikoshi-construct cost --last
 ```
 
+`sync` reports and changes nothing until you ask for `--apply`, and even then it writes only what
+the construct itself wrote and you have not touched.
+
 Every command, flag and exit code: [docs/cli.md](https://github.com/E1i/mikoshi-construct/blob/main/docs/cli.md).
 
 ## Three principles
@@ -95,10 +105,22 @@ Every command, flag and exit code: [docs/cli.md](https://github.com/E1i/mikoshi-
    runtime, composition models render the diagrams and are checked against the code, the dependency
    policy lives in lint, and every security invariant names the check that enforces it.
 
-The second principle in numbers, from three `/implement` runs on the same small service (Claude
-Opus): two tasks classified `high` — contract change, composition-root change — cost 1.7M and 1.4M
-billable tokens with an architect design phase; the `low` task, docs only, cost 236k with none. The
-harness passed every run on the first rung. `construct cost` prints this for your own runs.
+The second principle in numbers, from thirteen `/implement` runs on this repository (Claude Opus).
+Two `low` tasks cost 557k and 740k billable tokens. Nine `medium` tasks cost between 847k and 5.9M —
+the class is a weak predictor on its own. Two `high` tasks, each with an architect designing before
+any code, cost 14.19M and 14.14M.
+
+Almost none of that is the work. It is each agent's entry into the repository: a fresh exploration,
+paid in full before anything is produced, and paid again by every agent that starts. A `low` run pays
+it twice — an implementer, and the harness that refuses to let the implementer mark its own homework.
+A `high` run pays it three times. The class mostly decides how deep each entry goes; the ladder
+decides how many entries there are, and that is what it is for.
+
+The same arithmetic prices a bad brief. One run escalated to an architect after the implementer
+stopped on a contradiction in the task, and the architect spent 3.66M without returning a valid
+answer — 4.16M for the run, for nothing. That is why a response the schema rejects is not re-asked by
+default: a second attempt buys another entry, not another answer. `construct cost` prints all of this
+for your own runs, and reconciles it against the ledger the ladder writes.
 
 ## The lifecycle
 
@@ -127,6 +149,7 @@ with a named check, not a second fix.
 |---|---|
 | `construct init` | Detect, configure, materialize. `--yes --preset node-backend\|node-frontend\|node-library\|monorepo --ai claude\|cursor\|both --review claude --dir . --dry-run` |
 | `construct doctor` | Baseline files present, harness intact, discovery markers filled — `GLITCH` by name when not |
+| `construct sync` | Classify every path against today's templates and report; `--apply` writes only what the construct owns and you have not changed (`--json`) |
 | `construct soulkill` | Print what the detector sees, write nothing (`--json`; aliases `inspect`, `capture`) |
 | `construct cost` | Token usage of the `/implement` runs in this directory, per agent, billable and price-weighted (`--last`, `--json`) |
 
@@ -164,6 +187,12 @@ The names are a tribute to Cyberpunk 2077 and mean exactly one thing each here.
 | Soulkiller | `construct soulkill`: extracts the facts about a repository and writes nothing |
 | Netrunner | The coding agent — Claude Code, Cursor — that connects to the project through the construct |
 | Relic | The files at the root the agent reads first: `AGENTS.md`, `CLAUDE.md`, `construct.json` |
+| Engram | The record `init` cut into `construct.json`: what the construct wrote, and the version that wrote it |
+| Braindance | `construct sync`: replaying that engram against today's templates and reporting where the two disagree |
+| Relic write | `construct sync --apply`: the one write into a repository the construct did not create |
+| Blackwall | Where a construct block whose template variant cannot be established sits — not yours, not ours, and nothing is written there |
+| Glitch | A warning in the output. Something wants a human; nothing has failed |
+| Flatlined | A check that failed outright: a missing baseline file, or no `construct.json` where one was required |
 | Harness | No lore. `pnpm run quality`. The one word that must be understood without this table |
 
 Not affiliated with CD Projekt Red.