facult 2.13.9 → 2.15.0

package/docs/pack-upgrades.md

@@ -0,0 +1,73 @@
+# Built-in Pack Upgrades
+
+The built-in operating-model pack is a starting point, not a source of destructive ownership over your `.ai` root.
+
+Use normal install for a new root:
+
+```bash
+fclt templates init operating-model --global
+fclt templates init operating-model --project
+fclt templates init operating-model --root /path/to/.ai
+```
+
+By default, existing files are skipped. This is safe for first install and for adding newly introduced pack files.
+
+## Non-Destructive Update
+
+Use `--update` to refresh only files that still match the previously installed pack copy:
+
+```bash
+fclt templates init operating-model --global --update --dry-run
+fclt templates init operating-model --global --update
+```
+
+`fclt` records a pack manifest under:
+
+```text
+.ai/.facult/packs/facult-operating-model.json
+```
+
+During `--update`, files are overwritten only when their current hash matches the last installed pack hash. If a user or agent edited a file locally, `fclt` skips it and reports it as a local edit.
+
+Use `--force` only when you intentionally want to replace the selected root's pack files:
+
+```bash
+fclt templates init operating-model --global --force
+```
+
+## Legacy Installs
+
+Older installs may not have a pack manifest. In that case, `--update` stays conservative:
+
+- files that already match the current pack are recorded in the manifest
+- missing files are added
+- edited or unknown existing files are skipped
+
+For a legacy root with many local changes, use an agent-assisted review:
+
+```bash
+fclt templates init operating-model --global --update --dry-run --json
+fclt doctor --json --global
+```
+
+Review skipped files before deciding whether to merge changes manually, keep the local version, or replace with `--force`.
+
+## AGENTS.global.md
+
+The pack source stores the composed entry template at `snippets/templates/agents-global.md`. During install or update, `fclt` materializes that template as `AGENTS.global.md` in the target `.ai` root.
+
+That installed `AGENTS.global.md` is not meant to hold every rule.
+
+If first install finds existing agent guidance, `fclt` seeds `AGENTS.global.md` from it and appends the Facult operating-model frame. Global installs look for existing global tool docs such as `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md`; project installs look for repo-local `AGENTS.md` or `CLAUDE.md`.
+
+Seeded files are user-owned. They are intentionally excluded from the pack manifest so `--update` skips them unless you explicitly replace them with `--force` or edit them manually.
+
+Use:
+
+- snippets for injected baseline blocks
+- instructions for detailed doctrine
+- skills for workflow execution
+- agents for delegated review roles
+- local/global config for private user-owned refs
+
+This keeps global agent guidance small while still making the full operating model discoverable.

package/docs/reference.md

