faf 7.16.2 → 8.0.0

package/dist/interop/command-note.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A command value may carry its own note: `cmd — note`.
+ *
+ * `key_files` already works this way (`path — role`), and the authors turn
+ * that into a `| Path | Role |` table. Commands get the same convention, so a
+ * `.faf` can say what a script actually does:
+ *
+ * ```yaml
+ * commands:
+ *   build: bun run build — clean, bundle cli+index, then tsc
+ * ```
+ *
+ * authors as:
+ *
+ * ```bash
+ * bun run build    # clean, bundle cli+index, then tsc
+ * ```
+ *
+ * Without a note the behaviour is unchanged — the key is the comment, exactly
+ * as before. The separator is the em dash with spaces around it, matching
+ * `key_files`; a bare hyphen is left alone, because shell commands are full of
+ * them (`--force`, `-rf`).
+ *
+ * Every consumer of `data.commands` must split before it renders, or the note
+ * leaks into the command itself — an authored `bun run build — clean…` that a
+ * reader would try to run.
+ */
+/** The separator a command value uses to carry its note. */
+export declare const NOTE_SEPARATOR = " \u2014 ";
+export interface CommandAndNote {
+    /** The command to run, with any note removed. */
+    cmd: string;
+    /** The note the value carried, or null when it carried none. */
+    note: string | null;
+}
+/**
+ * Split a command value into the command and its note.
+ *
+ * @param value  a `commands` value, e.g. `bun run build` or `bun run build — clean, then tsc`
+ */
+export declare function splitCommandNote(value: unknown): CommandAndNote;
+/** The command alone — for prose and for authors that show no comments. */
+export declare function commandOnly(value: unknown): string;

package/dist/interop/inject.d.ts

