framein 0.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frameout (Framein)
+
+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

@@ -0,0 +1,249 @@
+# Framein
+
+**Keep one work frame across Claude, Codex, and Gemini.**
+
+Start with one agent, challenge it with another, switch when needed, and close the work with
+validation.
+
+Framein is a local work-state layer for AI coding agents. Keep using Claude, Codex, Gemini,
+slash-command frameworks, skill packs, role-based workflows, or your own agent setup. Framein keeps
+the work underneath them stable: a task contract, decision trail, risk state, validation results, and
+a compact capsule the next model can read.
+
+```text
+start in Claude -> challenge with Codex -> switch when needed -> validate before ship
+```
+
+Status: **public pre-release** (`v0.0.4`). Runtime dependencies: **zero**. Required Node:
+**22.5.0+**.
+
+[Website](https://www.framein.dev) · [Manual](docs/MANUAL.md) · [Install notes](docs/INSTALL.md) · [Code signing policy](docs/CODE_SIGNING.md) · [Security](SECURITY.md)
+
+## Why Framein?
+
+Good PRDs, plans, ADRs, and skill packs help any model do better work. That is useful, and Framein is
+designed to coexist with it.
+
+The pain Framein targets starts when the work has to survive beyond one model or one clean session:
+
+- Your lead model gets stuck and repeats the same approach.
+- You want a different model to challenge the plan, diff, or risk.
+- You need to switch lead model because of quota, model fit, or a dead end.
+- The agent says the task is done before build and tests ran.
+- The next session gets a chat summary instead of the actual contract, validation state, failed attempts, and decisions.
+
+Framein does not replace the coding agent or pretend to be a full multi-agent cockpit. It keeps one
+local work frame under the agents you already use.
+
+## Quick Start
+
+The public npm package is the intended install path, but `framein` is not published to npm yet.
+Until that publish step is complete, install from the public source repository:
+
+```bash
+git clone https://github.com/framein-dev/framein.git
+cd framein
+npm install
+npm run build
+npm install -g .
+framein --version
+```
+
+After npm publication, the install path becomes:
+
+```bash
+npm install -g framein
+```
+
+Initialize a project:
+
+```bash
+cd your-project
+framein init
+framein integrations install all --write
+```
+
+Run the work loop:
+
+```bash
+framein start "add Google OAuth, keep email login"
+framein verify
+
+# When another model should review or continue:
+framein challenge "review the OAuth callback plan" --run
+framein capsule codex
+
+framein ship
+```
+
+Use `challenge` when another model should review a claim or plan. Use `capsule <agent>` when a
+different model should continue from the same local facts. `verify` is a rehearsal; `ship` is the
+enforced gate and exits non-zero when hard validation fails.
+
+## What You See
+
+```text
+$ framein start "add Google OAuth, keep email login"
+task contract
+  goal      add Google OAuth, keep email login
+  preserve  existing email login
+
+$ framein challenge "OAuth callback stores state in session" --run
+reviewer  codex
+verdict   change required
+required  add nonce/state validation
+
+$ framein capsule gemini
+next lead prepared from facts:
+contract · diff · tests · decisions
+
+$ framein ship
+build ok · tests 42/42
+risk high: auth/ touched
+status ready with human gate
+```
+
+The important part is not the text UI. It is that every command writes to the same local work frame,
+so terminal commands, native agent wrappers, MCP tools, and the next model all read the same facts.
+
+## Core Commands
+
+| Need | Command | What it does |
+|---|---|---|
+| Define done | `framein start "<goal>"` | Creates a Task Contract: goal, acceptance, protected areas, non-goals |
+| Edit the contract | `framein task show` / `framein task amend ...` | Reviews or updates the definition of done |
+| Get second opinion | `framein challenge "<proposal>" --run` | Asks a different reviewer role for a bounded objection |
+| Switch model/session | `framein capsule [agent]` | Prepares the next lead from contract, diff, validation, ADRs, and ledger |
+| Run validation | `framein verify` | Runs configured build/test checks and records the result |
+| Check risk | `framein risk` | Flags sensitive blast radius from changed files |
+| Decide ship readiness | `framein ship` | Enforced validation and risk gate for commit/deploy readiness |
+| Recover from loops | `framein rescue` | Detects repeated failures or thrash and offers options |
+| Save a green point | `framein checkpoint <label>` | Records the current commit as last known good |
+
+Full reference: [`docs/MANUAL.md`](docs/MANUAL.md).
+
+## Native Agent Surface
+
+Framein installs logic-less wrappers into the tools agents already understand:
+
+| Host | Surface | Example |
+|---|---|---|
+| Claude / Gemini | slash commands | `/fr:verify`, `/fr:ship`, `/fr:risk` |
+| Codex | project skills | `$fr-verify`, `$fr-ship`, `$fr-capsule` |
+| Terminal / CI | CLI + JSON | `framein ship --json` |
+| MCP-capable clients | local stdio MCP server | `framein mcp serve` |
+
+The generated agent commands expose the same agent-facing verbs across hosts:
+
+| Intent | Claude / Gemini | Codex skill |
+|---|---|---|
+| Start or reset the task contract | `/fr:start` | `$fr-start` |
+| Run build/test validation | `/fr:verify` | `$fr-verify` |
+| Check commit/deploy readiness | `/fr:ship` | `$fr-ship` |
+| Detect a repair loop | `/fr:rescue` | `$fr-rescue` |
+| Read current Framein state | `/fr:status` | `$fr-status` |
+| Ask an independent model to review | `/fr:challenge` | `$fr-challenge` |
+| Check changed-file risk | `/fr:risk` | `$fr-risk` |
+| Show or amend the task contract | `/fr:task` | `$fr-task` |
+| Prepare a model switch | `/fr:capsule` | `$fr-capsule` |
+| Resolve a reviewer debate | `/fr:decide` | `$fr-decide` |
+
+The wrappers do not contain product logic. They call the same local `framein` engine, so a command
+invoked from an agent, a terminal, or CI reads and writes the same contract, validation results, risk, and ledger.
+
+Windows note: generated wrappers use `framein.cmd` to avoid PowerShell execution-policy failures from
+the npm `.ps1` shim inside agent shells.
+
+## How It Works
+
+```text
+framein.store.json (git-friendly snapshot) <-> .frame/store.db (local cache)
+        |
+        v
+Task Contract · ADRs · memory · write locks · ledger · validation results
+        |
+        v
+managed block projection
+        |
+        +--> CLAUDE.md
+        +--> AGENTS.md
+        +--> GEMINI.md
+```
+
+Important behavior:
+
+- `framein init` creates `.frame/store.db`, projects managed blocks, and ensures `.frame/` is ignored.
+- `framein export` writes `framein.store.json` when you want a git-canonical text snapshot.
+- Managed blocks are byte-identical across native context files.
+- User-authored text outside managed markers is preserved.
+- ADRs are append-only; corrections use superseding records.
+- Write locks are atomic conditional upserts with TTL.
+- Runtime dependencies stay at zero.
+
+## Trust Boundary
+
+Framein is local-first:
+
+- No provider credentials are collected.
+- No remote credential relay or subscription pooling.
+- Claude, Codex, and Gemini keep their official CLI authentication.
+- Existing MCP servers and skills are detected/recommended, not proxied or cross-executed.
+- No terminal I/O (TTY) screen-scraping.
+- `framein trust` previews permission-bypass flags; it does not silently enable them.
+- Destructive recovery uses explicit flags, for example `framein rewind --force`.
+- Deployment remains a human gate.
+
+## Current Status
+
+Solid in the current pre-release:
+
+- Store, import/export, managed-block projection
+- Task Contract, Verification Gate, Risk Gate, Rescue, Capsule, Challenge/Decide
+- Logic-less `/fr:*` and `$fr-*` wrappers
+- MCP stdio server and registration helpers
+- Headless delegation to real CLIs where available
+- Windows author environment live-verified
+- `244` automated tests passing
+
+Still being validated:
+
+- public npm publication and post-publish install verification
+- signed standalone executable release hardening for Windows and macOS
+- multi-developer workflows
+- interactive lobby paths such as `/lead`, `/go`, and inline command palette
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+Tests compile first and run from `dist/` through Node's built-in test runner.
+
+Useful focused commands:
+
+```bash
+node --no-warnings --test dist/store.test.js
+node --no-warnings --test --test-name-pattern="supersede" dist/**/*.test.js
+node --no-warnings dist/cli.js <cmd>
+```
+
+Node **22.5.0+** is required because Framein uses built-in `node:sqlite`.
+
+## Documentation
+
+- Manual: [`docs/MANUAL.md`](docs/MANUAL.md)
+- Korean manual backup: [`docs/MANUAL.ko.md`](docs/MANUAL.ko.md)
+- Install troubleshooting: [`docs/INSTALL.md`](docs/INSTALL.md) / [`docs/INSTALL.ko.md`](docs/INSTALL.ko.md)
+- Code signing policy: [`docs/CODE_SIGNING.md`](docs/CODE_SIGNING.md)
+- Website: [framein.dev](https://www.framein.dev)
+
+## License
+
+MIT. Framein by [Frameout](https://frameout.co.kr).
+
+Please keep the copyright and license notice when redistributing substantial
+portions of Framein. See [`NOTICE`](NOTICE) for suggested attribution and brand
+usage notes.

package/dist/adr.js

@@ -0,0 +1,17 @@
+// ADR digest: a compact index embedded into the projected native files.
+// Full ADRs live in the store (queried live via MCP); files carry only a digest.
+export function buildAdrDigest(adrs, opts = {}) {
+    if (adrs.length === 0)
+        return '_No decisions recorded yet._';
+    const max = opts.max ?? 10;
+    // Derived (append-only): an ADR is superseded only if a LATER one references it.
+    const supersededIds = new Set(adrs.filter((a) => a.supersedes != null && a.id > a.supersedes).map((a) => a.supersedes));
+    const recent = [...adrs].sort((a, b) => b.id - a.id).slice(0, max);
+    const lines = recent.map((a) => {
+        const status = supersededIds.has(a.id) ? 'superseded' : a.status;
+        return `- [ADR-${a.id}] ${a.title} (${status})`;
+    });
+    const overflow = adrs.length > recent.length
+        ? `\n- …and ${adrs.length - recent.length} earlier decision(s)` : '';
+    return `${adrs.length} decision(s) recorded. Latest:\n${lines.join('\n')}${overflow}`;
+}

package/dist/anomaly.js

@@ -0,0 +1,39 @@
+// Audit cadence (ADR-0005, F-AUDIT-3): detect "thrash" signals from the task ledger so a
+// reviewer can be pulled in only when an agent is going in circles — not on every turn.
+// Pure function over ledger entries; thresholds are tunable (PRD §11.8).
+export function detectThrash(entries, opts = {}) {
+    const editThreshold = opts.repeatedEdits ?? 3;
+    const failThreshold = opts.repeatedFailures ?? 2;
+    const noProgress = opts.noProgressTurns ?? 5;
+    const signals = [];
+    const editCounts = new Map();
+    const failCounts = new Map();
+    for (const e of entries) {
+        if (e.kind === 'edit' && e.target)
+            editCounts.set(e.target, (editCounts.get(e.target) ?? 0) + 1);
+        if (e.kind === 'test-fail' && e.target)
+            failCounts.set(e.target, (failCounts.get(e.target) ?? 0) + 1);
+    }
+    for (const [target, count] of editCounts) {
+        if (count >= editThreshold)
+            signals.push({ kind: 'repeated-edits', target, count, message: `'${target}' edited ${count}× — possible thrash loop` });
+    }
+    for (const [target, count] of failCounts) {
+        if (count >= failThreshold)
+            signals.push({ kind: 'repeated-failure', target, count, message: `'${target}' failed ${count}× — stuck on the same test` });
+    }
+    // turns accumulated since the last real progress (edit/commit). Other events (ask,
+    // test-fail) are neither progress nor turns — they're skipped, not counted.
+    let trailingTurns = 0;
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const k = entries[i].kind;
+        if (k === 'edit' || k === 'commit')
+            break;
+        if (k === 'turn')
+            trailingTurns++;
+    }
+    if (trailingTurns >= noProgress) {
+        signals.push({ kind: 'no-progress', count: trailingTurns, message: `${trailingTurns} turns without an edit/commit — may be going in circles` });
+    }
+    return signals;
+}

package/dist/bin.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// framein installed-bin entry. The node:sqlite ExperimentalWarning (and any other Node warning) is
+// printed at module-LOAD time, before any in-process filter can run — the only reliable suppression is
+// Node's own `--no-warnings`. So this tiny entry, which imports NOTHING that loads node:sqlite, re-execs
+// the CLI once under `--no-warnings`. stdio:'inherit' keeps stdin/stdout/stderr byte-exact (MCP serve
+// NDJSON, `ask --interactive` / shell `/go` hand-overs all pass straight through) and the child's exit
+// code is propagated. FRAMEIN_NOWARN guards against a re-exec loop; running `node dist/cli.js` directly
+// (dev/tests) bypasses this entirely.
+//
+// EXCEPTION: `mcp serve` is machine-facing — MCP clients read NDJSON on stdout and ignore stderr, so the
+// SQLite warning is harmless there. We skip the re-exec for it to avoid adding any startup latency to the
+// server an agent just spawned (a slow handshake can make a client cancel the first tool call).
+import { spawnSync } from 'node:child_process';
+const argv = process.argv.slice(2);
+const isMcpServe = argv[0] === 'mcp' && argv[1] === 'serve';
+if (process.env.FRAMEIN_NOWARN === undefined && !isMcpServe && typeof process.argv[1] === 'string') {
+    const res = spawnSync(process.execPath, ['--no-warnings', process.argv[1], ...process.argv.slice(2)], {
+        stdio: 'inherit',
+        env: { ...process.env, FRAMEIN_NOWARN: '1' },
+    });
+    if (res.error) {
+        console.error(res.error.message);
+        process.exit(1);
+    }
+    process.exit(res.status ?? 1);
+}
+await import('./cli.js');

package/dist/blast.js

@@ -0,0 +1,51 @@
+// Blast Radius Guard (F-LOOP-6, ADR-0008): detect when a change touches sensitive code and raise
+// the required gates — but only when risk actually changes, matching the audit cadence (ADR-0005:
+// not every task). Pure: map changed file paths to a risk level + required gates. Reading the
+// changed files (git) and acting on the gate live in cli.ts.
+import { PLAIN } from './ui/theme.js';
+// Order matters only for readability; each file is matched against every rule.
+const RULES = [
+    { category: 'secrets', level: 'high', pattern: /(^|\/)\.env(\.|$)|secret|credential|\.pem$|\.key$/i, gate: 'secret scan / rotation validation' },
+    { category: 'auth', level: 'high', pattern: /auth|login|session|oauth|permission|rbac|password/i, gate: 'security review' },
+    { category: 'payment', level: 'high', pattern: /payment|billing|stripe|checkout|invoice|charge/i, gate: 'security review (payments)' },
+    { category: 'migration', level: 'high', pattern: /migrat|\.sql$|schema\.|prisma\/migrations|alembic/i, gate: 'migration rollback validation' },
+    { category: 'deploy', level: 'high', pattern: /dockerfile|docker-compose|\.tf$|terraform|fly\.toml|vercel\.json|(^|\/)k8s\/|\.github\/workflows/i, gate: 'deploy rollback plan' },
+    { category: 'deps', level: 'medium', pattern: /(^|\/)package\.json$|package-lock\.json|yarn\.lock|pnpm-lock\.yaml/i, gate: 'dependency justification' },
+    { category: 'config', level: 'medium', pattern: /(^|\/)config\/|\.env\.example$|settings\.(json|py|ts)|\.config\./i, gate: 'config review' },
+];
+const RANK = { low: 0, medium: 1, high: 2 };
+export function riskRank(level) { return RANK[level]; }
+export function assessBlastRadius(changedFiles) {
+    const hits = [];
+    const gates = new Set();
+    let level = 'low';
+    for (const file of changedFiles) {
+        for (const rule of RULES) {
+            if (rule.pattern.test(file)) {
+                hits.push({ category: rule.category, file });
+                gates.add(rule.gate);
+                if (RANK[rule.level] > RANK[level])
+                    level = rule.level;
+            }
+        }
+    }
+    return { level, hits, requiredGates: [...gates] };
+}
+/** A message when risk INCREASED vs the previous assessment (cadence: only speak on change). */
+export function riskTransition(prev, curr) {
+    if (prev === undefined || RANK[curr] <= RANK[prev])
+        return undefined;
+    return `Risk level changed: ${prev.toUpperCase()} → ${curr.toUpperCase()}`;
+}
+export function renderBlast(a, ui = PLAIN) {
+    if (a.level === 'low')
+        return `Risk level: ${ui.tone('LOW', 'success')} (no sensitive files touched)`;
+    const tone = a.level === 'high' ? 'danger' : 'warning';
+    const lines = [`Risk level: ${ui.tone(a.level.toUpperCase(), tone)}`, 'Reason:'];
+    for (const h of a.hits)
+        lines.push(`  - ${h.category}: ${h.file}`);
+    lines.push('Required before ship:');
+    for (const g of a.requiredGates)
+        lines.push(`  - ${g}`);
+    return lines.join('\n');
+}

package/dist/brief.js

@@ -0,0 +1,21 @@
+// Ownership Brief (F-LOOP-10, ADR-0008): make the explainer produce a doc the user can take
+// OWNERSHIP of — not just a friendly recap. Pure: render the brief skeleton, filling the facts
+// framein already knows (changed files, how to test, how to roll back) and leaving the narrative
+// sections for the live explainer role. Gathering the facts lives in cli.ts.
+const TBD = '  (for the explainer role to fill)';
+export function ownershipBrief(input) {
+    const changed = input.changedFiles?.length
+        ? input.changedFiles.map((f) => `  - ${f}`).join('\n')
+        : '  (no changed files detected)';
+    const sections = [
+        ['What changed', changed],
+        ['How to test it', input.testCommand ? `  ${input.testCommand}` : '  (no test command found)'],
+        ['How to roll it back', input.lastGreen ? `  git reset --hard ${input.lastGreen.slice(0, 7)}  (last green checkpoint)` : '  (no checkpoint recorded — run `frame checkpoint`)'],
+        ['How requests flow', TBD],
+        ['Where configuration lives', TBD],
+        ['Known limitations', TBD],
+        ['What will likely break next', TBD],
+    ];
+    const head = `Ownership brief${input.goal ? `: ${input.goal}` : ''}`;
+    return [head, '', ...sections.map(([h, b]) => `## ${h}\n${b}`)].join('\n');
+}

package/dist/capsule.js

@@ -0,0 +1,64 @@
+// Task Capsule (F-LOOP-4, ADR-0008): when a session compacts, hits quota, or switches CLI, hand
+// over an AUTO-GENERATED structured state — not the chat transcript. The capsule is assembled from
+// what framein already holds (contract + ADRs + git + validation results + ledger), so "no manual
+// handoff; Framein rebuilds the working context from validation results." Pure assembly; the CLI
+// gathers the inputs.
+import { detectThrash } from './anomaly.js';
+import { PLAIN } from './ui/theme.js';
+export function buildCapsule(input) {
+    const ledger = input.ledger ?? [];
+    const recentActivity = ledger.slice(-8).map((e) => `${e.kind}${e.target ? ' ' + e.target : ''}`);
+    // Derive a blocker from a repeated-failure signal when one isn't supplied explicitly.
+    let blocker = input.blocker;
+    const testsAreGreen = input.testSummary !== null && input.testSummary !== undefined && input.testSummary.failed === 0;
+    if (!blocker && !testsAreGreen && ledger.length) {
+        const fail = detectThrash(ledger).find((s) => s.kind === 'repeated-failure');
+        if (fail)
+            blocker = fail.message;
+    }
+    return {
+        goal: input.goal ?? '(no task contract)',
+        branch: input.branch,
+        lastGreen: input.lastGreen,
+        decisions: input.decisions ?? [],
+        changed: input.changedFiles ?? [],
+        evidence: input.testSummary ?? undefined,
+        blocker,
+        lastDelegation: input.lastDelegation,
+        handoffTarget: input.handoffTarget,
+        recentActivity,
+    };
+}
+const short = (sha) => sha.slice(0, 7);
+/** Readable capsule for `frame resume` / `frame capsule show`. Empty sections are omitted. */
+export function renderCapsule(c, ui = PLAIN) {
+    const lines = [`task: ${c.goal}`];
+    if (c.branch)
+        lines.push(`branch: ${c.branch}`);
+    if (c.lastGreen)
+        lines.push(`last_green: ${short(c.lastGreen)}`);
+    if (c.decisions.length) {
+        lines.push('decisions:');
+        for (const d of c.decisions)
+            lines.push(`  - ADR-${d.id}: ${d.title}`);
+    }
+    if (c.changed.length) {
+        lines.push('changed:');
+        for (const f of c.changed)
+            lines.push(`  - ${f}`);
+    }
+    if (c.evidence)
+        lines.push(`validation: tests ${c.evidence.passed} passed, ${c.evidence.failed} failed`);
+    if (c.lastDelegation)
+        lines.push(`last_delegation: ${c.lastDelegation.agent} (${c.lastDelegation.ok ? 'ok' : 'failed'})`);
+    if (c.handoffTarget)
+        lines.push(`handoff: ${c.handoffTarget} (armed)`);
+    if (c.blocker)
+        lines.push(ui.tone(`current_blocker: ${c.blocker}`, 'danger'));
+    if (c.recentActivity.length) {
+        lines.push('recent:');
+        for (const a of c.recentActivity)
+            lines.push(`  - ${a}`);
+    }
+    return lines.join('\n');
+}