@bluenyang/reins 0.0.0-stage → 0.1.0

package/cli/dist/lib/migrate-plan.js

@@ -0,0 +1,233 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { listFiles } from './fsx.js';
+import { splitFrontmatter } from './skills.js';
+const TOOL_EXT = new Set([
+    '.cjs',
+    '.mjs',
+    '.js',
+    '.ts',
+    '.sh',
+    '.ps1',
+    '.py',
+    '.pem',
+    '.key',
+    '.env',
+    '.yml',
+    '.yaml',
+    '.json',
+    '.toml',
+    '.dockerfile',
+]);
+const isToolFile = (f) => TOOL_EXT.has(extname(f).toLowerCase()) || /dockerfile|compose|\.env/i.test(basename(f));
+function dirFiles(root, rel) {
+    return listFiles(join(root, rel)).map((f) => `${rel}/${f}`);
+}
+/** A work file is open unless its frontmatter says done. */
+function isOpen(abs) {
+    const { data } = splitFrontmatter(readFileSync(abs, 'utf8'));
+    return !data || String(data['status'] ?? 'todo') !== 'done';
+}
+export function planMigration(root) {
+    const moves = [];
+    const report = [];
+    const ai = '.ai';
+    if (!existsSync(join(root, ai)))
+        return { moves, report };
+    for (const entry of readdirSync(join(root, ai)).toSorted()) {
+        const rel = `${ai}/${entry}`;
+        const abs = join(root, rel);
+        const isDir = statSync(abs).isDirectory();
+        const files = isDir ? dirFiles(root, rel) : [rel];
+        const sub = (f) => f.slice(rel.length + 1);
+        switch (isDir ? entry : '') {
+            case 'history':
+                for (const f of files)
+                    moves.push({
+                        from: f,
+                        to: `.loctx/history/${sub(f)}`,
+                        action: 'move',
+                        why: 'know-how stays local, unchanged',
+                    });
+                continue;
+            case 'work':
+                for (const f of files)
+                    if (f.endsWith('.md') && isOpen(join(root, f)))
+                        moves.push({
+                            from: f,
+                            to: `.loctx/ticket/${sub(f)}`,
+                            action: 'ticket',
+                            why: 'open work item → ticket',
+                        });
+                    else
+                        moves.push({
+                            from: f,
+                            to: `.loctx/history/work/${sub(f)}`,
+                            action: 'move',
+                            why: 'closed work item',
+                        });
+                continue;
+            case 'release':
+            case 'pr':
+                for (const f of files)
+                    moves.push({ from: f, to: `.loctx/${entry}/${sub(f)}`, action: 'move', why: 'drafts' });
+                continue;
+            case 'test':
+                for (const f of files)
+                    if (isToolFile(f)) {
+                        moves.push({
+                            from: f,
+                            to: `.loctx/_legacy/${f.slice(4)}`,
+                            action: 'legacy',
+                            why: 'tool file in a report folder — may hold secrets',
+                        });
+                        report.push(`test asset candidate (review, then move to test/ if it should be committed): ${f}`);
+                    }
+                    else
+                        moves.push({
+                            from: f,
+                            to: `.loctx/reports/${sub(f)}`,
+                            action: 'move',
+                            why: 'test report',
+                        });
+                continue;
+            case 'verify':
+            case 'benchmark':
+            case 'artifacts':
+                for (const f of files)
+                    moves.push({
+                        from: f,
+                        to: `.loctx/_legacy/${f.slice(4)}`,
+                        action: 'legacy',
+                        why: 'verification assets — review before committing',
+                    });
+                report.push(`${rel}/ (${files.length} files) kept in .loctx/_legacy/ — promote what should be committed to test/`);
+                continue;
+            case 'plan':
+                for (const f of files)
+                    moves.push({
+                        from: f,
+                        to: `.loctx/context/plan/${sub(f)}`,
+                        action: 'move',
+                        why: 'plans before reins — kept as context',
+                    });
+                if (files.length)
+                    report.push('plans moved to .loctx/context/plan/ — open version plans become intents through the intent skill, with the user');
+                continue;
+            default:
+                break;
+        }
+        if (!isDir) {
+            if (/^ROADMAP\.local\.md$/i.test(entry) || entry === 'ROADMAP.md')
+                moves.push({
+                    from: rel,
+                    to: '.loctx/ROADMAP.local.md',
+                    action: 'move',
+                    why: 'raw roadmap',
+                });
+            else if (/^ROADMAP\.pub\.md$/i.test(entry)) {
+                moves.push({
+                    from: rel,
+                    to: existsSync(join(root, 'docs/ROADMAP.md'))
+                        ? '.loctx/context/ROADMAP.pub.md'
+                        : 'docs/ROADMAP.md',
+                    action: 'move',
+                    why: 'public roadmap',
+                });
+            }
+            else if (entry === 'README.md')
+                moves.push({
+                    from: rel,
+                    to: '.loctx/context/ai-README.md',
+                    action: 'move',
+                    why: 'the old workspace readme',
+                });
+            else if (entry === '.gitignore')
+                moves.push({
+                    from: rel,
+                    to: '.loctx/_legacy/ai.gitignore',
+                    action: 'legacy',
+                    why: 'replaced by .loctx/.gitignore',
+                });
+            else
+                moves.push({
+                    from: rel,
+                    to: `.loctx/context/${entry}`,
+                    action: 'move',
+                    why: 'other workspace file',
+                });
+            continue;
+        }
+        // conversation/, interview/, survey/, assets/, docs/, … → personal context
+        for (const f of files)
+            moves.push({
+                from: f,
+                to: `.loctx/context/${f.slice(4)}`,
+                action: 'move',
+                why: 'personal context',
+            });
+    }
+    // a second ROADMAP*.md would collide with the first
+    const seen = new Set();
+    for (const m of moves) {
+        if (seen.has(m.to)) {
+            m.to = `.loctx/context/${basename(m.from)}`;
+            m.why += ' (target taken)';
+        }
+        seen.add(m.to);
+    }
+    // .claude/memory (AI-GW) → knowledge; old procedures → legacy
+    for (const f of dirFiles(root, '.claude/memory'))
+        moves.push({
+            from: f,
+            to: `.agents/knowledge/${f.slice('.claude/memory/'.length)}`,
+            action: 'move',
+            why: 'shared memory → knowledge',
+        });
+    for (const d of [
+        '.claude/commands',
+        ...(existsSync(join(root, '.claude/skills'))
+            ? readdirSync(join(root, '.claude/skills'))
+                .filter((s) => s.endsWith('-workflow'))
+                .map((s) => `.claude/skills/${s}`)
+            : []),
+    ]) {
+        const fs = dirFiles(root, d);
+        for (const f of fs)
+            moves.push({
+                from: f,
+                to: `.loctx/_legacy/${f}`,
+                action: 'legacy',
+                why: 'replaced by reins skills',
+            });
+        if (fs.length)
+            report.push(`${d}/ moved to .loctx/_legacy/ — keep any project-specific procedure as a skill in .agents/skills/`);
+    }
+    return { moves, report };
+}
+/** work → ticket frontmatter (design §7): `release: <ver>-rc.N` becomes planned; the rest carries over. */
+export function convertWorkToTicket(text, fileName) {
+    const { data, body } = splitFrontmatter(text);
+    const fm = data ?? {};
+    const rel = String(fm['release'] ?? '');
+    const ticket = {
+        // intent 000 = not yet tied to an intent; the PL links it when the work is planned again
+        id: `000-${Number.parseInt(String(fm['id'] ?? ''), 10) || 1}`,
+        intent: '000',
+        plan_step: Number(fm['id'] ?? 1) || 1,
+        title: String(fm['title'] ?? basename(fileName, '.md')),
+        status: ['todo', 'doing', 'blocked', 'done'].includes(String(fm['status']))
+            ? String(fm['status'])
+            : 'todo',
+        depends: Array.isArray(fm['depends']) ? fm['depends'] : [],
+        release: /rc\.(\d+)/.exec(rel) && Number(/rc\.(\d+)/.exec(rel)?.[1]) > 1 ? 'stabilization' : 'planned',
+        role: 'implementer',
+        asks: [],
+        ...(fm['branch'] ? { branch: fm['branch'] } : {}),
+        migrated_from: fileName,
+    };
+    const yaml = Object.entries(ticket)
+        .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+        .join('\n');
+    return `---\n${yaml}\n---\n${body}`;
+}