@@ -48,8 +48,8 @@ The graph explains how instructions, snippets, config refs, and rendered targets
 
 ```bash
 fclt templates list
-fclt templates init operating-model [--global|--project|--root PATH]
-fclt templates init project-ai
+fclt templates init operating-model [--global|--project|--root PATH] [--update] [--force]
+fclt templates init project-ai [--update] [--force]
 fclt templates init instruction <name>
 fclt templates init snippet <marker>
 fclt templates init skill <name>

package/docs/roadmap.md

@@ -16,6 +16,7 @@ This roadmap tracks remaining product direction for `fclt`.
 - JSON-first `inventory`.
 - `sync --adopt-live` for explicit promotion of live tool edits.
 - Managed sync local-edit protection for rendered docs, config, MCP, and skills.
+- Initial first-party Codex plugin with setup/writeback/evolution/capability-review skills and a CLI-backed MCP wrapper.
 
 ## Current Priorities
 
@@ -48,11 +49,11 @@ This roadmap tracks remaining product direction for `fclt`.
    - Add graph visibility.
    - Include them in status and sync plans.
 
-7. Add a first-party Codex plugin and MCP surface.
-   - Expose safe read/write operations over existing `fclt` behavior.
+7. Expand the first-party Codex plugin and MCP surface.
+   - Add richer setup planning tools beyond the initial CLI wrapper.
    - Keep the CLI and canonical `.ai` roots as the source of truth.
    - Gate high-risk global changes behind explicit review.
-   - Bundle agent-facing skills for work units, writeback, evolution, capability search, and automation setup.
+   - Add more focused agent-facing skills for automation setup, capability search, and upgrade flows.
 
 8. Tighten selector consistency.
    - Use one selector grammar across `list`, `show`, `graph`, `enable`, `disable`, `trust`, `audit`, writeback, and evolution.

package/docs/work-units.md

@@ -0,0 +1,96 @@
+# Work Units
+
+A work unit is a governed unit of agent work. It gives a task enough shape to be executed, checked, integrated, and learned from.
+
+This is broader than capability evolution. Use work-unit framing for coding, research, docs, operations, setup, debugging, product work, and AI capability updates whenever the task has meaningful ambiguity or risk.
+
+## Minimum Shape
+
+A useful work unit names:
+
+- goal: the outcome needed
+- acceptance criteria: what must be true at the end
+- context: source files, systems, docs, messages, or decisions needed for correctness
+- constraints: privacy, permissions, compatibility, deadlines, ownership, and scope limits
+- evidence: checks that confirm progress or falsify assumptions
+- artifact: code, docs, issue, note, draft, proposal, report, or rendered output
+- verification: command, review surface, manual check, or source-of-truth read
+- writeback target: where durable learning belongs if the work teaches something reusable
+
+Keep this implicit for trivial work. Make it explicit when the task is ambiguous, stateful, high-impact, cross-tool, or likely to create reusable learning.
+
+## Why It Matters
+
+Machine execution makes output cheaper. That does not remove the governance problem. It moves pressure into intent, context, review, integration, memory, and feedback.
+
+Work units are the object that keeps those pieces attached. Without them, agents can produce more output while leaving humans to reconstruct what changed, why it changed, what evidence exists, and what should improve next time.
+
+With them:
+
+- the agent knows what done means
+- verification is chosen before the final claim
+- integration risk is visible
+- writeback has evidence and a target
+- repeated friction can become evolution instead of folklore
+
+## How It Connects To fclt
+
+`fclt` ships work-unit guidance in the built-in operating-model pack:
+
+```text
+@builtin/facult-operating-model/instructions/WORK_UNITS.md
+@builtin/facult-operating-model/snippets/global/core/work-units.md
+```
+
+Install it into a canonical root:
+
+```bash
+fclt templates init operating-model --global
+```
+
+Then agents can read the same guidance from `~/.ai/instructions/WORK_UNITS.md`, and rendered global agent files can include the work-unit snippet.
+
+## Examples
+
+Coding work:
+
+```text
+Goal: fix a failing checkout test
+Acceptance: the focused test and relevant integration path pass
+Context: failing output, checkout code, recent commits
+Constraints: preserve public API and user data behavior
+Evidence: test output plus inspected changed path
+Artifact: code diff and summary
+Verification: command output and integration check
+Writeback: only if the failure exposes reusable stale guidance
+```
+
+Research work:
+
+```text
+Goal: answer a product or technical question
+Acceptance: answer is current, source-backed, and separates facts from inference
+Context: user question, relevant docs, date sensitivity
+Constraints: use primary sources when accuracy depends on them
+Evidence: source links and consistency check
+Artifact: concise answer or research note
+Verification: source freshness and source agreement
+Writeback: durable note if the answer will recur
+```
+
+Capability evolution:
+
+```text
+Goal: decide whether writebacks justify changing capability
+Acceptance: proposal exists only when repeated evidence or a clear gap supports it
+Context: grouped writebacks, current target asset, project/global scope
+Constraints: avoid proposal noise and private leakage
+Evidence: writeback ids and affected work units
+Artifact: proposal, applied change, rejection, or no-op note
+Verification: target, scope, proposal kind, and rendered/review artifact
+Writeback: only for new meta-learning about the evolution loop
+```
+
+## Background
+
+The framing is related to the production-model argument in [Governing the Machine](https://www.hack.dance/writing/governing-the-machine): as more work becomes machine-mediated, the hard problem shifts from producing output to governing work, evidence, memory, and improvement.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.13.9",
+  "version": "2.15.0",
   "description": "Manage canonical AI capabilities, sync surfaces, and evolution state.",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,10 @@
     "bin/facult.cjs",
     "docs/**/*.md",
     "docs/**/*.png",
+    "plugins/fclt/.codex-plugin/*.json",
+    "plugins/fclt/.mcp.json",
+    "plugins/fclt/**/*.js",
+    "plugins/fclt/**/*.md",
     "src/**/*.ts",
     "!src/**/*.test.ts",
     "README.md",

package/plugins/fclt/.codex-plugin/plugin.json

@@ -0,0 +1,31 @@
+{
+  "name": "fclt",
+  "version": "0.1.0",
+  "description": "Codex workflows and MCP tools for fclt setup, writeback, evolution, and capability review.",
+  "license": "MIT",
+  "keywords": [
+    "fclt",
+    "facult",
+    "codex",
+    "skills",
+    "mcp",
+    "writeback",
+    "evolution"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "fclt",
+    "shortDescription": "Capability loops for Codex",
+    "longDescription": "Install and operate fclt from Codex: initialize AI capability roots, inspect setup health, record writebacks, review evolution proposals, and keep skills, snippets, instructions, automations, and MCP surfaces improving over time.",
+    "developerName": "Hack Dance",
+    "category": "Productivity",
+    "capabilities": ["Read", "Write", "MCP"],
+    "defaultPrompt": [
+      "Use fclt to check this repo's AI capability setup.",
+      "Record useful fclt writeback from this work.",
+      "Review fclt evolution proposals and next actions."
+    ],
+    "brandColor": "#166534"
+  }
+}

package/plugins/fclt/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "fclt": {
+      "command": "node",
+      "args": ["./scripts/fclt-mcp.js"],
+      "env": {
+        "FCLT_BIN": "fclt"
+      }
+    }
+  }
+}

package/plugins/fclt/scripts/fclt-mcp.js

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+
+const FCLT_BIN = process.env.FCLT_BIN || "fclt";
+const DEFAULT_TIMEOUT_MS = Number(process.env.FCLT_MCP_TIMEOUT_MS || 60_000);
+const CONTENT_LENGTH_RE = /Content-Length:\s*(\d+)/i;
+
+const tools = [
+  {
+    name: "fclt_status",
+    description:
+      "Return fclt status for the current, global, or project scope.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: ["auto", "global", "project"] },
+        cwd: { type: "string" },
+      },
+    },
+  },
+  {
+    name: "fclt_doctor",
+    description: "Run read-only fclt doctor checks and return JSON output.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: ["auto", "global", "project"] },
+        cwd: { type: "string" },
+      },
+    },
+  },
+  {
+    name: "fclt_paths",
+    description: "Return canonical, generated, review, and runtime fclt paths.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: ["auto", "global", "project"] },
+        cwd: { type: "string" },
+      },
+    },
+  },
+  {
+    name: "fclt_init_operating_model",
+    description: "Install or update the built-in operating-model pack.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: ["global", "project"] },
+        cwd: { type: "string" },
+        update: { type: "boolean" },
+        dryRun: { type: "boolean" },
+        force: { type: "boolean" },
+      },
+      required: ["scope"],
+    },
+  },
+  {
+    name: "fclt_writeback_add",
+    description: "Record a durable fclt writeback with evidence.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: ["auto", "global", "project"] },
+        cwd: { type: "string" },
+        kind: { type: "string" },
+        summary: { type: "string" },
+        asset: { type: "string" },
+        evidence: { type: "string" },
+        confidence: {
+          type: "string",
+          enum: ["low", "medium", "high"],
+        },
+      },
+      required: ["kind", "summary"],
+    },
+  },
+  {
+    name: "fclt_writeback_review",
+    description: "List, group, or summarize current fclt writebacks.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: ["auto", "global", "project"] },
+        cwd: { type: "string" },
+        mode: { type: "string", enum: ["list", "group", "summarize"] },
+        by: { type: "string" },
+      },
+    },
+  },
+  {
+    name: "fclt_evolve",
+    description: "List, propose, draft, or review fclt evolution proposals.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: ["auto", "global", "project"] },
+        cwd: { type: "string" },
+        action: {
+          type: "string",
+          enum: ["list", "propose", "draft", "review", "show"],
+        },
+        id: { type: "string" },
+      },
+    },
+  },
+];
+
+function scopeArgs(scope) {
+  if (scope === "global") {
+    return ["--global"];
+  }
+  if (scope === "project") {
+    return ["--project"];
+  }
+  return [];
+}
+
+function boolFlag(name, value) {
+  return value ? [name] : [];
+}
+
+function stringFlag(name, value) {
+  return typeof value === "string" && value.trim() ? [name, value] : [];
+}
+
+function commandForTool(name, args = {}) {
+  switch (name) {
+    case "fclt_status":
+      return ["status", ...scopeArgs(args.scope), "--json"];
+    case "fclt_doctor":
+      return ["doctor", ...scopeArgs(args.scope), "--json"];
+    case "fclt_paths":
+      return ["paths", ...scopeArgs(args.scope), "--json"];
+    case "fclt_init_operating_model":
+      return [
+        "templates",
+        "init",
+        "operating-model",
+        ...scopeArgs(args.scope),
+        ...boolFlag("--update", args.update),
+        ...boolFlag("--dry-run", args.dryRun),
+        ...boolFlag("--force", args.force),
+        "--json",
+      ];
+    case "fclt_writeback_add":
+      return [
+        "ai",
+        "writeback",
+        ...scopeArgs(args.scope),
+        "add",
+        "--kind",
+        args.kind,
+        "--summary",
+        args.summary,
+        ...stringFlag("--asset", args.asset),
+        ...stringFlag("--evidence", args.evidence),
+        ...stringFlag("--confidence", args.confidence),
+      ];
+    case "fclt_writeback_review": {
+      const mode = args.mode || "list";
+      return [
+        "ai",
+        "writeback",
+        ...scopeArgs(args.scope),
+        mode,
+        ...stringFlag("--by", args.by),
+      ];
+    }
+    case "fclt_evolve": {
+      const action = args.action || "list";
+      return [
+        "ai",
+        "evolve",
+        ...scopeArgs(args.scope),
+        action,
+        ...(args.id ? [args.id] : []),
+      ];
+    }
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+function runFclt(args, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn(FCLT_BIN, args, {
+      cwd: cwd || process.cwd(),
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+    }, DEFAULT_TIMEOUT_MS);
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({
+        code,
+        text: [
+          `$ ${FCLT_BIN} ${args.join(" ")}`,
+          stdout.trim(),
+          stderr.trim() ? `stderr:\n${stderr.trim()}` : "",
+        ]
+          .filter(Boolean)
+          .join("\n\n"),
+      });
+    });
+  });
+}
+
+function send(message) {
+  const body = JSON.stringify(message);
+  process.stdout.write(
+    `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`
+  );
+}
+
+async function handle(message) {
+  if (!message || message.id == null) {
+    return;
+  }
+
+  try {
+    if (message.method === "initialize") {
+      send({
+        jsonrpc: "2.0",
+        id: message.id,
+        result: {
+          protocolVersion: "2025-06-18",
+          capabilities: { tools: {} },
+          serverInfo: { name: "fclt", version: "0.1.0" },
+        },
+      });
+      return;
+    }
+    if (message.method === "tools/list") {
+      send({ jsonrpc: "2.0", id: message.id, result: { tools } });
+      return;
+    }
+    if (message.method === "tools/call") {
+      const { name, arguments: args = {} } = message.params || {};
+      const command = commandForTool(name, args);
+      const result = await runFclt(command, args.cwd);
+      send({
+        jsonrpc: "2.0",
+        id: message.id,
+        result: {
+          isError: result.code !== 0,
+          content: [{ type: "text", text: result.text }],
+        },
+      });
+      return;
+    }
+    send({
+      jsonrpc: "2.0",
+      id: message.id,
+      error: { code: -32_601, message: `Method not found: ${message.method}` },
+    });
+  } catch (error) {
+    send({
+      jsonrpc: "2.0",
+      id: message.id,
+      error: {
+        code: -32_000,
+        message: error instanceof Error ? error.message : String(error),
+      },
+    });
+  }
+}
+
+let buffer = Buffer.alloc(0);
+
+process.stdin.on("data", (chunk) => {
+  buffer = Buffer.concat([buffer, chunk]);
+  while (true) {
+    const headerEnd = buffer.indexOf("\r\n\r\n");
+    if (headerEnd === -1) {
+      return;
+    }
+    const header = buffer.slice(0, headerEnd).toString("utf8");
+    const match = CONTENT_LENGTH_RE.exec(header);
+    if (!match) {
+      buffer = Buffer.alloc(0);
+      return;
+    }
+    const length = Number(match[1]);
+    const frameEnd = headerEnd + 4 + length;
+    if (buffer.length < frameEnd) {
+      return;
+    }
+    const body = buffer.slice(headerEnd + 4, frameEnd).toString("utf8");
+    buffer = buffer.slice(frameEnd);
+    handle(JSON.parse(body)).catch((error) => {
+      send({
+        jsonrpc: "2.0",
+        id: null,
+        error: {
+          code: -32_000,
+          message: error instanceof Error ? error.message : String(error),
+        },
+      });
+    });
+  }
+});
+
+if (process.argv.includes("--self-test")) {
+  console.log(
+    JSON.stringify({ tools: tools.map((tool) => tool.name) }, null, 2)
+  );
+  process.exit(0);
+}

package/plugins/fclt/skills/fclt-capability-review/SKILL.md

@@ -0,0 +1,51 @@
+---
+description: Inspect fclt capability roots, docs, snippets, skills, agents, MCP, and automations.
+tags: [fclt, capability, review, inventory]
+---
+
+# fclt-capability-review
+
+## When To Use
+Use this skill when Codex needs to understand what capability exists before changing it.
+
+Use it for:
+
+- checking global and project `.ai` roots
+- finding relevant skills, snippets, instructions, agents, MCP servers, or automations
+- deciding whether a change belongs in global or project scope
+- checking whether managed rendering is enabled or needed
+- reviewing public/private boundaries before publishing docs or pack assets
+
+## Workflow
+
+```bash
+fclt status --json
+fclt inventory --json
+fclt list skills
+fclt list instructions
+fclt list snippets
+fclt graph AGENTS.global.md
+```
+
+For project work:
+
+```bash
+fclt status --project --json
+fclt inventory --project --json
+```
+
+## Rules
+
+- Read existing repo guidance before proposing project capability.
+- Use project scope for repo-specific commands, tests, architecture, or team workflow.
+- Use global scope only for broadly reusable behavior.
+- Keep generated state and review artifacts out of repo-local `.ai`.
+- Prefer adding or updating the smallest unit: instruction, snippet, skill, agent, MCP config, or automation.
+
+## Output
+
+- capability roots found
+- relevant assets
+- scope recommendation
+- missing or stale capability
+- safe next command