KongFangXun/sofagent#cordis-plugin-sofagent-audit

---

What is this

💬 One-sentence version: on entry, it maps your business and writes it down as files; after it leaves, every time your digital employee touches code or files, it passes a security check, leaves a record, and saves a snapshot — traceable and roll-backable when things go wrong. That is what sofagent does.

An open-source FDE Harness layer. The AI-deployment engineer for one-person companies and SMBs — never sleeps, never leaves, and carries its own auditor. It sits between mature Agents (executors: DSH / OpenClaw / WorkBuddy) and the model layer (intelligence sources: general LLMs + bespoke/small post-trained models), governing both sides. Shipped as FDE plugins + Skill + MCP + CLI + Dashboard: on entry, map the business flow clearly, build the ontology graph, deploy the AI nodes in place; on departure, audit every change and keep optimizing.

sofagent does not build its own Agent — execution is delegated to mature hosts (model + tools + sessions). What it delivers is the FDE Harness layer: FDE methodology × Harness engineering, two stages of one job — on entry, generate judgment (where AI belongs, written down as machine-checkable files), after departure, retain judgment (execute against those files 24/7, audit every change). The five Harness capabilities: inject · audit · rollback · distill · evolve — slots into any existing Agent; and it keeps every model (general or bespoke) under control (register / rollout / train / deploy fully audited). How the two stages interlock, and why they cannot be pulled apart, is covered in the dedicated chapter below.

🚂 Why a training engine in a governance repo (30-second answer): governance is capped by data — what audits uncover (which tasks failed, which outputs were substandard) is exactly training fuel. The training engine closes the loop from "problems found by audits → models that fix those problems", letting governance data feed back into the model layer; training assets themselves ship on the commercial side — this repo keeps only protocols and interfaces (externalized / configurable).

📌 Terminology note: the Chinese side uses「后训模块」(post-training module); the English "training engine" is deliberately retained per the 2026-09-03 naming ruling (English-face exemption) — the two refer to the same module. Independent reviewers: this is a known, ruled-on boundary, not a missed rename.

🏞️ Big tech hands you "water" (foundation models) and "riverbeds" (Agent platforms) — but the water is raw, and you don't dare drink it straight. sofagent is the engineering that makes the river usable for a whole city: dams keep the water from flooding, treatment plants turn raw water into drinking water, and pipe networks deliver it to every faucet. Models supply 90% of the intelligence; sofagent supplies the 10% of reliable execution.

Should you install it?

If you are...	Recommendation
Adding discipline to an existing Agent — you already run DSH / OpenClaw / WorkBuddy and want your AI to behave, leave traces, and stay roll-backable when things go wrong	✅ Install now. The core value is exactly the constraint layer (inject · audit · rollback · distill · evolve) — works right after installation
A one-person company / SMB landing AI — no dedicated engineer, you need a "never-quitting FDE" to map your business flow and deploy AI nodes	✅ Install now. The FDE Harness layer is built for this — the full journey from mapping to deployment to post-departure audit
Looking for a turnkey enterprise Agent platform — you expect a complete commercial product (multi-tenancy, permission management, billing, SLA)	⏸️ Hold off. sofagent is a governance layer, not a platform product — platform-grade capabilities are out of this open-source repository's scope. Teams with integration capacity can still embed the constraint layer into their own platform as its governance module; if you need pure turnkey, look at platform products elsewhere
Researching / curious about constraint-layer design — reading code, studying architecture, borrowing methodology	✅ Install now. Full documentation (HANDBOOK / ARCHITECTURE / PHILOSOPHY), MIT licensed

How does it relate to gitleaks / pre-commit? (complementary, not substitutes)

	gitleaks-style scanners	pre-commit hooks	sofagent
Positioning	full-history secret scanning	generic commit-hook framework	Agent behavior audit harness
Evidence	repo text patterns	your own scripts	git-diff hard evidence + Agent logs + decision trail
Coverage	secret leaks	anything (DIY)	24 rules: secrets / scope / injection / privilege / backdoors
Advice	a must for strict secret compliance	keep if you have one	use alongside both — focused on Agent governance

10-minute lightweight trial: npx -y -p @sofagent/audit sofagent-audit (any git repo; secret leaks blocked on the spot).