package/cli/dist/lib/schema.js

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { parse } from 'yaml';
+import { splitFrontmatter } from './skills.js';
+/** Loads every `*.schema.json` in the harness and compiles them by file name (`intent`, `bus-request`, …). */
+export function loadSchemas(harness) {
+    const dir = join(harness, 'schemas');
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    const files = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.schema.json')) : [];
+    const ids = new Map();
+    for (const f of files) {
+        const schema = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+        ajv.addSchema(schema); // registered under its $id, so cross-file $refs resolve
+        if (schema.$id)
+            ids.set(f.replace(/\.schema\.json$/, ''), schema.$id);
+    }
+    const out = new Map();
+    for (const [name, id] of ids) {
+        const v = ajv.getSchema(id);
+        if (v)
+            out.set(name, v);
+    }
+    return out;
+}
+function errors(v, path) {
+    return (v.errors ?? []).map((e) => ({
+        path,
+        message: `${e.instancePath || '(root)'} ${e.message ?? 'invalid'}`,
+    }));
+}
+/** Validates a Markdown file's YAML frontmatter, or a whole YAML file when `whole` is set. */
+export function validateFile(v, path, whole = false) {
+    const text = readFileSync(path, 'utf8');
+    let data;
+    let error;
+    if (whole) {
+        try {
+            data = parse(text);
+        }
+        catch (e) {
+            error = e.message.split('\n')[0];
+        }
+    }
+    else
+        ({ data, error } = splitFrontmatter(text));
+    if (data == null)
+        return [{ path, message: error ? `not valid YAML: ${error}` : 'missing YAML frontmatter' }];
+    return v(data) ? [] : errors(v, path);
+}
+/** Which schema a file belongs to, from where it lives. */
+export function schemaFor(rel) {
+    const name = basename(rel);
+    if (/(^|\/)intent\/[^/]+\/intent\.md$/.test(rel) || rel.endsWith('templates/intent.md'))
+        return { schema: 'intent', whole: false };
+    if (/(^|\/)intent\/[^/]+\/spec\.md$/.test(rel) || rel.endsWith('templates/spec.md'))
+        return { schema: 'spec', whole: false };
+    if (/(^|\/)intent\/[^/]+\/plan\.md$/.test(rel) || rel.endsWith('templates/plan.md'))
+        return { schema: 'plan', whole: false };
+    if (/(^|\/)\.loctx\/ticket\/[^/]+\.md$/.test(rel) || rel.endsWith('templates/ticket.md'))
+        return { schema: 'ticket', whole: false };
+    if (/(^|\/)(knowledge|knowledge-seeds\/[^/]+)\/[^/]+\.md$/.test(rel) ||
+        rel.endsWith('templates/knowledge.md'))
+        return { schema: 'knowledge', whole: false };
+    if (name.endsWith('.request.yaml') || rel.endsWith('templates/bus/request.yaml'))
+        return { schema: 'bus-request', whole: true };
+    if (name.endsWith('.response.yaml') || rel.endsWith('templates/bus/response.yaml'))
+        return { schema: 'bus-response', whole: true };
+    return null;
+}