@@ -123,7 +123,14 @@ export declare function injectFafBlock(path: string, block: string, start?: stri
  *     older block there is an example to faf, and stays below the new one;
  *   - a whole-line START marker sits past more than MAX_OPEN_CONTAINERS
  *     nested lists or quotes: faf did not read that far, and the older block
- *     stays below the new one.
+ *     stays below the new one;
+ *   - a whole-line START or END marker is shown as text with no matching pair
+ *     — a block an older faf truncated, or a pair the two readings read
+ *     differently. faf cannot prove where that block ended, so it is left
+ *     exactly as it is and the new block goes on top. Without this line the
+ *     file is the one case in this family that is prefixed in silence: it
+ *     carries faf's own marker text, so it looks most like faf's to a reader
+ *     and least like it to faf.
  * `label` names the file (`CLAUDE.md`). `existing` is the file's text before
  * the write (null when there was none). faf-mcp and claude-faf-mcp print the
  * same line through this export.

package/dist/wasm/kernel.d.ts

@@ -1,6 +1,6 @@
 import type { KernelScoreResult, FafbInfo } from '../core/types.js';
 export declare function score(yaml: string): KernelScoreResult;
-/** Score a .faf YAML string (33 enterprise slots), as the file is (a leading BOM is not scored). */
+/** Same as {@link score} (always 33) — kept for existing callers (a leading BOM is not scored). */
 export declare function scoreEnterprise(yaml: string): KernelScoreResult;
 /** Validate .faf YAML (a leading BOM is left out, as in {@link score}: `faf check` reads a BOM file). */
 export declare function validate(yaml: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faf",
-  "version": "7.16.2",
+  "version": "8.0.0",
   "description": "Persistent AI context + memory — .faf and .fafm, IANA-registered. Anthropic-merged.",
   "type": "module",
   "icon": "https://faf.one/orange-smiley.svg",

package/project.faf

@@ -1,29 +1,32 @@
 faf_version: "3.0"
 project:
   name: faf-cli
-  version: "7.16.2"
-  goal: "CLI for IANA-registered `.faf` + `.fafm` — context DNA and portable agent memory. TypeScript, Bun-native since v6. package faf-cli v7.16.2 The Discoverable Edition."
+  version: "8.0.0"
+  goal: "CLI for IANA-registered `.faf` + `.fafm` — context DNA and portable agent memory. TypeScript, Bun-native since v6. package faf-cli v8.0.0 The Always33 Edition — scored by the always-33 engine."
   main_language: TypeScript
   type: cli  # found: package.json bin
 # Commands + key_files feed `faf export --agents` (hand values win over detection).
 commands:
   install: bun install
-  build: bun run build
-  dev: bun run dev
-  test: bun run test
-  lint: bun run lint
+  build: bun run build — clean, bundle src/cli.ts to dist, then tsc
+  dev: bun run dev — run the CLI from source, no build
+  test: bun run test — must pass before a change is done
+  lint: bun run lint — eslint over src
+  check:no-hardcode: bun run check:no-hardcode — fail if a build-machine path leaked into dist
 key_files:
-  - src/cli.ts
-  - src/index.ts
-  - src/commands/
-  - src/commands/memory.ts
-  - src/core/
-  - src/detect/
-  - src/fafm/
-  - src/interop/
-  - src/wasm/
-  - package.json
-  - project.faf
+  - src/cli.ts — CLI entry (Commander); builds to the `faf` / `faf-cli` bin
+  - src/index.ts — library entry; builds to `main`, plus the `./pack` export
+  - src/commands/ — one file per faf subcommand (39)
+  - src/commands/memory.ts — `faf memory`, the `.fafm` surface
+  - src/core/ — domain engines (drift, faf-dna, faf-source, cwd-guard)
+  - src/detect/ — stack and project detection, per language
+  - src/fafm/ — the `.fafm` library (soul, from-claude-dir, types)
+  - src/interop/ — the context authors (agents, claude, gemini, cards, copilot)
+  - src/interrogate/ — extractors that read a repo's own files for facts (readme, cargo, compose, env)
+  - src/ui/ — terminal output (colors, display, progress, star-nudge)
+  - src/wasm/ — bridge to faf-scoring-kernel; scoring lives there, not in TS
+  - package.json — scripts, and the bin that maps `faf` to dist/cli.js
+  - project.faf — this file; the DNA every author reads from
 instant_context:
   what_building: CLI for IANA-registered .faf context + .fafm memory
   tech_stack: TypeScript · Bun-native since v6
@@ -43,9 +46,9 @@ stack:
   runtime: slotignored
   database: slotignored
   connection: slotignored
-  hosting: slotignored
-  build: slotignored
-  cicd: slotignored
+  hosting: npm + Homebrew
+  build: Bun (bun build) + tsc
+  cicd: GitHub Actions
   monorepo_tool: slotignored
   package_manager: slotignored
   workspaces: slotignored
@@ -58,7 +61,7 @@ human_context:
   what: Persistent AI Context Standard — project DNA for AI. IANA-registered. Anthropic-merged.
   why: Eliminates 91% context re-discovery tax — define once, AI remembers forever
   where: npm registry, Homebrew, GitHub
-  when: Production since September 2025; Bun-native since v6; current package 7.16.2
+  when: Production since September 2025; Bun-native since v6; current package 8.0.0 (always-33 engine)
   how: bunx faf-cli auto, then project.faf versions with your code — faf show renders it human-visible
 monorepo:
   packages_count: slotignored

package/vendor/faf-scoring-kernel/README.md

@@ -1,14 +1,88 @@
-# faf-scoring-kernel 2.1.0 (vendored)
+# faf-scoring-kernel
 
-WASM built from `~/FAF/faf-rust/crates/faf-wasm-sdk` against `faf-fafb` 1.0.4.
+**faf-scoring-kernel v3.0.0 — The Always33 Edition**
 
-- `compile_fafb` emits **FAFb wire v2**
-- `score_faf` is 21-slot base; `score_faf_enterprise` is 33-slot Mk4
+One engine, one number: `score_faf` is always-33, so a repo scores the same in every FAF app.
 
-Rebuild:
+WASM from the FAF Rust workspace. Scores `.faf` against all 33 slots and compiles `.fafb`. `.faf` is IANA-registered as `application/vnd.faf+yaml`.
+
+## What's New — v3.0.0
+
+One engine, one number: `score_faf` is always-33, so a repo scores the same in every FAF app.
+
+- `score_faf` → always-33 — the same score as faf-kernel, the Rust SDK and the MCP servers
+- `score_faf_enterprise` → alias of `score_faf` (existing callers keep working)
+- `score_fafb` → agrees with `score_faf`
+- `tbd` / `todo` count as empty (placeholders)
+- Engine `sdk_version()` is **3.1.0** (the `faf-wasm-sdk` crate this WASM was built from)
+
+**Upgrading from 2.x:** a `.faf` without its 12 enterprise `slotignored` markers now scores against all 33 slots, so its number can drop (100 → 64). Mark the slots that don't apply as `slotignored` — a 21-slot project carries the 12 enterprise slots that way — and the score returns.
+
+## Install
 
 ```bash
-# wasm-opt -all emits stringref (Node 20 rejects). Crate metadata has wasm-opt = false.
-wasm-pack build --target nodejs --release --out-dir /tmp/faf-scoring-kernel-v2
-# copy faf_wasm_sdk* into this directory
+npm install faf-scoring-kernel
+```
+
+Node.js 16+ and Bun.
+
+## Usage
+
+```javascript
+const kernel = require('faf-scoring-kernel');
+
+const yaml = `faf_version: 2.5.0
+project:
+  name: my-app
+  goal: Ship a fast CLI
+  main_language: Rust
+`;
+
+const result = JSON.parse(kernel.score_faf(yaml));
+console.log(result.score, result.populated, '/', result.active); // active = 33 minus slotignored
+
+const bytes = kernel.compile_fafb(yaml);
+console.log(String.fromCharCode(bytes[0], bytes[1], bytes[2], bytes[3])); // FAFB
+console.log(JSON.parse(kernel.decompile_fafb(bytes)).version);           // 2.0
 ```
+
+## API
+
+8 pure-function exports. No classes. No state.
+
+| Function | Input | Output |
+|----------|-------|--------|
+| `sdk_version()` | — | engine version string (`3.1.0`) |
+| `score_faf(yaml)` | YAML string | JSON — always-33 |
+| `score_faf_enterprise(yaml)` | YAML string | JSON — same as `score_faf` |
+| `validate_faf(yaml)` | YAML string | `boolean` |
+| `compile_fafb(yaml)` | YAML string | `Uint8Array` — FAFb v2 |
+| `decompile_fafb(bytes)` | `Uint8Array` | JSON string |
+| `score_fafb(bytes)` | `Uint8Array` | JSON string — same score as `score_faf` |
+| `fafb_info(bytes)` | `Uint8Array` | JSON — header + section table |
+
+## Tiers
+
+| Score | Tier |
+|-------|------|
+| 100% | ✪ Trophy |
+| 99% | ★ Gold |
+| 95% | ◆ Silver |
+| 85% | ◇ Bronze |
+| 70% | ● Green |
+| 55% | ● Yellow |
+| 1% | ○ Red |
+| 0% | ♡ White |
+
+✪ is the work glyph for 100%. Same score as 🏆 on social surfaces.
+
+## Links
+
+- [faf.one](https://faf.one) · [the format spec](https://faf.one/spec)
+- [Source](https://github.com/Wolfe-Jam/faf-rust) — `crates/faf-wasm-sdk` (engine) · `npm/faf-scoring-kernel` (this package)
+- [IANA](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml) — `application/vnd.faf+yaml`
+- [faf-cli](https://www.npmjs.com/package/faf-cli) vendors this WASM
+
+## License
+
+MIT

package/vendor/faf-scoring-kernel/faf_wasm_sdk.d.ts

@@ -17,12 +17,15 @@ export function decompile_fafb(bytes: Uint8Array): string;
 export function fafb_info(bytes: Uint8Array): string;
 
 /**
- * Score FAF YAML content — 21-slot base (CLI default). Returns JSON.
+ * Score FAF YAML content with the Mk4 kernel (always-33) — returns JSON.
+ *
+ * Always 33 slots. A 21-slot file carries the 12 enterprise slots as
+ * `slotignored`, so it scores the same here as in every other FAF app.
  */
 export function score_faf(yaml: string): string;
 
 /**
- * Score FAF YAML content — full 33-slot Mk4. Returns JSON.
+ * Same as [`score_faf`] (always-33). Kept so existing callers keep working.
  */
 export function score_faf_enterprise(yaml: string): string;
 

package/vendor/faf-scoring-kernel/faf_wasm_sdk.js

@@ -94,7 +94,10 @@ function fafb_info(bytes) {
 exports.fafb_info = fafb_info;
 
 /**
- * Score FAF YAML content — 21-slot base (CLI default). Returns JSON.
+ * Score FAF YAML content with the Mk4 kernel (always-33) — returns JSON.
+ *
+ * Always 33 slots. A 21-slot file carries the 12 enterprise slots as
+ * `slotignored`, so it scores the same here as in every other FAF app.
  * @param {string} yaml
  * @returns {string}
  */
@@ -127,7 +130,7 @@ function score_faf(yaml) {
 exports.score_faf = score_faf;
 
 /**
- * Score FAF YAML content — full 33-slot Mk4. Returns JSON.
+ * Same as [`score_faf`] (always-33). Kept so existing callers keep working.
  * @param {string} yaml
  * @returns {string}
  */

package/vendor/faf-scoring-kernel/package.json

@@ -1,12 +1,13 @@
 {
   "name": "faf-scoring-kernel",
-  "version": "2.1.0",
-  "description": "FAF Mk4 Scoring Kernel \u2014 WASM from faf-rust. Scores .faf (21/33) and compiles FAFb v2.",
+  "version": "3.0.0",
+  "description": "FAF Mk4 Scoring Kernel — WASM from faf-rust. Scores .faf always-33 and compiles FAFb v2.",
   "license": "MIT",
   "author": "wolfejam <wolfejam@faf.one>",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Wolfe-Jam/faf-rust"
+    "url": "git+https://github.com/Wolfe-Jam/faf-rust.git",
+    "directory": "npm/faf-scoring-kernel"
   },
   "homepage": "https://faf.one",
   "files": [