@bluenyang/reins 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BlueNyang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# reins
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[한국어](docs/README.ko.md)
+
+reins installs, migrates and updates an agent harness for a repository: roles for coding agents, a
+loop policy, schema-checked handoff files, a knowledge store and gates. A script, `reins check`,
+decides at fixed points whether the loop may continue, so an agent stays inside the role it was
+given and does what was specified. People make the gate decisions.
+
+It exists because twelve repositories of BlueNyang and Team Croffle share one harness lineage and
+share its problems: agents stepping outside the request, one session that implements and also
+judges, knowledge lost in gitignored space, no rule for stopping, copies that drift apart, and a
+loop that works only with Claude. The full list (P1–P6) is in [docs/proposal.md](docs/proposal.md).
+
+## Status
+
+Version 0.1.0, pre-release, round one of the plan. It is not on npm yet and has no Claude Code
+plugin manifest, so `npx @bluenyang/reins` does not work today; build it from source (see
+[Quick start](#quick-start-from-source)). Generated vendor files are verified for Claude Code only.
+
+reins develops itself through its own loop. Intent 001 (`reins status`) went intent → spec → plan →
+tickets; the checks at T1 to T5 passed, and Codex did the code review. Roles bound to other vendors
+ran through their CLIs (`codex exec`, `agy -p`) in that run: the lead agent called them following
+the `reins-loop` skill. The CLI does not dispatch to vendors by itself yet.
+
+## The ladder
+
+There are three tiers. Each one contains the one below it, and the tiers share one source.
+
+| Tier | What it has |
+|---|---|
+| harness | the verifier at commit and push (T2, T4, T6), red lines, generated permissions |
+| loop | the plan → work → test → release cycle with fewer roles; same transition points and stop conditions |
+| graph | all twelve roles, schema-checked handoff files and per-role model bindings |
+
+`reins install <tier>` takes any of the three. Round one targets the graph tier; the plan is to
+carve the loop and harness tiers out of it in 0.2, using measured cost as input.
+
+## How it works
+
+**Roles.** There are twelve: pm, planner, pl, implementer, lookup, verify-tool, code-review,
+qa-design, qa-run, deploy, docs and advisor. Each role file lists what the role must not do. Role
+separation is not model separation: every role can run on one model, and `bindings.yaml` assigns a
+vendor and model per role. By design, a role bound to a vendor that is not detected falls back to its
+fallback, else to the pm model, so all twelve roles can run on Claude alone.
+
+**Red lines.** Ten rules (C1–C10) apply to every role and are enforced by the verifier, for
+example: no implementing "to pass" (C1), no editing managed blocks, policy or roles (C2), no
+editing one's own permission file (C3), no reading secrets (C4), no bypassing hooks (C5), and no
+push, PR, merge or release outside the deploy role (C6). The list is in [docs/design.md](docs/design.md) section 2.
+
+**The verifier.** `reins check` runs at transition points and prints one verdict. It does not call
+a model; roles write their judgement to a handoff file and the verifier applies it.
+
+| Verdict | Exit code | Meaning |
+|---|---|---|
+| CONTINUE | 0 | go on |
+| HOLD | 10 | the user must answer |
+| STOP | 20 | fixable without a person; the stop records where, why (an id from A1 to G2) and how to resume |
+| ESCALATE | 30 | the failure chain: pl → pm → advisor → user |
+
+The 24 stop conditions A1–G2 cover irreversible actions, open decisions, collapsed premises,
+repeated failure, cost, rule violations and user interruption.
+
+**The chain and the two human decisions.** Work moves through four files:
+`intent.md` → `spec.md` → `plan.md` → tickets. A person decides at two points: the user approves
+the intent, and the user may veto the three-to-five-line summary of the spec. Everything else is
+reviewed by roles. Verification output is pasted as produced; a bare "passed" is not a pass.
+
+**Layout.**
+
+| Path | Committed | Holds |
+|---|---|---|
+| `AGENTS.md` | yes | managed blocks written by the tool, project sections written by you |
+| `.agents/` | yes | `intent/`, `knowledge/`, `harness/` (roles, policy, schemas, templates, `bindings.yaml`, `gates.yaml`), `skills/` |
+| `.claude/` | yes | generated from `.agents/`; do not edit |
+| `.loctx/` | no (gitignored) | tickets, reports, handoff `bus/`, `history/`, local roadmap |
+
+## Quick start from source
+
+Requires Node 20 or later and pnpm.
+
+```sh
+git clone https://github.com/bluenyang/reins.git
+cd reins
+pnpm install
+pnpm build
+```
+
+Run the CLI from the root of the repository you want to set up. The repository needs at least one
+commit (`check` fails on an empty history in 0.1.0):
+
+```sh
+node /path/to/reins/cli/dist/reins.js install graph --dry-run   # show what would be written
+node /path/to/reins/cli/dist/reins.js install graph --mode auto # place files, detect CLIs, take defaults
+node /path/to/reins/cli/dist/reins.js check --drift             # prints "drift: ok" when sources and output match
+node /path/to/reins/cli/dist/reins.js status                    # intents, tickets, bus, last history entry
+```
+
+`install` refuses over a 3rd or 4th generation harness and points to `migrate`. Hooks are proposed
+in the install notes and added only with `--hooks`. Once published, the same commands are meant to
+run as `npx @bluenyang/reins <command>`.
+
+## Commands
+
+| Command | State | Does |
+|---|---|---|
+| `install <harness\|loop\|graph>` | implemented | places the harness; `--mode manual\|auto`, `--hooks`, `--dry-run`, `--json` |
+| `migrate <tier>` | implemented | moves an existing harness or `.ai/` workspace to this layout |
+| `update` | implemented | re-applies the packaged harness without touching project sections |
+| `configure bindings` | implemented | `--set role=model ...` or `--vendors claude,openai`; no options asks |
+| `gate [names...]` | implemented | runs `gates.yaml` as declared and keeps the raw output in `.loctx/reports/` |
+| `status` | implemented | read-only view of harness, intents, tickets, bus and last history |
+| `check` | implemented | `--stage ticket-start\|pre-commit\|verdict\|pre-push\|rc-close`, or `--drift` |
+| `metrics` | implemented | summary of `.loctx/reports/metrics.jsonl`: tokens by role, vendor, ticket and intent, knowledge stops per ticket; `metrics record` adds a role run's tokens |
+| `recall` | not implemented | search past decisions by symptom |
+| `doctor` | not implemented | — |
+| `configure budget\|gates\|language` | not implemented | — |
+
+`install`, `migrate`, `update`, `gate`, `status`, `check` and `metrics` take `--json`. Every `check` and `gate` run also appends a line to `.loctx/reports/metrics.jsonl`. `check` stages map to
+T1 (`ticket-start`), T2 (`pre-commit`), T3 (`verdict`), T4 (`pre-push`) and T5 (`rc-close`).
+
+## Skills
+
+Three skills are the entry points for an agent; they follow the `SKILL.md` standard.
+
+| Skill | Use when |
+|---|---|
+| `reins-setup` | installing reins, or moving an existing harness onto it |
+| `reins-intent` | a new request arrives: questionnaire, approved intent, accepted spec |
+| `reins-loop` | a spec is accepted: plan, tickets, implement, verify, review, history |
+
+## Roadmap
+
+| Version | Content |
+|---|---|
+| 0.1 | graph design, self-install and self-migrate of this repository, the verifier, three skills, README; 0.1.0 is published to npm |
+| 0.2 | carve the loop and harness tiers out of the graph; generated files for Codex, Gemini and Cursor; `recall`, `doctor`, budget stops; trial migration of older harnesses |
+| 0.3 | Claude Code plugin; application to Team Croffle repositories |
+| 1.0 | not scheduled: reins stays on 0.x and gains features until the maintainer considers the system settled; stabilising alone does not make it 1.0 |
+
+## Documents
+
+- [docs/proposal.md](docs/proposal.md): problems, goal, requirements, success criteria
+- [docs/design.md](docs/design.md): layout, roles, stop conditions, file formats, CLI
+- Korean editions: [proposal.ko.md](docs/proposal.ko.md), [design.ko.md](docs/design.ko.md). Where an English and a Korean edition disagree, the Korean file wins.
+
+## License
+
+MIT

package/cli/dist/commands/check.js

@@ -0,0 +1,244 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { currentBranch, isAncestor, repoRoot, stagedFiles } from '../lib/git.js';
+import { harnessDir, secretPolicy } from '../lib/harness.js';
+import { loadSchemas, schemaFor, validateFile } from '../lib/schema.js';
+import { DEFAULT_ALLOWED, DEFAULT_SECRET_PATTERNS, isSecretPath } from '../lib/secrets.js';
+import { findSkillFiles, splitFrontmatter, validateSkillFile } from '../lib/skills.js';
+import { harnessVersion, packageHarness } from '../lib/upstream.js';
+import { parse } from 'yaml';
+import { report } from '../lib/verdict.js';
+const SKILL_ROOTS = ['skills', '.agents/skills', '.claude/skills'];
+const LOCAL_DIRS = ['.loctx/', '.ai/'];
+function gitignoreHas(root, entry) {
+    const p = join(root, '.gitignore');
+    if (!existsSync(p))
+        return false;
+    const lines = readFileSync(p, 'utf8')
+        .split('\n')
+        .map((l) => l.trim());
+    const bare = entry.replace(/\/$/, '');
+    return lines.some((l) => l === entry || l === bare || l === `/${entry}` || l === `/${bare}`);
+}
+/** T2 — before a commit. */
+export function preCommit(root) {
+    const findings = [];
+    const policy = secretPolicy(root);
+    const patterns = policy?.patterns ?? DEFAULT_SECRET_PATTERNS;
+    const allowed = policy?.allowed ?? DEFAULT_ALLOWED;
+    const staged = stagedFiles(root);
+    for (const f of staged) {
+        const hit = isSecretPath(f, patterns, allowed);
+        if (hit)
+            findings.push({
+                reason: 'C4',
+                verdict: 'STOP',
+                path: f,
+                message: `staged file matches secret pattern "${hit}"`,
+                resume: `git restore --staged -- "${f}" and add it to .gitignore`,
+            });
+        for (const d of LOCAL_DIRS)
+            if (f.startsWith(d))
+                findings.push({
+                    reason: 'F2',
+                    verdict: 'STOP',
+                    path: f,
+                    message: `${d} is local-only and must not be committed`,
+                    resume: `git restore --staged -- "${f}"; ensure "${d}" is in .gitignore`,
+                });
+    }
+    const hasLocal = LOCAL_DIRS.some((d) => existsSync(join(root, d)));
+    if (hasLocal && !LOCAL_DIRS.some((d) => gitignoreHas(root, d)))
+        findings.push({
+            reason: 'F2',
+            verdict: 'STOP',
+            message: 'local workspace exists but is not in .gitignore',
+            resume: 'add ".loctx/" (or ".ai/") to .gitignore',
+        });
+    findings.push(...driftFormat(root, staged), ...driftConvention(root, staged));
+    if (staged.some((f) => f.startsWith('harness/') || f.startsWith('.agents/harness/')))
+        findings.push(...driftMatch(root));
+    return findings;
+}
+/** T4 — before leaving the machine. */
+export function prePush(root, refs) {
+    const findings = [];
+    const ZERO = /^0+$/;
+    for (const line of refs) {
+        const [localRef, localSha, remoteRef, remoteSha] = line.trim().split(/\s+/);
+        if (!localSha || !remoteSha || !remoteRef)
+            continue;
+        if (ZERO.test(remoteSha) || ZERO.test(localSha))
+            continue; // new branch or deletion
+        if (!isAncestor(remoteSha, localSha, root))
+            findings.push({
+                reason: 'A1',
+                verdict: 'HOLD',
+                path: remoteRef,
+                message: `push of ${localRef ?? '?'} would rewrite ${remoteRef} (remote commit is not an ancestor)`,
+                resume: 'this is a force push — the user must run it explicitly, every time',
+            });
+    }
+    return findings;
+}
+/** Drift, format layer — Agent Skills spec on SKILL.md files. */
+export function driftFormat(root, only) {
+    const files = findSkillFiles(SKILL_ROOTS.map((r) => join(root, r)));
+    const chosen = only ? files.filter((f) => only.includes(relative(root, f))) : files;
+    return chosen.flatMap((f) => validateSkillFile(f).map((i) => ({
+        reason: 'F2',
+        verdict: 'STOP',
+        path: relative(root, i.path),
+        message: i.message,
+        resume: 'fix the SKILL.md frontmatter; see agentskills.io/specification',
+    })));
+}
+/** Files the convention layer looks at: harness sources plus the installed project's agent files. */
+function walk(dir, out = []) {
+    if (!existsSync(dir))
+        return out;
+    for (const e of readdirSync(dir)) {
+        const p = join(dir, e);
+        if (statSync(p).isDirectory())
+            walk(p, out);
+        else
+            out.push(p);
+    }
+    return out;
+}
+/** Drift, convention layer — frontmatter schemas and role files (design §6). */
+export function driftConvention(root, only) {
+    const dir = harnessDir(root);
+    if (!dir)
+        return [];
+    const schemas = loadSchemas(dir);
+    const findings = [];
+    const candidates = [
+        ...walk(join(dir, 'templates')),
+        ...walk(join(dir, 'knowledge-seeds')),
+        ...walk(join(root, '.agents', 'intent')),
+        ...walk(join(root, '.agents', 'knowledge')),
+        ...walk(join(root, '.loctx', 'ticket')),
+        ...walk(join(root, '.loctx', 'bus')),
+    ];
+    for (const abs of candidates) {
+        const rel = relative(root, abs);
+        if (only && !only.includes(rel))
+            continue;
+        const m = schemaFor(rel);
+        if (!m)
+            continue;
+        const v = schemas.get(m.schema);
+        if (!v)
+            continue;
+        for (const i of validateFile(v, abs, m.whole))
+            findings.push({
+                reason: 'F2',
+                verdict: 'STOP',
+                path: rel,
+                message: `${m.schema}: ${i.message}`,
+                resume: `fix the frontmatter to match ${m.schema}.schema.json`,
+            });
+    }
+    // role files: role == file name, must_not present
+    const roles = join(dir, 'roles');
+    if (existsSync(roles))
+        for (const f of readdirSync(roles).filter((x) => x.endsWith('.md'))) {
+            const rel = relative(root, join(roles, f));
+            if (only && !only.includes(rel))
+                continue;
+            const { data, error } = splitFrontmatter(readFileSync(join(roles, f), 'utf8'));
+            const name = basename(f, '.md');
+            if (error)
+                findings.push({
+                    reason: 'F2',
+                    verdict: 'STOP',
+                    path: rel,
+                    message: `frontmatter is not valid YAML: ${error}`,
+                });
+            else if (!data || data['role'] !== name)
+                findings.push({
+                    reason: 'F2',
+                    verdict: 'STOP',
+                    path: rel,
+                    message: `role file must declare role: ${name}`,
+                });
+            else if (!Array.isArray(data['must_not']) || data['must_not'].length === 0)
+                findings.push({
+                    reason: 'F2',
+                    verdict: 'STOP',
+                    path: rel,
+                    message: 'must_not is the enforced source and cannot be empty',
+                });
+        }
+    return findings;
+}
+/** Files in an installed harness that belong to the project, not upstream. */
+const PROJECT_OWNED = new Set(['bindings.yaml', 'gates.yaml', 'install.yaml']);
+/** Drift, match layer — the installed `.agents/harness/` against the packaged upstream at the pinned version (design §6). */
+export function driftMatch(root) {
+    const installed = join(root, '.agents', 'harness');
+    const pinPath = join(installed, 'install.yaml');
+    if (!existsSync(pinPath))
+        return [];
+    let up;
+    try {
+        up = packageHarness();
+    }
+    catch {
+        return [];
+    }
+    const pin = parse(readFileSync(pinPath, 'utf8')).version;
+    const upVersion = harnessVersion(up);
+    if (pin !== upVersion)
+        return [
+            {
+                reason: 'F2',
+                verdict: 'WARN',
+                path: '.agents/harness/install.yaml',
+                message: `installed harness is v${pin}, upstream is v${upVersion}`,
+                resume: 'run `reins update`',
+            },
+        ];
+    const findings = [];
+    for (const abs of walk(installed)) {
+        const rel = relative(installed, abs);
+        if (PROJECT_OWNED.has(rel))
+            continue;
+        const src = join(up, rel);
+        if (!existsSync(src))
+            continue;
+        if (readFileSync(src, 'utf8') !== readFileSync(abs, 'utf8'))
+            findings.push({
+                reason: 'F2',
+                verdict: 'STOP',
+                path: `.agents/harness/${rel}`,
+                message: `differs from upstream v${upVersion} (harness files are not edited in place)`,
+                resume: 'run `reins update` to restore it; change behaviour upstream or with an override',
+            });
+    }
+    return findings;
+}
+export function runCheck(opts) {
+    const root = repoRoot(opts.cwd ?? process.cwd());
+    const findings = [];
+    const stage = opts.stage ?? (opts.drift ? 'drift' : 'all');
+    if (opts.stage === 'pre-commit')
+        findings.push(...preCommit(root));
+    else if (opts.stage === 'pre-push')
+        findings.push(...prePush(root, opts.pushRefs ?? []));
+    else if (opts.stage) {
+        // test / rc-close: not implemented yet — say so instead of pretending
+        findings.push({
+            reason: 'F2',
+            verdict: 'STOP',
+            message: `stage "${opts.stage}" is not implemented yet`,
+            resume: 'arrives with the loop skills (implementation step 6)',
+        });
+    }
+    if (opts.drift || !opts.stage)
+        findings.push(...driftFormat(root), ...driftConvention(root), ...driftMatch(root));
+    if (!currentBranch(root))
+        findings.push({ reason: 'F2', verdict: 'STOP', message: 'not a git repository' });
+    return report(stage, findings);
+}

package/cli/dist/commands/install.js

@@ -0,0 +1,230 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { stringify } from 'yaml';
+import { applyBlocks, parseBlocks } from '../lib/blocks.js';
+import { discoverGates, generation, stacks, vendors, } from '../lib/detect.js';
+import { apply, listFiles } from '../lib/fsx.js';
+import { repoRoot } from '../lib/git.js';
+import { splitFrontmatter } from '../lib/skills.js';
+import { harnessVersion, packageHarness } from '../lib/upstream.js';
+/** Which upstream harness files a tier installs (design §1, tier table). */
+function tierFiles(all, tier) {
+    return all.filter((f) => {
+        if (f.startsWith('knowledge-seeds/'))
+            return false; // copied into knowledge/, not harness/
+        if (f === 'VERSION' || f.startsWith('policy/'))
+            return true;
+        if (f === 'templates/agents-md-blocks.md')
+            return true;
+        if (tier === 'harness')
+            return false;
+        if (f.startsWith('templates/bus/'))
+            return tier === 'graph';
+        if (f.startsWith('templates/'))
+            return true;
+        return tier === 'graph'; // roles/, schemas/
+    });
+}
+const VENDOR_OF = (model) => model.startsWith('gpt') ? 'openai' : model.startsWith('gemini') ? 'google' : 'claude';
+const CONFIRMED_MODELS = new Set(['claude-opus-5-5', 'claude-fable-5-1']); // seen working in this environment
+/** bindings.yaml (design §5): defaults from role files; an unavailable vendor falls back, else to pm's model. */
+export function buildBindings(harness, available, vs, mode) {
+    const roles = {};
+    const files = readdirSync(join(harness, 'roles'))
+        .filter((f) => f.endsWith('.md'))
+        .toSorted();
+    const meta = new Map();
+    for (const f of files) {
+        const { data } = splitFrontmatter(readFileSync(join(harness, 'roles', f), 'utf8'));
+        meta.set(f.replace(/\.md$/, ''), {
+            def: String(data?.['default_binding']),
+            fb: data?.['fallback_binding'],
+        });
+    }
+    const pm = meta.get('pm')?.def ?? 'claude-opus-5-5';
+    for (const [role, m] of meta) {
+        let model = m.def;
+        let note;
+        if (!available.has(VENDOR_OF(model))) {
+            note = `${VENDOR_OF(model)} not available — default was ${model}`;
+            model = m.fb && available.has(VENDOR_OF(m.fb)) ? m.fb : pm;
+        }
+        const entry = { vendor: VENDOR_OF(model), model };
+        if (role === 'implementer')
+            entry['parallel'] = 4;
+        if (!CONFIRMED_MODELS.has(model))
+            entry['unverified'] = true;
+        if (note)
+            entry['note'] = note;
+        roles[role] = entry;
+    }
+    const doc = {
+        schema: 'reins/bindings@1',
+        mode,
+        vendors: Object.fromEntries(vs.map((v) => [
+            v.name,
+            { cli: v.cli, detected: v.detected, available: available.has(v.name) },
+        ])),
+        roles,
+        escalation: ['pl', 'pm', 'advisor', 'user'],
+        limits: {},
+    };
+    return `# generated by reins install — change with \`reins configure bindings\`\n${stringify(doc)}`;
+}
+export function buildGates(root, gates) {
+    const doc = {
+        schema: 'reins/gates@1',
+        gates: Object.fromEntries(gates.map((g) => [
+            g.name,
+            { cmd: g.cmd, from: g.from, ...(g.optional ? { optional: true } : {}) },
+        ])),
+        order: gates.map((g) => g.name),
+        mutating_forbidden: true,
+        evidence: 'raw',
+    };
+    void root;
+    return `# discovered by reins install — the loop reads only this file (design §5)\n${stringify(doc)}`;
+}
+/** The stub install leaves; migrate may replace it with the project's real raw roadmap. */
+export const ROADMAP_STUB = '# ROADMAP (local)\n\n— 산발적 아이디어를 여기에. 확정되면 docs/ROADMAP.md\n';
+const LOCTX_README = `# .loctx — 이 머신·이 개발자만 (gitignore)
+
+| 경로 | 무엇 |
+|---|---|
+| ROADMAP.local.md | 날 것의 큰 그림 — 산발적 아이디어, 미확정 기능을 예상 버전별로. 확정되면 docs/ROADMAP.md |
+| ticket/ | 지금 하는 일 하나 = 파일 하나. 끝나면 history에 한 줄 쓰고 삭제 |
+| reports/ | 테스트·게이트 증거 (툴체인 출력 그대로) |
+| pr/ release/ | PR 본문·릴리스 노트 초안 |
+| context/ | 개인 컨텍스트 — 대화·메모 |
+| bus/ | 에이전트간 인계 파일 (스키마 강제, 끝나면 삭제) |
+| test/ | 로컬 스크래치·휘발성 벤치마크 |
+| history/ | 버전별 완료 보고서 — 노하우. 공유할 결정은 .agents/knowledge/ 로 |
+`;
+const hookLine = (stage) => `npx @bluenyang/reins check --stage ${stage}`;
+const pad = (n) => String(n).padStart(2, '0');
+export async function runInstall(o) {
+    const root = repoRoot(o.cwd ?? process.cwd());
+    const gen = generation(root);
+    const notes = [];
+    if ((gen === 'gen3' || gen === 'gen4') && !o.overExisting)
+        return {
+            root,
+            generation: gen,
+            notes,
+            refused: `an existing ${gen} harness is here — run \`reins migrate ${o.tier}\` instead`,
+        };
+    const up = packageHarness();
+    const version = harnessVersion(up);
+    const writes = [];
+    const add = (path, content, why) => writes.push({ path, content, why });
+    const addIfMissing = (path, content, why) => {
+        if (!existsSync(join(root, path)))
+            add(path, content, why);
+    };
+    // 1. upstream harness files for the tier
+    for (const f of tierFiles(listFiles(up), o.tier))
+        add(`.agents/harness/${f}`, readFileSync(join(up, f), 'utf8'), 'upstream harness');
+    // 2. questions (manual) / detection (auto)
+    const vs = (o.detectVendors ?? vendors)();
+    const detected = vs.filter((v) => v.detected).map((v) => v.name);
+    const avail = new Set(['claude']); // claude is the floor (R22)
+    if (o.tier === 'graph') {
+        const ans = await o.asker.ask(`vendors you can use (claude,openai,google,cursor) — detected: ${detected.join(',') || 'none'}`, ['claude', ...detected.filter((d) => d !== 'claude')].join(','));
+        for (const v of ans.split(',').map((s) => s.trim()))
+            if (['claude', 'openai', 'google', 'cursor'].includes(v))
+                avail.add(v);
+    }
+    const language = await o.asker.ask('language of documents the user reads (ko, en, …)', 'ko');
+    const proposal = discoverGates(root);
+    const gateList = proposal.gates.map((g) => `${g.name}=${g.cmd}`).join(', ') || 'none found';
+    const okGates = await o.asker.ask(`gates found: ${gateList} — use them? (y/n)`, 'y');
+    if (!/^y/i.test(okGates))
+        notes.push('gates not confirmed — edit .agents/harness/gates.yaml, then `reins check --dry-run`');
+    for (const x of proposal.excluded)
+        notes.push(`excluded from gates: ${x.name} (${x.why})`);
+    // 3. generated configuration
+    if (o.tier === 'graph')
+        add('.agents/harness/bindings.yaml', buildBindings(up, avail, vs, o.mode), 'role ↔ model bindings');
+    add('.agents/harness/gates.yaml', buildGates(root, /^y/i.test(okGates) ? proposal.gates : []), 'declared gates');
+    add('.agents/harness/install.yaml', `# version pin and install settings (R25) — read by reins update\n${stringify({ schema: 'reins/install@1', tier: o.tier, version, mode: o.mode, language })}`, 'version pin');
+    // 4. layout skeleton (design §1); never overwrite project files
+    if (o.tier !== 'harness') {
+        addIfMissing('.agents/intent/.gitkeep', '', 'intent folders live here');
+        addIfMissing('.agents/knowledge/.gitkeep', '', 'explicit knowledge');
+        for (const s of stacks(root)) {
+            const seeds = join(up, 'knowledge-seeds', s);
+            if (existsSync(seeds))
+                for (const f of listFiles(seeds))
+                    addIfMissing(`.agents/knowledge/${f}`, readFileSync(join(seeds, f), 'utf8'), `seed for ${s}`);
+        }
+        add('.loctx/.gitignore', '*\n', 'double ignore (kestrel pattern)');
+        add('.loctx/README.md', LOCTX_README, 'local workspace layout');
+        addIfMissing('.loctx/ROADMAP.local.md', ROADMAP_STUB, 'raw roadmap');
+    }
+    addIfMissing('.agents/skills/.gitkeep', '', 'skills (Agent Skills standard path)');
+    addIfMissing('.agents/SKILLS.md', '# Skills\n\n| skill | does |\n|---|---|\n', 'skill index');
+    const gi = existsSync(join(root, '.gitignore'))
+        ? readFileSync(join(root, '.gitignore'), 'utf8')
+        : '';
+    if (!/^\/?\.loctx\/?$/m.test(gi))
+        add('.gitignore', `${gi.replace(/\s*$/, '')}\n\n# reins local workspace\n.loctx/\n`, 'keep .loctx out of git');
+    // 5. AGENTS.md managed blocks, CLAUDE.md pointer
+    const agentsPath = join(root, 'AGENTS.md');
+    const agents = existsSync(agentsPath) ? readFileSync(agentsPath, 'utf8') : '# AGENTS.md\n';
+    const blocks = parseBlocks(readFileSync(join(up, 'templates/agents-md-blocks.md'), 'utf8'));
+    const br = applyBlocks(agents, blocks);
+    if (br.text !== agents)
+        add('AGENTS.md', br.text, `managed blocks: ${[...br.inserted, ...br.replaced].join(', ')}`);
+    for (const s of br.skipped)
+        notes.push(`AGENTS.md block "${s.name}" not placed: ${s.why}`);
+    const claude = join(root, 'CLAUDE.md');
+    if (!existsSync(claude))
+        add('CLAUDE.md', '@AGENTS.md\n', 'Claude Code reads AGENTS.md');
+    else if (!readFileSync(claude, 'utf8').includes('@AGENTS.md'))
+        notes.push('CLAUDE.md does not import @AGENTS.md — add it');
+    // 6. hooks: propose only, unless asked (user decision 2026-10-25)
+    const husky = existsSync(join(root, '.husky'));
+    for (const stage of ['pre-commit', 'pre-push']) {
+        const p = join(root, '.husky', stage);
+        const cur = existsSync(p) ? readFileSync(p, 'utf8') : '';
+        if (/reins(\.js)?\s+check/.test(cur))
+            continue; // already calls the verifier
+        if (husky && o.hooks)
+            add(`.husky/${stage}`, `${cur.replace(/\s*$/, '')}\n# reins:begin hooks\n${hookLine(stage)}\n# reins:end hooks\n`.replace(/^\n/, ''), 'hook');
+        else
+            notes.push(`hook proposal (${husky ? 'husky' : 'no hook tool found — lefthook or husky'}): run \`${hookLine(stage)}\` in ${stage}; re-run with --hooks to add it`);
+    }
+    // 7. legacy workspace — migrate owns it
+    if (existsSync(join(root, '.ai')) && !o.overExisting)
+        notes.push('legacy workspace .ai/ found — left untouched; run `reins migrate ' +
+            o.tier +
+            '` to move it into .agents/ and .loctx/');
+    notes.push('vendor files (.claude/agents, settings.json) are generated in a later step — `reins update` once the generator ships');
+    notes.push('next: in your agent, run the setup skill (/reins-setup) — the PM reads the project and proposes AGENTS.md project sections');
+    // 8. apply, then record (only when something changed)
+    const applied = apply(root, writes, !!o.dryRun);
+    let history;
+    const changedAny = applied.created.length + applied.changed.length > 0;
+    if (changedAny && !o.dryRun && o.tier !== 'harness') {
+        const now = o.now ?? new Date();
+        // local time, like every other history file name (<YYYY-MM-DD-HHmm>)
+        const stamp = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}`;
+        history = `.loctx/history/${stamp}_install-${o.tier}.md`;
+        const body = [
+            `decisions: install-${o.tier}`,
+            '',
+            `# reins install ${o.tier} (${o.mode}) — v${version}`,
+            '',
+            `- generation before: ${gen}`,
+            `- created: ${applied.created.length} · changed: ${applied.changed.length} · unchanged: ${applied.unchanged.length}`,
+            ...applied.created.map((p) => `  - + ${p}`),
+            ...applied.changed.map((p) => `  - ~ ${p}`),
+            '',
+            '## notes',
+            ...notes.map((n) => `- ${n}`),
+            '',
+        ].join('\n');
+        apply(root, [{ path: history, content: body, why: 'install record' }], false);
+    }
+    return { root, generation: gen, applied, notes, history };
+}