package/cli/dist/lib/secrets.js

@@ -0,0 +1,28 @@
+import { matchesAny } from './glob.js';
+/** Fallback secret-file patterns (red line C4) when no harness policy is present. */
+export const DEFAULT_SECRET_PATTERNS = [
+    '.env',
+    '.env.*',
+    'secrets/**',
+    '*.key',
+    '*.pem',
+    '*.p12',
+    '*.pfx',
+    '*.properties',
+    'id_rsa',
+    'id_rsa.*',
+    'id_ed25519',
+    'id_ed25519.*',
+];
+/** Templates that look like secrets but are fine to commit. */
+export const DEFAULT_ALLOWED = [
+    '.env.example',
+    '*.example',
+    '*.example.*',
+    '*.sample',
+];
+export function isSecretPath(path, patterns = DEFAULT_SECRET_PATTERNS, allowed = DEFAULT_ALLOWED) {
+    if (matchesAny(path, allowed))
+        return null;
+    return matchesAny(path, patterns);
+}

package/cli/dist/lib/skills.js

@@ -0,0 +1,63 @@
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { parse } from 'yaml';
+const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const RESERVED = ['anthropic', 'claude'];
+export function splitFrontmatter(text) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+    if (!m)
+        return { data: null, body: text };
+    try {
+        const data = parse(m[1] ?? '');
+        return { data: data ?? {}, body: m[2] ?? '' };
+    }
+    catch (e) {
+        // a broken frontmatter is a finding, never a crash of the verifier
+        return { data: null, body: m[2] ?? '', error: e.message.split('\n')[0] };
+    }
+}
+export function validateSkillFile(path) {
+    const issues = [];
+    const dir = basename(join(path, '..'));
+    const text = readFileSync(path, 'utf8');
+    const { data, body, error } = splitFrontmatter(text);
+    if (!data)
+        return [
+            {
+                path,
+                message: error ? `frontmatter is not valid YAML: ${error}` : 'missing YAML frontmatter',
+            },
+        ];
+    const name = data['name'];
+    const desc = data['description'];
+    if (typeof name !== 'string' || name.length === 0 || name.length > 64 || !NAME_RE.test(name))
+        issues.push({ path, message: 'name: 1–64 chars, lowercase letters/digits/single hyphens' });
+    else {
+        if (name !== dir)
+            issues.push({ path, message: `name "${name}" must equal its directory "${dir}"` });
+        for (const w of RESERVED)
+            if (name.split('-').includes(w))
+                issues.push({ path, message: `name must not contain reserved word "${w}"` });
+    }
+    if (typeof desc !== 'string' || desc.trim().length === 0 || desc.length > 1024)
+        issues.push({ path, message: 'description: 1–1024 chars, non-empty' });
+    else if (/<[a-z][^>]*>/i.test(desc))
+        issues.push({ path, message: 'description must not contain XML tags' });
+    if (body.split('\n').length > 500)
+        issues.push({ path, message: 'SKILL.md body over 500 lines — move detail to references/' });
+    return issues;
+}
+/** Every `<dir>/SKILL.md` under the given roots that exist. */
+export function findSkillFiles(roots) {
+    const out = [];
+    for (const root of roots) {
+        if (!existsSync(root))
+            continue;
+        for (const entry of readdirSync(root)) {
+            const p = join(root, entry, 'SKILL.md');
+            if (existsSync(p) && statSync(p).isFile())
+                out.push(p);
+        }
+    }
+    return out;
+}