Core Features

On entry · generate judgment (the FDE stage — deciding where AI belongs and what it's worth, frozen into deliverables):

• 🧭 Map the business flow on entry — five-element deep-dive + three-question triage, capturing every role's process steps and pricing out what each AI node is worth
• 🤖 Deploy AI nodes — three-layer deliverables (documents + Skills + runtime), installed into your existing AI tools; from "you do the work" to "you delegate the work"
• 📦 Judgment frozen into deliverables — every node carries "what counts as done (merge_criteria) · who signs off (approver)", machine-checkable and shared across both stages

After departure · retain judgment (the Harness stage — executing against the deliverables 24/7, writing back as it evolves):

• 🏠 Stay resident after departure — the FDE capability remains for inspection, audit, and optimization, 7×24 online guardian (audit triggers on commit); the human leaves, governance doesn't
• 🔍 Zero-setup audit — npx -y -p @sofagent/audit sofagent-audit, auditing the latest commit of any git repo in seconds (single-machine measured: quick ~1.1s, 50k-line diff ~6.1s; see HANDBOOK)
• 🧱 24 audit rules + 95 MCP tools — secret leaks, out-of-scope edits, injection defense, privilege red lines; judged on two evidence tiers: 19 of the 24 rules run on git-diff hard evidence (effective locally), 4 hybrid (diff + Agent logs, active once an Agent is connected), 1 filesystem scan; log-based rules such as A7/A8 are skipped when no Agent logs exist, violations blocked on the spot (once a critical-layer rule hits, remaining rules are skipped — fail-fast design); evidence is based on local diffs — trust boundaries and known bypass surfaces in LIMITATIONS §3 (quick runs 17 by default; full 24 = 17 default + 7 extensions)
• 🛡️ Automatic snapshot rollback — auto-archived after every audit, one-click restore to any snapshot when something breaks

What is the FDE Harness

FDE = Forward Deployed Engineer — the person who embeds models into real enterprise operations. sofagent turns this role into an open-source FDE Harness layer, sitting between the Agents you already have (DSH / OpenClaw / WorkBuddy) and the model layer. A full FDE business flow has two stages, sewn together by the deliverables handed over in between:

• On entry · generate judgment: four steps — map the business flow → build dual graphs → qualify AI nodes → deploy. Dual graphs = business graph (system boundaries, data flows; read by humans) + ontology graph (shared semantic foundation; read by AI), turning the enterprise into a machine-readable structure; for every AI node, "what counts as done (merge_criteria) · who signs off (approver) · when it runs (trigger)" is judged here and frozen into the deliverables (workflow.yml + ontology + skills).
• After departure · retain judgment: the FDE leaves, the judgment stays — audit triggers automatically on change events (commits) against the frozen criteria, 24 rules judging on git-diff hard evidence; daemon inspects 7×24, snapshots roll back, experience distills back. The human leaves, governance doesn't.

🔗 Why they must be one thing: the deliverables are a living state shared by both stages — written on entry, read during execution, written back during evolution (trial branches promoted to baseline, reflections distilled back). Without FDE, the constraint layer has no criteria to enforce; without the constraint layer, FDE judgment evaporates the moment the engineer leaves. That is where the name "FDE Harness" comes from — not a bundle of an FDE feature and a Harness feature, but two stages of one job.

From FDE to FDEing: the combined effect of the two stages is turning Forward Deployed Engineer (a job title) into Forward Deployed Engineering (a capability) — the person moves on, the capability stays with the deliverables. FDEing is pronounced /ef-di-i-ing/, mirroring "engineering".

Why the FDE Harness

• The bottleneck for enterprise AI is deployment, not the model — mapping workflows, drawing system boundaries, and setting data rules is precisely the FDE's job. MIT NANDA's The GenAI Divide: 95% of enterprise GenAI projects failed to produce value worth a financial statement, while FDE job postings surged 729% in a year (verification in VALIDATION)
• Completeness comes from the union — DSH solves "can work"; sofagent solves "keeps working"; only together do they make a complete FDE Harness (next chapter)
• "Continuous optimization" only holds with a constraint layer — backed by auditable, rollback-capable mechanisms, not promises in prompts. Independent external experiment (ARC-AGI-3): optimizing only the outer Harness around the same model significantly lifts task completion. Verification in VALIDATION · THANKS
• Capabilities are portable, never dead-bound to a platform — the constraint layer is platform-agnostic; the methodology follows the business, not the platform

🔄 Self-bootstrapping: sofagent's first FDE engagement is sofagent itself — the project is a complete FDE business flow (map → build → deploy → depart), and this open-source repository is that deliverable.

Multi-platform Mounting

Sits between the Agents you already use and the model layer — it doesn't replace the model, only adds reliable execution. The FDE Harness layer is platform-agnostic (five forms — plugin / Skill / MCP / CLI / Dashboard — distributed by host capability); the methodology follows the business, not the platform:

Tier	Platform	Constraint injection	Mounting method
Deep integration	DeepSeek Harness	✅ Per-tool-call interception	9 atomic cordis-plugin-sofagent-* mounted into the runtime (1 optional aggregate plugin also available; previous chapter) — 8 lifecycle events incl. tools/pre-execute
Full mounting	OpenClaw	✅ Once per session	Hook-injected four-layer constraints + circuit breaker + 4 OpenClaw plugins
Standard mounting	Claude Code / Cursor	⚠️ Skill self-load	Skills-directory symlink + platform rule file + interception config (content = commit-level 24 rules, not call-level interception)
Thin mounting	WorkBuddy / Codex / Gemini CLI / Hermes	⚠️ Skill self-load	Skills-directory symlink (Codex uses the AGENTS.md mount point) + git-hook audit

• Never assume capability parity — tiers differ in injection strength, not in "supported or not" — DSH intercepts per tool call, OpenClaw injects once per session, and on every other host constraints ride along as Skill text the Agent reads on its own (advisory). "Supports platform X" means the constraint assets work there; it does not mean constraint strength matches other platforms. Before migrating hosts or writing integration docs, check which tier the target host falls into — full matrix in the load-chain HOOK
• Audit fallback is platform-agnostic — sofagent-audit --install-hook runs as a git hook; at every tier, every commit passes through all 24 audit rules, violations hard-blocked. Constraints are advisory; auditing is mandatory

One command selects your mounting tier: bash install.sh --platform <platform-name> (all platforms and differences in HANDBOOK)

v1.4.7: Commercial Platform Interface Edition

🔌 All data and action interfaces the commercial platform needs, delivered in one pass — the organization can see (capability gaps / performance), collaboration can turn (PR lifecycle / workflow-as-object), and data can flow in (data_push dual gate). workflow_gaps capability-gap query (three classes: missing people / missing capability / upgrade due; convertible to bounty PRs) · contribution_query performance export (three-source aggregation: PR weight + decision traces + audit changes; humans and digital workers on the same standard, org-tenant filtering) · pr_submit / pr_review / pr_merge PR lifecycle tools (state machine + two-state confidence, branch→trunk merge linkage) · workflow-as-object CRUD (four tools; owner edits trunk, others open branches; trigger.schedule cron triggers) · G6 node-level visibility (open/private/result-only enum + review-gate linkage) · G7 multi-tenancy v0 (data/<tenant>/ path foundation + orgId attribution field) · G8 first-deploy cron pack (--with-first-deploy-cron — value visible from day one, daemon periodic consumption) · onboard_prompt onboarding-prompt generator · workflow burned into USB keys (auto-load after signature verification) · two-layer audit trail (reducer aggregation + PROV-O export) · TrainChannel cloud-training standard interface (hosted clouds integrate per spec; ssh channel built in-engine) · data_push standard data-push entry (schema validation + sensitive-triage dual gate; enterprise compliance-interception policy reserved as extension) · static-encryption daemon wiring closed (ciphertext-at-rest once the key is ready) · runtime-audit repo-hash isolation (llm-calls / data-sovereignty split per git repo; legacy history readable in place). (Point-in-time figures: MCP 84→95 tools, tests 4107→4279 — see devlog; current scope under Core Features.) Full details in the devlog · earlier versions in CHANGELOG.

FDE Methodology

The first half of the two stages. Many companies adopt AI the wrong way around — they pick models, build platforms, and buy Agents first, only to find nobody uses them. The problem isn't the technology; it's that they haven't figured out their own business processes before handing them to AI.

Most tools teach you how to build Agents; sofagent first answers where AI should go — turning that judgment from guesswork into a repeatable methodology:

Phase	Input	What happens	Deliverable
1 · Map	Role roster · existing systems	Five-element deep-dive — capture each step's input / output / owner / time cost / pain points	Enterprise profile
2 · Triage	Enterprise profile	Three-question triage — which steps fit AI: 🔄 automate · ⚡ augment · 👤 leave alone, prioritized by ROI	Node plan + annual savings
3 · Deliver	Node plan	Three-layer deliverables — documents + Skills + runtime, so AI nodes actually run	Ontology + workflow.yml + skills/

Full methodology (four phases, twelve steps) in FDE/GUIDE.md — a half-day read, enough to run FDE independently afterwards.

💾 Don't rush off after deployment: each node's workflow is "burned" onto a USB drive through the DeepSeek Harness execution backend — the drive becomes one node, one key: plug it into any machine and it runs there (unplug, zero residue). The 9 open-source atomic plugins are already mounted into DSH (1 aggregate plugin also available) — burn and go.

FDE Skill System

The seam of the two stages — on-entry judgment is frozen into Skills loaded alongside the node, and after departure the constraint layer executes against them. Deploying an AI node is only the first step: the chapters above cover how to map the flow and where to put it; this one covers how to keep it behaving every single time. The FDE Skill System answers that:

• 📜 SKILL.md — the single main entry, loaded by your AI tool: routes to the corresponding sub-Skill by phase, with role norms auto-injected by task type (mapping / audit / orchestration)
• 🧩 Phase sub-Skills — a five-step closed loop of entry → deep-dive → quantify → deliver → depart (01-entry → 05-exit); what to do and what to deliver at each step is defined up front
• 🔒 Harness constraint skeleton — entry-gate / fde-template / engage / loop-check / task-closure… every step from entry to departure has its matching constraint template
• 📚 Knowledge asset pipeline (Distill) — the structured pipeline of think.md reflection + knowledge maintenance is in place; measured data on capture effectiveness under sustained use is still accumulating (see LIMITATIONS · core-effect measurements)

What gets deployed is not a bare Agent, but an Agent with a constraint skeleton — constraints are advisory, auditing is mandatory: the Agent may ignore the constraints, but every change gets audited without exception.

Constraint Layer (Harness)

The second half of the two stages. The judgment generated on entry (merge_criteria / approver / trigger) is retained and enforced here — this is the half that keeps FDE judgment alive after the engineer leaves. The constraint layer is sofagent's behavioral foundation, with five capabilities:

• Injection — inject enterprise constraints at Agent startup through the four-layer loading chain; constraints are advisory
• Audit — 24 git-diff hard-evidence rules (quick runs 17 by default, 7 extensions enabled via config) + AgentShield five-face static config scanning; auditing is mandatory — every change gets audited, violations blocked on the spot
• Rollback — auto-archived snapshot after every audit, one-click restore to any snapshot
• Distillation — audit trails, think.md reflections, and industry cases distilled into reusable knowledge assets (knowledge/ base + SKILL files; knowledge capture is currently a format-only pipeline; content filling advances as models get wired in — see LIMITATIONS)
• Evolution — think.md reflection + Dream Cycle + evolve, consuming distilled knowledge assets to get stronger automatically (knowledge capture is currently a format-only pipeline; content filling advances as models get wired in — see LIMITATIONS)

Installation

⚠️ Enterprise users read first LIMITATIONS §3 — config.yml is non-fail-closed by default (rules can be bypassed by Agent tampering), and write-side multi-tenant isolation is not yet landed (v0 delivered query-side isolation: orgId filtering + the data// path foundation — see LIMITATIONS). For strict-compliance scenarios use CI fallback + file-permission lock (chmod 444 .sofagent/config.yml); do not put the single-machine default config directly into production.

30 seconds, zero setup — run an audit in any git repo:

npx -y -p @sofagent/audit sofagent-audit

💡 quick runs the 17 default rules (A3 task-scope / A9 commit-msg injection detection active — quick mode auto-reads the latest commit message; when no message is available, A9 is handled by the engine as no-input and marked skipped). The full 24 rules + hook auto-audit require --init — see LIMITATIONS §3.

Here's what it looks like when a known-format secret leak is blocked (real output; A2 detects AWS AKIA/Secret, OpenAI sk-, GitHub ghp_, Google AIza, Slack xox-, JWT, PEM private keys and other known formats — generic secret shapes are intentionally out of scope, a conservative design against false positives, see LIMITATIONS §3 A2): — the screenshot above (first screen) shows exactly this scenario, not repeated here.

Full install (Node.js ≥ 18, download and review before running) — installed on the enterprise devices running the AI nodes:

curl -fsSL https://raw.githubusercontent.com/KongFangXun/sofagent/refs/tags/v1.4.8/bootstrap.sh -o bootstrap.sh
less bootstrap.sh          # review the script first, confirm it's safe
bash bootstrap.sh && rm bootstrap.sh

🔒 Supply-chain trust: tag pinning + sha256 verification + fail-closed + self-anchored hash re-verification (see SECURITY.md, remote-install section); ⚠️ audit logs are plaintext on disk by default — enterprise deployments should enable encryption-at-rest.

sofagent-audit --init      # install the git hook — every commit is audited from now on
sofagent-audit --doctor    # verify the environment (optional)

💡 The install scripts mainly write to ~/.sofagent/ (data directory) + ~/.local/bin (CLI entry); when OpenClaw is detected they additionally write into its integration directory; if npm permissions are insufficient, the CLI entry falls back to /usr/local/bin. No other system files are touched. --init installs the three-layer git hook defense (pre-commit blocks .sofagent/ from entering the repo + commit-msg rule audit + post-commit reconciliation). --no-verify can skip the commit-msg audit — it guards against honest Agents' carelessness, not malicious bypass; skipped commits are reconciled afterwards by the post-commit hook (flagged "suspected bypass") but not blocked. Personal fallbacks: CI-side sofagent-audit --diff, periodic --doctor, and reviewing the audit records. See LIMITATIONS.

📌 install.sh is the enterprise device installer — install it on the enterprise devices running the AI nodes (constraint-layer engine + daemon inspection + single-machine dashboard); FDEs do not need to run it on their own machines — the FDE's tools are the FDE Skill (methodology). See deployment architecture.

📌 How bootstrap.sh and install.sh relate: bootstrap.sh is a one-line download wrapper around install.sh — curl bootstrap.sh | bash is equivalent to "download install.sh + run install.sh". Both scripts install exactly the same thing; bootstrap just saves you the manual clone/download step.

To uninstall: bash engine/scripts/uninstall.sh — removes the Skill/constitution files, hook registrations and the three git hooks (pre-commit / commit-msg / post-commit), while keeping your ~/.sofagent/ data. More install options (clone install / full npx install / minimal install / enterprise deployment) in HANDBOOK. Enterprise users who just want the FDE methodology for mapping business workflows, see FDE/README.md (zero dependencies, no Node.js needed; for the 15-minute shortest path see its "15-minute shortest path" section).

What do I install → which channel — two "install everything" entry points; pick the one matching your environment, and you never need both (they do not depend on each other, and neither is a prerequisite for the other):

What I want	Which channel	What I get
Everything, via the npm ecosystem	npm i -g sofagent (npm bare-name umbrella package engine/umbrella)	@sofagent/audit + @sofagent/mcp + @sofagent/orchestrator + @sofagent/daemon
Everything, via DSH host mounting	mount one cordis-plugin-sofagent entry in the host profile's bundles	all atomic plugins declared by that aggregator (one entry aggregates them)

Usage

📊 The Dashboard has three entries, each in its place:

Entry	Command	Form	Who it's for
Terminal	sofagent-dashboard --full	Terminal ASCII three-pane (zero frontend dependencies)	Developers / FDE quick check
Web	sofagent web (available in the install.sh-installed state) · repo-mode node tools/dashboard/serve-dashboard.mjs	Browser visualization (localhost:3780)	Boss / IT visual review
macOS double-click	Double-click start-dashboard.command	macOS shortcut to the Web version (macOS double-click entry only)	macOS users

👁️ Agent's view: with hooks installed, every commit triggers an audit — PASS prints a short echo then passes (auto-snapshot), violations are printed directly into the terminal output and pushed via Webhook / IM per config; there is no separate GUI on the Agent side (see PHILOSOPHY §2).

Entry	What it does	Where installed	Time needed
npx -y -p @sofagent/audit sofagent-audit	Zero-setup audit of the last commit, results in seconds (first npx ~30s)	Any git repo (temporary)	30 sec
--ruleset rule marketplace	Load rulesets like security, or custom JSON rules	Same as above	1 min
GitHub Action	Auto-audit every PR, violations annotated on the diff lines	CI/CD	Set up once
install.sh full suite	inject · audit · rollback · distill · evolve + daemon inspection + dashboard — the Agent's complete constraint layer	Enterprise device (server/computer running the AI nodes)	FDE residency

Install-granularity comparison (same engine, three install styles — pick by scenario):

Style	Command	Lifecycle	Best for
npx temporary	npx -y -p @sofagent/audit sofagent-audit	use-and-go, downloaded each time	quick audit of any repo, one-off checks outside CI
npm in-project	npm install @sofagent/audit (project devDependency)	installed with project, version locked in package-lock	team projects with fixed deps, reproducible audits
npm global	npm install -g @sofagent/audit	install once, use everywhere	daily audit across repos, daemon residency

Rule marketplace — community rulesets are published as sofagent-ruleset-* npm packages and loaded manually via --ruleset-path (which also accepts your own JSON rules):

npx -y -p @sofagent/audit sofagent-audit --list-rulesets      # see available rulesets
npx -y -p @sofagent/audit sofagent-audit --ruleset security   # load the security ruleset

FDE on-site deployment — pick either of two paths:

• Methodology path (zero dependencies): read FDE/GUIDE.md and map business workflows manually following the handbook — Excel + your own brain is enough
• Tooling path (Node.js ≥ 18): after the FDE installs the constraint layer on the enterprise device via install.sh, tell your own AI tool "run an FDE diagnosis for me" — the Agent guides you from entry onward

FAQ

• Is it production-ready? Currently single-machine, single-user (tenancy on the ROADMAP; encryption-at-rest and boundaries in LIMITATIONS — read SECURITY before enterprise deployment).
• Does it collect my data? Fully local by default. Optional federation queries leave your machine only when you configure them yourself (see SECURITY).

Ecosystem & Docs Index

🌏 Note: the linked docs (LIMITATIONS / ARCHITECTURE / PHILOSOPHY / WIKI / SECURITY …) are Chinese-first — English readers can rely on this README plus the EN summary at the top of WIKI; full doc translation is tracked in issue #8.

Featured in (community listings, incl. pending PRs):

Upstream & plugin entries:

• DeepSeek Harness (upstream repository): https://github.com/deepseek-ai/deepseek-harness
• Cordis runtime: https://github.com/cordiverse/cordis
• 10 cordis-plugin-sofagent* plugin sources (9 atomic + 1 aggregate): engine/dsh-plugins/

You want to know	Where
Global index (one entry to all docs, in Chinese)	WIKI — EN summary: one-liner & product story · core concepts · architecture overview · file map · current status · glossary · intent-based navigation
How to install, use, FAQ	HANDBOOK
Architecture (constraint layer · injection chain · evolution · 24 rules)	ARCHITECTURE
API overview (seven interface surfaces + 95 MCP tools)	API
Design philosophy	PHILOSOPHY
Industry validation & ecosystem positioning (differences from existing tools)	VALIDATION
Version roadmap	ROADMAP
What each version delivered	CHANGELOG
FDE diagnostic methodology (four phases, twelve steps)	FDE/GUIDE.md
Security statement · known limitations	SECURITY · LIMITATIONS
Contribution guide	CONTRIBUTING

🧪 Engineering credibility: 4429 tests / 13 module packages + 14 plugins (10 DSH + 4 OpenClaw) (4429 = 13-main-package scope, per the check-test-count gate; authoritative package-count breakdown in WIKI) · 24 audit rules · fresh-eyes independent review continuously running (test counts are determined by tools/check/test-count.sh; environmental notes are documented in docs/guides/review-system.md. Performance figures are single-machine reference values; cross-tool benchmarking is scheduled for v1.4.x together with Benchmark integration).

---