fux-engine 0.3.2__tar.gz → 0.4.0__tar.gz

{fux_engine-0.3.2 → fux_engine-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fux-engine
-Version: 0.3.2
+Version: 0.4.0
 Summary: Fux — a portable agent-aware knowledge engine: rules, memory, narrative, and graph in one frontmatter substrate.
 Author-email: arpit arya <arpitarya.me@gmail.com>
 License: MIT
@@ -31,6 +31,8 @@ Requires-Dist: tree-sitter>=0.23; extra == "ast"
 Requires-Dist: tree-sitter-language-pack>=0.7; extra == "ast"
 Provides-Extra: pdf
 Requires-Dist: pypdf>=4.0; extra == "pdf"
+Provides-Extra: critic
+Requires-Dist: anthropic>=0.40; extra == "critic"
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: build>=1.0; extra == "dev"
@@ -41,15 +43,34 @@ Dynamic: license-file
 
 # Fux
 
-> A portable, agent-aware **knowledge engine**. One frontmatter substrate →
-> derived **index**, **graph**, and **memory** views. `$0` deterministic
-> maintenance — no mandatory LLM calls. Continuously referenced, cheaply
-> maintained.
+> **Fux records *why* your code is the way it is — and checks it's still true.**
+> A portable, agent-aware knowledge engine: one frontmatter substrate → derived
+> **index**, **graph**, and **memory** views. `$0` and deterministic — zero
+> third-party deps, no mandatory LLM calls. Author each rule once; your agent
+> reads a cheap one-line index first and opens the full rule only when it's
+> relevant — and `fux seal` lets `fux check` tell you when the governed code
+> drifted out from under it.
+
+> **New in v0.4.0 — the constitutional-app engine.** Govern where trust lives, opt-in and
+> `$0`: give a rule a `tier` (`constitutional` · `standard` · `advisory`); author principles
+> by two-agent **`/fux debate`**; **`fux ratify`** a rule into a tamper-evident constitution
+> (sealed in **`.fux/constitution.lock`** — any later edit/add/delete is an always-blocking
+> `tampered` finding); critique changes against the constitution with **`fux critic`** before
+> they land (deterministic pass first, no LLM); and **`fux gate`** reports every ungoverned
+> path (report-first, never blocks). The AI self-critique ships behind an opt-in **`[critic]`**
+> extra — the default install stays model-free. Adopting it changes nothing until you opt in.
+
+<!-- launch: replace the line below with the demo GIF — `fux why day-pnl` → rule + why +
+     governed code, then the Solar Terminal graph igniting the `governs` links.
+     Storyboard + capture script: docs/launch/gif-storyboard.md -->
+<p align="center"><em>▶ demo GIF goes here — see <a href="docs/launch/gif-storyboard.md">docs/launch/gif-storyboard.md</a></em></p>
+
+**Pronounced "fox."** (Say it like the animal — *fux* → *fox*.)
 
 Named after *Johann Joseph Fux*, author of *Gradus ad Parnassum* (1725) — the
 counterpoint treatise every composer learned the rules from. A tool that codifies
-and enforces rules, named after the man who wrote *the* rulebook. Sits beside
-`wagner`, `bach`, `orff`.
+and enforces rules, named after the man who wrote *the* rulebook. (The name is
+deliberate.) Sits beside `wagner`, `bach`, `orff`.
 
 Fux **unifies and replaces** three things a project usually runs separately — the
 structural graph (graphify), cross-session memory, and the narrative docs — and
@@ -73,12 +94,14 @@ So: write the *why* down once → it's found fast, stays correct, and never gets
 ## Why
 
 The *why* behind a formula — why current value not invested cost, why
-INR-normalize first, which cost-basis method — usually lives only as an inline
+dollar-normalize first, which cost-basis method — usually lives only as an inline
 comment, invisible until someone greps for it. Fux makes that knowledge
 **first-class**: one entry, authored once, served back through a tiny index (read
 first) plus lazily-opened rules (read only when relevant). Lookups run ~5–10×
 cheaper and more correct on every later session — and you don't have to take that
-on faith: **`fux savings`** measures the multiplier from your own file sizes.
+on faith: **`fux savings`** measures the multiplier from your own file sizes and
+prices the win in **real dollars** (configurable `usd_per_mtok`, default = Claude
+Opus 4.8's $5/M input rate), per lookup and as a cumulative ledger.
 
 ## Install
 
@@ -102,10 +125,13 @@ fux why day-pnl [--history]    # explain a rule (+ how its *why* evolved, via gi
 fux refs src/aggregator.py     # which rules govern this file
 fux recall "how is day P&L computed" --hybrid  # BM25F; RRF-fuse lexical+semantic+graph
 fux seal --all                 # bind rules to an AST fingerprint of their code
+fux debate "<rule>" (skill)    # two-agent free debate → you ratify the result
+fux ratify <id> --by Arpit     # ratify a constitutional rule (tamper-evident; the only path)
+fux critic "<change>"          # critique a change vs principles before it lands (deterministic pass; $0)
 fux coverage                   # % of important files with a governing rule
 fux verify --fuzz              # run invariant `check:`; boundary-fuzz for div-by-zero
 fux mine                       # surface candidate rules latent in the code (drafts)
-fux savings "how is day P&L computed"  # measured token-cost win (+ cumulative ledger)
+fux savings "how is day P&L computed"  # measured token + dollar cost win (+ cumulative ledger)
 fux lint                       # rule *quality*: missing why / code_refs / edges
 fux stats                      # knowledge-health dashboard + score
 fux gate --install             # wire a git pre-commit enforcement hook
@@ -170,6 +196,31 @@ Beyond authoring, Fux **enforces and reports**: `fux lint` grades rule quality,
 `fux stats` scores knowledge health, `fux gate` blocks drift at commit/CI time,
 and `fux mcp` exposes the whole substrate to agents over MCP.
 
+**Constitutional tier (opt-in):** a rule's `tier` (`constitutional` · `standard` ·
+`advisory`) sets how hard it bites — constitutional rules block in any mode. A principle
+*becomes* law through `/fux debate "<rule>"` — a skill that spawns **two sub-agents** (no
+assigned sides, blind first passes, anti-sycophancy gates) and escalates to **you** as
+tie-breaker — then `fux ratify` makes it tamper-evident: it stamps a `content_seal` (and the
+debate's `debate_hash`) and records the rule in a committed `.fux/constitution.lock`, so any
+in-place edit, add, or delete becomes an always-blocking `tampered` finding. The debate is
+the *host session's* tokens; Fux's own code never calls an LLM (a guard test proves the
+maintenance path is model-free). All deterministic and `$0`. Default behaviour is unchanged
+until you ratify (`tier` defaults to `standard`).
+
+Each principle is tagged `enforcement: deterministic` (money/PII/numbers — decided by a
+`check:`/seal, **never** sent to the AI critic) or `judgment` (tone/completeness — decided
+by AI self-critique, **never** faked as a machine check); the split is enforced structurally
+by a `$0` router, and `fux check` flags untagged rules that look like principles so backfill
+is guided, not guessed.
+
+At the action boundary (PreToolUse / pre-commit), `fux critic "<change>"` runs the
+**deterministic pass first** (hard-invariant fails block, no LLM), then the host agent
+self-critiques the `judgment` principles with its own tokens (the `critic` skill drives the
+bounded revise / escalate / `/fux debate` loop); verdicts land in `.fux/out/critic.jsonl`,
+and `fux gate` reports any ungoverned `important_globs` path (report-first, never blocks).
+A headless AI critic for no-session/runtime use ships behind an opt-in `[critic]` extra
+(mirroring `[embeddings]`) — the default install stays model-free.
+
 For cross-session memory it stays **authored, not captured**: an opt-in `capture`
 hook queues *which* files changed for `fux distill` (human-confirmed) rather than
 auto-summarising, and `type: memory` entries **decay** after a TTL so stale notes

{fux_engine-0.3.2 → fux_engine-0.4.0}/README.md

@@ -2,15 +2,34 @@
 
 # Fux
 
-> A portable, agent-aware **knowledge engine**. One frontmatter substrate →
-> derived **index**, **graph**, and **memory** views. `$0` deterministic
-> maintenance — no mandatory LLM calls. Continuously referenced, cheaply
-> maintained.
+> **Fux records *why* your code is the way it is — and checks it's still true.**
+> A portable, agent-aware knowledge engine: one frontmatter substrate → derived
+> **index**, **graph**, and **memory** views. `$0` and deterministic — zero
+> third-party deps, no mandatory LLM calls. Author each rule once; your agent
+> reads a cheap one-line index first and opens the full rule only when it's
+> relevant — and `fux seal` lets `fux check` tell you when the governed code
+> drifted out from under it.
+
+> **New in v0.4.0 — the constitutional-app engine.** Govern where trust lives, opt-in and
+> `$0`: give a rule a `tier` (`constitutional` · `standard` · `advisory`); author principles
+> by two-agent **`/fux debate`**; **`fux ratify`** a rule into a tamper-evident constitution
+> (sealed in **`.fux/constitution.lock`** — any later edit/add/delete is an always-blocking
+> `tampered` finding); critique changes against the constitution with **`fux critic`** before
+> they land (deterministic pass first, no LLM); and **`fux gate`** reports every ungoverned
+> path (report-first, never blocks). The AI self-critique ships behind an opt-in **`[critic]`**
+> extra — the default install stays model-free. Adopting it changes nothing until you opt in.
+
+<!-- launch: replace the line below with the demo GIF — `fux why day-pnl` → rule + why +
+     governed code, then the Solar Terminal graph igniting the `governs` links.
+     Storyboard + capture script: docs/launch/gif-storyboard.md -->
+<p align="center"><em>▶ demo GIF goes here — see <a href="docs/launch/gif-storyboard.md">docs/launch/gif-storyboard.md</a></em></p>
+
+**Pronounced "fox."** (Say it like the animal — *fux* → *fox*.)
 
 Named after *Johann Joseph Fux*, author of *Gradus ad Parnassum* (1725) — the
 counterpoint treatise every composer learned the rules from. A tool that codifies
-and enforces rules, named after the man who wrote *the* rulebook. Sits beside
-`wagner`, `bach`, `orff`.
+and enforces rules, named after the man who wrote *the* rulebook. (The name is
+deliberate.) Sits beside `wagner`, `bach`, `orff`.
 
 Fux **unifies and replaces** three things a project usually runs separately — the
 structural graph (graphify), cross-session memory, and the narrative docs — and
@@ -34,12 +53,14 @@ So: write the *why* down once → it's found fast, stays correct, and never gets
 ## Why
 
 The *why* behind a formula — why current value not invested cost, why
-INR-normalize first, which cost-basis method — usually lives only as an inline
+dollar-normalize first, which cost-basis method — usually lives only as an inline
 comment, invisible until someone greps for it. Fux makes that knowledge
 **first-class**: one entry, authored once, served back through a tiny index (read
 first) plus lazily-opened rules (read only when relevant). Lookups run ~5–10×
 cheaper and more correct on every later session — and you don't have to take that
-on faith: **`fux savings`** measures the multiplier from your own file sizes.
+on faith: **`fux savings`** measures the multiplier from your own file sizes and
+prices the win in **real dollars** (configurable `usd_per_mtok`, default = Claude
+Opus 4.8's $5/M input rate), per lookup and as a cumulative ledger.
 
 ## Install
 
@@ -63,10 +84,13 @@ fux why day-pnl [--history]    # explain a rule (+ how its *why* evolved, via gi
 fux refs src/aggregator.py     # which rules govern this file
 fux recall "how is day P&L computed" --hybrid  # BM25F; RRF-fuse lexical+semantic+graph
 fux seal --all                 # bind rules to an AST fingerprint of their code
+fux debate "<rule>" (skill)    # two-agent free debate → you ratify the result
+fux ratify <id> --by Arpit     # ratify a constitutional rule (tamper-evident; the only path)
+fux critic "<change>"          # critique a change vs principles before it lands (deterministic pass; $0)
 fux coverage                   # % of important files with a governing rule
 fux verify --fuzz              # run invariant `check:`; boundary-fuzz for div-by-zero
 fux mine                       # surface candidate rules latent in the code (drafts)
-fux savings "how is day P&L computed"  # measured token-cost win (+ cumulative ledger)
+fux savings "how is day P&L computed"  # measured token + dollar cost win (+ cumulative ledger)
 fux lint                       # rule *quality*: missing why / code_refs / edges
 fux stats                      # knowledge-health dashboard + score
 fux gate --install             # wire a git pre-commit enforcement hook
@@ -131,6 +155,31 @@ Beyond authoring, Fux **enforces and reports**: `fux lint` grades rule quality,
 `fux stats` scores knowledge health, `fux gate` blocks drift at commit/CI time,
 and `fux mcp` exposes the whole substrate to agents over MCP.
 
+**Constitutional tier (opt-in):** a rule's `tier` (`constitutional` · `standard` ·
+`advisory`) sets how hard it bites — constitutional rules block in any mode. A principle
+*becomes* law through `/fux debate "<rule>"` — a skill that spawns **two sub-agents** (no
+assigned sides, blind first passes, anti-sycophancy gates) and escalates to **you** as
+tie-breaker — then `fux ratify` makes it tamper-evident: it stamps a `content_seal` (and the
+debate's `debate_hash`) and records the rule in a committed `.fux/constitution.lock`, so any
+in-place edit, add, or delete becomes an always-blocking `tampered` finding. The debate is
+the *host session's* tokens; Fux's own code never calls an LLM (a guard test proves the
+maintenance path is model-free). All deterministic and `$0`. Default behaviour is unchanged
+until you ratify (`tier` defaults to `standard`).
+
+Each principle is tagged `enforcement: deterministic` (money/PII/numbers — decided by a
+`check:`/seal, **never** sent to the AI critic) or `judgment` (tone/completeness — decided
+by AI self-critique, **never** faked as a machine check); the split is enforced structurally
+by a `$0` router, and `fux check` flags untagged rules that look like principles so backfill
+is guided, not guessed.
+
+At the action boundary (PreToolUse / pre-commit), `fux critic "<change>"` runs the
+**deterministic pass first** (hard-invariant fails block, no LLM), then the host agent
+self-critiques the `judgment` principles with its own tokens (the `critic` skill drives the
+bounded revise / escalate / `/fux debate` loop); verdicts land in `.fux/out/critic.jsonl`,
+and `fux gate` reports any ungoverned `important_globs` path (report-first, never blocks).
+A headless AI critic for no-session/runtime use ships behind an opt-in `[critic]` extra
+(mirroring `[embeddings]`) — the default install stays model-free.
+
 For cross-session memory it stays **authored, not captured**: an opt-in `capture`
 hook queues *which* files changed for `fux distill` (human-confirmed) rather than
 auto-summarising, and `type: memory` entries **decay** after a TTL so stale notes

{fux_engine-0.3.2 → fux_engine-0.4.0}/fux/__init__.py

@@ -3,4 +3,4 @@
 One frontmatter substrate → derived index, graph, and memory views.
 $0 deterministic maintenance; no mandatory LLM calls. See docs/fux-plan.md.
 """
-__version__ = "0.3.2"
+__version__ = "0.4.0"

fux_engine-0.4.0/fux/baseline.py

@@ -0,0 +1,35 @@
+"""§5b migration guard — snapshot findings, surface only the NEW ones ($0).
+
+A *transient* upgrade guard, not a regression subsystem: `fux check --baseline-write`
+snapshots current findings (canonical: kind, rule_id, message) pre-upgrade; `fux gate
+--baseline` re-runs and fails only on findings absent from the snapshot, so a backward-
+compatible upgrade is provably a no-op. Reuses the `Finding` serialization; stdlib only.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from fux.findings import Finding
+
+
+def _sig(f: Finding) -> str:
+    return f"{f.kind}\t{f.rule_id}\t{f.message}"
+
+
+def write(path: Path, findings: list[Finding]) -> int:
+    """Snapshot findings canonically sorted. Returns the count written."""
+    sigs = sorted(_sig(f) for f in findings)
+    path.write_text("\n".join(sigs) + ("\n" if sigs else ""), encoding="utf-8")
+    return len(sigs)
+
+
+def _read(path: Path) -> set[str]:
+    if not path.exists():
+        return set()
+    return {ln for ln in path.read_text(encoding="utf-8").splitlines() if ln.strip()}
+
+
+def new_findings(path: Path, findings: list[Finding]) -> list[Finding]:
+    """Findings absent from the baseline snapshot — the upgrade's new ones."""
+    base = _read(path)
+    return [f for f in findings if _sig(f) not in base]

{fux_engine-0.3.2 → fux_engine-0.4.0}/fux/check.py

@@ -4,7 +4,8 @@ from __future__ import annotations
 import re
 from pathlib import Path
 
-from fux import config, gitutil, governance, loader, paths, schema, seal
+from fux import (config, constitution, critic, gitutil, governance, loader, paths,
+                 schema, seal)
 from fux.findings import Finding
 from fux.model import Rule
 
@@ -25,6 +26,13 @@ def run(root: Path) -> list[Finding]:
         findings += _seal(r, root)
     findings += _conflicts(layered)
     findings += _extractor_drift(fp)
+    findings += constitution.check_tamper(rs.rules)   # constitution layer (plan §6, §7a)
+    findings += constitution.check_lock(root, rs.rules)
+    findings += critic.untagged_candidates(rs.rules)  # advisory backfill guide (plan §3, §5b)
+    tier_of = {r.id: str(r.fm.get("tier", "standard")) for r in rs.rules}
+    for f in findings:
+        f.tier = tier_of.get(f.rule_id, "standard")   # constitution layer (plan §6)
+    findings.sort(key=lambda f: (f.kind, f.rule_id, f.message))  # canonical → baseline diff
     _write_drift(fp, findings)
     return findings
 
@@ -133,8 +141,9 @@ def _conflicts(layered: list[Rule]) -> list[Finding]:
 def _write_drift(fp: paths.Footprint, findings: list[Finding]) -> None:
     lines = ["# Fux DRIFT report", "",
              f"_{len(findings)} finding(s)._" if findings else "_No drift — all rules current._", ""]
-    for kind in ("schema", "dead-ref", "conflict", "stale", "plan-drift", "invariant",
-                 "memory-stale", "unsealed", "extractor-drift"):
+    for kind in ("tampered", "schema", "dead-ref", "conflict", "stale", "plan-drift",
+                 "invariant", "memory-stale", "unsealed", "untagged-candidate",
+                 "extractor-drift"):
         group = [f for f in findings if f.kind == kind]
         if group:
             lines.append(f"## {kind} ({len(group)})")

{fux_engine-0.3.2 → fux_engine-0.4.0}/fux/cli.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 import argparse
 
-from fux import __version__, clicmds, cligraph, cliquery, hooks
+from fux import __version__, clicmds, cliconstitution, cligraph, cliquery, hooks
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -20,6 +20,8 @@ def build_parser() -> argparse.ArgumentParser:
     bld.set_defaults(fn=clicmds.cmd_build)
     chk = sub.add_parser("check", help="validate schema/refs/staleness/conflicts")
     chk.add_argument("--fix", action="store_true", help="apply mechanical $0 repairs")
+    chk.add_argument("--baseline-write", metavar="FILE",
+                     help="snapshot current findings for the §5b migration gate (then exit)")
     chk.set_defaults(fn=clicmds.cmd_check)
 
     sub.add_parser("context", help="emit the compact INDEX (SessionStart hook)").set_defaults(fn=clicmds.cmd_context)
@@ -42,6 +44,18 @@ def build_parser() -> argparse.ArgumentParser:
     sl.add_argument("--all", action="store_true", help="seal every rule with resolvable code")
     sl.set_defaults(fn=cliquery.cmd_seal)
 
+    rt = sub.add_parser("ratify", help="ratify a constitutional rule (stamp + seal + lock; no LLM)")
+    rt.add_argument("id")
+    rt.add_argument("--by", help="named human ratifier (default: git user.name)")
+    rt.add_argument("--date", help="ISO ratification date (default: today)")
+    rt.add_argument("--debate", metavar="FILE",
+                    help="debate transcript (from /fux debate) to hash into ratification.debate_hash")
+    rt.set_defaults(fn=cliconstitution.cmd_ratify)
+
+    cr = sub.add_parser("critic", help="critique a proposed change against principles (deterministic pass first; $0)")
+    cr.add_argument("proposal", help="the proposed change / commit message / diff summary to critique")
+    cr.set_defaults(fn=cliconstitution.cmd_critic)
+
     refs = sub.add_parser("refs", help="reverse lookup: which rules govern this file")
     refs.add_argument("file")
     refs.set_defaults(fn=cliquery.cmd_refs)
@@ -58,7 +72,7 @@ def build_parser() -> argparse.ArgumentParser:
     vf.set_defaults(fn=cliquery.cmd_verify)
     sub.add_parser("tour", help="emit an ordered ONBOARDING.md").set_defaults(fn=cliquery.cmd_tour)
 
-    sv = sub.add_parser("savings", help="estimate the token-cost win of Fux ($0)")
+    sv = sub.add_parser("savings", help="estimate the token + dollar cost win of Fux ($0)")
     sv.add_argument("query", nargs="?", help="optional: cost a specific lookup")
     sv.add_argument("--top", type=int, default=3)
     sv.add_argument("--reset", action="store_true", help="clear the cumulative cost ledger")
@@ -82,6 +96,8 @@ def build_parser() -> argparse.ArgumentParser:
     gt = sub.add_parser("gate", help="CI / pre-commit enforcement (exit 2 on blocking)")
     gt.add_argument("--install", action="store_true", help="install a git pre-commit hook")
     gt.add_argument("--strict-lint", action="store_true", help="treat lint findings as blocking")
+    gt.add_argument("--baseline", metavar="FILE",
+                    help="§5b migration gate: fail only on findings new since this snapshot")
     gt.set_defaults(fn=clicmds.cmd_gate)
 
     sub.add_parser("mcp", help="serve the substrate over MCP (stdio JSON-RPC)").set_defaults(fn=clicmds.cmd_mcp)

{fux_engine-0.3.2 → fux_engine-0.4.0}/fux/clicmds.py

@@ -5,8 +5,8 @@ import shutil
 import subprocess
 from pathlib import Path
 
-from fux import (build, check, config, context, fix, gate, hookinstall, importer,
-                 initcmd, mcpserver, paths, serve)
+from fux import (baseline, build, check, config, context, fix, gate, hookinstall,
+                 importer, initcmd, mcpserver, paths, serve)
 from fux.cliutil import root
 from fux.findings import blocking
 
@@ -51,6 +51,10 @@ def cmd_build(args) -> int:
 def cmd_check(args) -> int:
     here = root()
     findings = check.run(here)
+    if getattr(args, "baseline_write", None):
+        n = baseline.write(Path(args.baseline_write), findings)
+        print(f"✔ baseline written: {n} finding(s) → {args.baseline_write}")
+        return 0
     if args.fix:
         for n in fix.apply(here, findings):
             print(f"✔ fixed: {n}")
@@ -77,7 +81,8 @@ def cmd_gate(args) -> int:
         print(f"✔ pre-commit gate installed → {hook}")
         print("  it runs `fux gate` on every commit; bypass once with `git commit --no-verify`.")
         return 0
-    code, report = gate.run(here, strict_lint=args.strict_lint)
+    base = Path(args.baseline) if getattr(args, "baseline", None) else None
+    code, report = gate.run(here, strict_lint=args.strict_lint, baseline=base)
     print(report)
     return code
 
@@ -166,15 +171,15 @@ def cmd_setup(_args) -> int:
     skills_src = data / "skills"
     _copy_skill(skills_src / "fux", skills_dir / "fux")
     print(f"✔ /fux skill  → {skills_dir / 'fux'}/")
-    for name in ("plan", "adr", "trace", "savings", "distill", "fetch-rules"):
+    for name in ("plan", "adr", "debate", "critic", "trace", "savings", "distill", "fetch-rules"):
         src = skills_src / name
         if src.exists():
             _copy_skill(src, skills_dir / f"fux-{name}")
-    print(f"✔ sub-skills  → {skills_dir}/fux-{{plan,adr,trace,savings,distill,fetch-rules}}/")
+    print(f"✔ sub-skills  → {skills_dir}/fux-{{plan,adr,debate,critic,trace,savings,distill,fetch-rules}}/")
 
     codex_skills_dir.mkdir(parents=True, exist_ok=True)
     _copy_skill(skills_src / "fux", codex_skills_dir / "fux")
-    for name in ("plan", "adr", "trace", "savings", "distill", "fetch-rules"):
+    for name in ("plan", "adr", "debate", "critic", "trace", "savings", "distill", "fetch-rules"):
         src = skills_src / name
         if src.exists():
             _copy_skill(src, codex_skills_dir / f"fux-{name}")

fux_engine-0.4.0/fux/cliconstitution.py

@@ -0,0 +1,61 @@
+"""CLI handlers for the constitution layer — `ratify` + `critic` (deterministic, no LLM)."""
+from __future__ import annotations
+
+import hashlib
+from datetime import date as _date
+from pathlib import Path
+
+from fux import config, constitution, criticloop, gitutil, loader, paths
+from fux.cliutil import root
+
+
+def cmd_ratify(args) -> int:
+    """Stamp ratification + freeze the seal + update the lock — the only path to the apex."""
+    here = root()
+    cfg = config.load(paths.Footprint(here).config)
+    rules = loader.resolve(here, cfg).rules
+    by = args.by or gitutil.user_name(here) or ""
+    if not by:
+        print("fux: no ratifier — pass --by <name> (or set git user.name)")
+        return 1
+    when = args.date or _date.today().isoformat()
+    dhash = None
+    if args.debate:
+        dpath = Path(args.debate)
+        if not dpath.is_file():
+            print(f"fux: debate transcript not found: {args.debate}")
+            return 1
+        dhash = hashlib.sha256(dpath.read_bytes()).hexdigest()[:16]
+    try:
+        r = constitution.ratify(here, rules, args.id, by=by, date=when, debate_hash=dhash)
+    except KeyError:
+        print(f"fux: no rule with id '{args.id}'")
+        return 1
+    except ValueError as e:
+        print(f"fux: {e}")
+        return 1
+    print(f"✔ ratified {r.id} → constitutional (by {by}, {when})")
+    print(f"  content_seal frozen{f' + debate_hash {dhash}' if dhash else ''} + "
+          ".fux/constitution.lock updated — the only path into the apex.")
+    return 0
+
+
+def cmd_critic(args) -> int:
+    """Critique a proposed change: deterministic pass first, then list judgment principles the
+    host agent must self-critique. $0, no LLM — the agent (or `[critic]` extra) is the judge."""
+    here = root()
+    result = criticloop.critique(here, args.proposal)
+    criticloop.record(here, result)
+    for v in result.verdicts:
+        mark = {"pass": "✔", "fail": "✗", "needs-judgment": "?"}.get(v.status, "·")
+        print(f"  {mark} [{v.status}] {v.principle}: {v.rationale}".rstrip())
+    pend = result.pending
+    if pend:
+        print(f"\n{len(pend)} judgment principle(s) need self-critique — review each against the "
+              "proposal, revise, escalate if borderline (skills/critic/SKILL.md).")
+    if result.blocked:
+        print("\n✗ critic: a deterministic principle is violated — fix before proceeding.")
+        return 2
+    if not pend:
+        print("\n✔ critic: deterministic pass clean.")
+    return 0

{fux_engine-0.3.2 → fux_engine-0.4.0}/fux/cliquery.py

@@ -106,7 +106,7 @@ def cmd_savings(args) -> int:
         return 0
     rep = savings.build(here, query=getattr(args, "query", None), top=args.top)
     print(savings.render(rep))
-    print(costledger.render_summary(costledger.load(here)), end="")
+    print(costledger.render_summary(costledger.load(here), per_mtok=rep.usd_per_mtok), end="")
     return 0
 
 

{fux_engine-0.3.2 → fux_engine-0.4.0}/fux/config.py

@@ -30,6 +30,8 @@ DEFAULTS = {
     "memory_ttl_days": 180,   # type: memory decays after this many untouched days (§17.3)
     "usage_tracking": False,   # opt-in: record served rules → usage-weighted decay (§17.20c)
     "cost_tracking": False,    # opt-in: record each lookup's savings → cumulative cost.json (§12)
+    "usd_per_mtok": 5.0,       # $/million input tokens for `fux savings` dollar figures (§12);
+                               # default = Claude Opus 4.8 input price. Model-agnostic — override per project.
     "parity_stay": [],        # docs that stay/are out-of-scope for `fux parity` (§17.17)
     "context_budget_tokens": 0,  # >0 ⇒ knapsack-pack the SessionStart INDEX (§17.25)
     "graph_editor": "vscode",  # editor URI scheme for clickable graph.html node links:
@@ -78,6 +80,9 @@ def default_toml() -> str:
         "usage_tracking = false\n\n"
         "# Opt-in: accumulate each lookup's token savings into .fux/cost.json ($0).\n"
         "cost_tracking = false\n\n"
+        "# $/million input tokens used to price `fux savings` in dollars (model-agnostic).\n"
+        "# Default = Claude Opus 4.8 input price; set to your model's rate.\n"
+        "usd_per_mtok = 5.0\n\n"
         "# Docs that stay / are out-of-scope for `fux parity` (beyond conventions,\n"
         "# guardrails) — e.g. process docs that get deleted, not migrated to narrative.\n"
         "parity_stay = []\n\n"

fux_engine-0.4.0/fux/constitution.py

@@ -0,0 +1,100 @@
+"""Constitutional integrity — tamper-evidence, ratification & the lock ($0, deterministic).
+A ratified constitutional rule (§6) carries `ratification.content_seal`, recorded in
+`.fux/constitution.lock`; `fux check` recomputes both → always-blocking `tampered`; `fux
+ratify` is the only path that stamps them. No LLM, no new deps."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from fux import seal
+from fux.findings import Finding
+from fux.model import Rule
+
+LOCK = "constitution.lock"                       # under .fux/
+_VOLATILE = {"ratification", "seal", "updated"}  # change without changing meaning
+
+
+def content_seal(rule: Rule) -> str:
+    """Tamper fingerprint: hash of the rule's normalized body + governing frontmatter
+    (volatile seal/ratification/updated excluded). Reuses seal.py's hash + whitespace fold."""
+    gov = {k: v for k, v in rule.fm.items() if k not in _VOLATILE}
+    blob = json.dumps(gov, sort_keys=True, ensure_ascii=False, default=str)
+    return seal._hash(blob + "\n" + " ".join(rule.body.split()))
+
+
+def _constitutional(rules: list[Rule]) -> list[Rule]:
+    return [r for r in rules if str(r.fm.get("tier")) == "constitutional"]
+
+
+def check_tamper(rules: list[Rule]) -> list[Finding]:
+    """`tampered` for any ratified constitutional rule whose recomputed content_seal no
+    longer matches its stamped `ratification.content_seal` (a body/meaning edit)."""
+    out: list[Finding] = []
+    for r in _constitutional(rules):
+        stored = (r.fm.get("ratification") or {}).get("content_seal")
+        if stored and content_seal(r) != stored:
+            out.append(Finding("tampered", r.id,
+                                "body/frontmatter changed since ratification — constitutional "
+                                "rules never change in place; supersede + re-ratify"))
+    return out
+
+
+def lock_manifest(rules: list[Rule]) -> dict[str, str]:
+    """The expected lock — {id: stamped content_seal} for every ratified constitutional rule."""
+    out = {r.id: (r.fm.get("ratification") or {}).get("content_seal")
+           for r in _constitutional(rules)}
+    return {k: v for k, v in sorted(out.items()) if v}
+
+
+def _lock_path(root: Path) -> Path:
+    return root / ".fux" / LOCK
+
+
+def _read_lock(root: Path) -> dict[str, str]:
+    p = _lock_path(root)
+    if not p.exists():
+        return {}
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def check_lock(root: Path, rules: list[Rule]) -> list[Finding]:
+    """`tampered` wherever `.fux/constitution.lock` and the live ratified set diverge —
+    a constitutional rule added, deleted, or re-stamped outside `fux ratify`."""
+    locked, current = _read_lock(root), lock_manifest(rules)
+    out: list[Finding] = []
+    for rid in sorted(set(locked) | set(current)):
+        lo, cu = locked.get(rid), current.get(rid)
+        if lo == cu:
+            continue
+        why = ("missing/un-ratified on disk — restore + `fux ratify`" if cu is None
+               else "absent from the lock — `fux ratify` to record" if lo is None
+               else "content_seal differs from the lock — changed outside `fux ratify`")
+        out.append(Finding("tampered", rid, "constitution.lock mismatch: " + why))
+    return out
+
+
+def ratify(root: Path, rules: list[Rule], rule_id: str, by: str, date: str,
+           debate_hash: str | None = None) -> Rule:
+    """The only path into the constitutional tier: stamp ratification.{by,date,content_seal,
+    debate_hash?}, freeze the code seal, rewrite `.fux/constitution.lock`. Raises if id absent
+    or not constitutional. Deterministic — no LLM, no clock (caller supplies date + hash)."""
+    from fux import fmwrite
+    rule = next((r for r in rules if r.id == rule_id), None)
+    if rule is None:
+        raise KeyError(rule_id)
+    if str(rule.fm.get("tier")) != "constitutional":
+        raise ValueError(f"{rule_id} is tier={rule.fm.get('tier', 'standard')}, not constitutional")
+    rat = {"by": by, "date": date, "content_seal": content_seal(rule)}
+    rule.fm["ratification"] = {**rat, "debate_hash": debate_hash} if debate_hash else rat
+    if (code_seal := seal.current(root, rule)):
+        rule.fm["seal"] = code_seal
+    rule.path.write_text(fmwrite.dump(rule.fm, rule.body), encoding="utf-8")
+    lock = _lock_path(root)
+    lock.parent.mkdir(parents=True, exist_ok=True)
+    lock.write_text(json.dumps(lock_manifest(rules), indent=2, sort_keys=True) + "\n",
+                    encoding="utf-8")
+    return rule