package/cli/dist/lib/upstream.js

@@ -0,0 +1,16 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The harness shipped with this package: `<pkg>/harness`, two levels above `cli/dist/lib`. */
+export function packageHarness() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const up of ['../../../harness', '../../harness', '../harness']) {
+        const p = join(here, up);
+        if (existsSync(join(p, 'VERSION')))
+            return p;
+    }
+    throw new Error('reins: cannot find the packaged harness/ directory');
+}
+export function harnessVersion(dir) {
+    return readFileSync(join(dir, 'VERSION'), 'utf8').trim();
+}

package/cli/dist/lib/verdict.js

@@ -0,0 +1,15 @@
+export const EXIT = { CONTINUE: 0, HOLD: 10, STOP: 20, ESCALATE: 30 };
+const RANK = { CONTINUE: 0, STOP: 1, ESCALATE: 2, HOLD: 3 };
+/** The report's verdict is the most demanding of its findings; HOLD outranks all; WARN never stops. */
+export function report(stage, findings) {
+    let verdict = 'CONTINUE';
+    for (const f of findings)
+        if (f.verdict !== 'WARN' && RANK[f.verdict] > RANK[verdict])
+            verdict = f.verdict;
+    const blocking = findings.filter((f) => f.verdict !== 'WARN');
+    const warns = findings.length - blocking.length;
+    const summary = blocking.length === 0
+        ? `${stage}: ok${warns ? ` (${warns} warning${warns > 1 ? 's' : ''})` : ''}`
+        : `${stage}: ${verdict} — ${blocking.map((f) => f.reason).join(', ')}`;
+    return { schema: 'reins/bus/stop-report@1', stage, verdict, findings, summary };
+}

package/cli/dist/reins.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { runCheck } from './commands/check.js';
+import { runInstall } from './commands/install.js';
+import { runMigrate } from './commands/migrate.js';
+import { defaultsAsker, stdinAsker } from './lib/ask.js';
+import { EXIT } from './lib/verdict.js';
+const program = new Command()
+    .name('reins')
+    .description('agent harness — install, migrate, update; check keeps agents inside their roles')
+    .version('0.1.0');
+const notYet = (name) => () => {
+    process.stderr.write(`reins ${name}: not implemented yet (see docs/design.md §11)\n`);
+    process.exit(2);
+};
+program
+    .command('install')
+    .description('install the harness at a tier: harness | loop | graph')
+    .argument('<tier>', 'harness | loop | graph')
+    .option('--mode <mode>', 'manual (ask) | auto (detect and apply defaults)', 'manual')
+    .option('--hooks', 'add the reins check line to existing husky hooks (otherwise only proposed)')
+    .option('--dry-run', 'show what would be written')
+    .option('--json')
+    .action(async (tier, o) => {
+    if (!['harness', 'loop', 'graph'].includes(tier)) {
+        process.stderr.write(`reins install: tier must be harness, loop or graph (got "${tier}")\n`);
+        process.exit(2);
+    }
+    const asker = o.mode === 'auto' ? defaultsAsker : await stdinAsker();
+    const r = await runInstall({
+        tier: tier,
+        mode: o.mode,
+        hooks: o.hooks,
+        dryRun: o.dryRun,
+        asker,
+    });
+    asker.close();
+    if (o.json) {
+        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+        process.exit(r.refused ? 2 : 0);
+    }
+    if (r.refused) {
+        process.stderr.write(`reins install: ${r.refused}\n`);
+        process.exit(2);
+    }
+    const a = r.applied;
+    const verb = o.dryRun ? 'would write' : 'wrote';
+    process.stdout.write(`reins install ${tier} — generation before: ${r.generation}\n`);
+    process.stdout.write(`${verb}: ${a.created.length} new, ${a.changed.length} changed; ${a.unchanged.length} already up to date\n`);
+    for (const p of a.created)
+        process.stdout.write(`  + ${p}\n`);
+    for (const p of a.changed)
+        process.stdout.write(`  ~ ${p}\n`);
+    for (const n of r.notes)
+        process.stdout.write(`• ${n}\n`);
+    if (r.history)
+        process.stdout.write(`recorded: ${r.history}\n`);
+});
+program
+    .command('migrate')
+    .description('move an existing harness or .ai/ workspace onto the reins layout')
+    .argument('<tier>', 'harness | loop | graph')
+    .option('--mode <mode>', 'manual | auto', 'manual')
+    .option('--dry-run', 'show the moves without touching anything')
+    .option('--json')
+    .action(async (tier, o) => {
+    if (!['harness', 'loop', 'graph'].includes(tier)) {
+        process.stderr.write(`reins migrate: tier must be harness, loop or graph (got "${tier}")\n`);
+        process.exit(2);
+    }
+    const asker = o.mode === 'auto' || o.dryRun ? defaultsAsker : await stdinAsker();
+    const r = await runMigrate({ tier: tier, mode: o.mode, dryRun: o.dryRun, asker });
+    asker.close();
+    if (o.json) {
+        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+        process.exit(r.refused ? 2 : 0);
+    }
+    if (r.refused) {
+        process.stderr.write(`reins migrate: ${r.refused}\n`);
+        process.exit(2);
+    }
+    const by = (k) => r.moves.filter((m) => m.result === k).length;
+    process.stdout.write(`reins migrate ${tier} — from ${r.generation}${o.dryRun ? ' (dry run)' : ''}\n`);
+    process.stdout.write(o.dryRun
+        ? `would move ${r.moves.length} files\n`
+        : `moved ${by('moved')} · tickets ${by('converted')} · identical ${by('same')} · kept both ${by('kept-both')}\n`);
+    if (o.dryRun)
+        for (const m of r.moves)
+            process.stdout.write(`  ${m.action === 'move' ? ' ' : m.action[0]} ${m.from} → ${m.to}\n`);
+    process.stdout.write(`AGENTS.md: swapped ${r.agents.swapped.join(', ') || 'none'}; inserted ${r.agents.inserted.join(', ') || 'none'}\n`);
+    for (const n of r.report)
+        process.stdout.write(`• ${n}\n`);
+    if (r.history)
+        process.stdout.write(`recorded: ${r.history}\n`);
+});
+for (const n of ['update', 'configure', 'recall', 'status', 'doctor'])
+    program.command(n).allowUnknownOption().allowExcessArguments().action(notYet(n));
+program
+    .command('check')
+    .description('harness verifier: --stage pre-commit|pre-push|test|rc-close, or --drift')
+    .option('--stage <stage>')
+    .option('--drift')
+    .option('--json')
+    .action(async (o) => {
+    let pushRefs = [];
+    if (o.stage === 'pre-push' && !process.stdin.isTTY) {
+        const chunks = [];
+        for await (const c of process.stdin)
+            chunks.push(c);
+        pushRefs = Buffer.concat(chunks).toString('utf8').split('\n').filter(Boolean);
+    }
+    const r = runCheck({ stage: o.stage, drift: o.drift, pushRefs });
+    if (o.json)
+        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+    else {
+        process.stdout.write(`${r.summary}\n`);
+        for (const f of r.findings)
+            process.stdout.write(`  [${f.reason} ${f.verdict}] ${f.path ? `${f.path}: ` : ''}${f.message}${f.resume ? `\n      → ${f.resume}` : ''}\n`);
+    }
+    process.exit(EXIT[r.verdict]);
+});
+program.parseAsync(process.argv);