Agent Safety Architecture

LumenFlow uses host-neutral, layered protection for agent work. Lifecycle commands, gates, repository hooks, and recorded evidence remain authoritative.

Universal Contract

Every agent consumes the same managed surfaces:

• LUMENFLOW.md, followed by LUMENFLOW.local.md when present
• .lumenflow/constraints.md, .lumenflow/rules/, and .lumenflow/skills/
• workspace.yaml
• the LumenFlow CLI and pack runtime
• WU briefs, memory signals, checkpoints, stamps, and audit records

LumenFlow does not generate, inspect, or manage host-specific instruction or skill directories. A project-owned discovery file may point to the contract, but is not part of LumenFlow’s compatibility promise.

Fleet Lifecycle Authority

Cleanup, recovery, completion, and orchestration derive authority from WU id, lane lock, session/lease evidence, lane branch, worktree path, done stamp, and audit records. Provider names, models, hosted runners, and UIs are execution metadata only.

Active or recently active WU leases block destructive cleanup. Restore a missing worktree with an intact lane branch through the lifecycle command:

pnpm wu:recover --id WU-042 --action restore

wu:prune --execute records recoverable tracked removals under .lumenflow/quarantine/worktrees/cleanup.jsonl. Raw git worktree pruning is an implementation detail, not lifecycle authority.

Bootstrap And Prerequisite Safety

Agent-facing root scripts should invoke commands through node tools/cli-entry.mjs <entry>. The wrapper keeps clean WU worktrees from failing command discovery before local CLI build artifacts exist.

Use the script guard after alias changes:

pnpm verify:script-help
pnpm verify:script-help --run-probes

Use the prerequisite reporter before local database or model workflows:

pnpm lumenflow:setup-prereqs --json

The report omits local service keys and token-shaped values. Do not paste raw service startup, environment, or provider-token output into prompts, issues, or WU notes.

Delivery telemetry safe-text classifier

Lifecycle telemetry (wu_telemetry.v1) redacts free-text fields before emission. The classifier rejects two shapes: named credential keywords (api_key, token, secret, password, authorization) immediately followed by : or = and a value, and SCREAMING_SNAKE_CASE env-style assignments with two or more underscore-joined uppercase segments (for example DB_PASSWORD=...). Ordinary capitalized work-item prefixes such as BUG:, FIXME:, or API: are not credential shapes and are admitted. Every rejection carries a reasonCode and never echoes the matched value, so the diagnostic is safe to log or count.

Protection Layers

1. Universal contract — LUMENFLOW.md, constraints, rules, and canonical skills define one workflow for every agent. wu:brief renders the same contract regardless of execution metadata.
2. Governed file operations — worktree guards and the vendor-neutral file:write / file:edit commands reject paths outside the declared checkout.
3. Pre-commit enforcement — .husky/pre-commit.mjs checks formatting, commit identity, and worktree discipline.
4. Pre-push enforcement — .husky/pre-push.mjs enforces branch and lifecycle policy before a push.
5. Lifecycle commands — wu:create, wu:claim, wu:prep, wu:done, wu:cleanup, and recovery commands own state transitions.
6. Quality gates — configured gates block unsafe or invalid completion and write structured evidence.
7. Ownership guards — state-mutating commands validate the target WU’s session owner. Audited overrides require --override-owner --reason "...".
8. Memory and signals — handoffs, discoveries, directed signals, and checkpoints remain shared across hosts.
9. Audit and recovery evidence — events, stamps, gate records, override records, and quarantine manifests make lifecycle decisions inspectable and recoverable.

Authenticated web workspace operations

Workspace create, connect, inventory, author, and install routes authenticate before consuming a body or accessing the filesystem. Actual request bytes are bounded while streaming. The configured host root provides path containment only; for an existing target, the top-level workspace.yaml.id must exactly match the authenticated caller workspace identity.

Canonical checks reject symlink components before pack removal or writes. Pack installation uses a host-pinned CLI entrypoint rather than repository-selected npx resolution. A mismatch or unsafe path fails closed before pack generation, registry lookup, filesystem mutation, subprocess execution, or any other body-driven side effect.

Hosts exposing local workspace pack installation set LUMENFLOW_WEB_CLI_ENTRYPOINT to an absolute, host-owned pack-install.js path. Missing, relative, symlink-only, or non-file values fail closed; the route never falls back to PATH, npx, or workspace dependencies.

Project-owned native hooks may surface violations earlier. They do not change LumenFlow authority and are not generated or maintained by LumenFlow.

Coverage Matrix

Surface	Authority	Blocks violations
Universal contract	LumenFlow	Policy/injection
File-operation guards	LumenFlow	Yes
Git hooks	Repository	Yes
WU lifecycle commands	LumenFlow	Yes
Quality gates	LumenFlow	Yes
Session ownership	LumenFlow	Yes
Memory and audit evidence	LumenFlow	Completion checks
Native pre-write feedback	Repository	If configured

The optional final row improves feedback latency only. It does not grant, remove, or replace lifecycle authority.

Governed Local Main Sync

Raw git pull from the main checkout mutates local main without LumenFlow guards. For a clean, fast-forward-only update, use:

pnpm git:sync-main

The command fetches origin/main, requires a clean primary checkout on main, rejects WU worktrees and in-progress merge/rebase state, verifies ancestry, and then fast-forwards. Divergent or dirty checkouts fail with remediation guidance.

YAML Editing Policy

Danger

Raw YAML edits bypass schema validation, atomic lifecycle updates, and audit evidence. Always use CLI tooling instead.

Use governed commands for configuration and WU metadata:

# Read and update workspace configuration
pnpm config:get --key software_delivery.methodology.testing
pnpm config:set --key software_delivery.methodology.testing --value test-after

# Edit or create WU specifications
pnpm wu:edit --id WU-XXX --description "Updated description"
pnpm wu:create \
  --lane "Framework: Core" \
  --title "Add feature" \
  --type feature \
  --exposure backend-only \
  --description "Add the bounded capability described by the linked plan" \
  --acceptance "The capability passes its unit and smoke verification" \
  --notes "Preserve the existing public contract" \
  --code-paths "src/feature.ts" \
  --test-paths-unit "src/__tests__/feature.test.ts" \
  --test-paths-manual "Run the feature smoke scenario and verify the expected result" \
  --plan

These commands provide schema validation, atomic updates, type coercion, and audit evidence.

Universal Setup

One command produces the universal scaffold; there is no client or vendor flag:

pnpm lumenflow:init

Connecting the public contract to any host-native discovery or hook mechanism is a repository-owner task. See Connect an AI Coding Assistant.

Lifecycle Enforcement Integrity

Repository-owned pre-commit, pre-push, and CI delegators protect the lifecycle manifest, receipts, journals, hooks, and managed CI block. lumenflow:doctor reports enforced, non-compliant-disabled, missing, stale, tampered, or unavailable; only enforced is certifying. Run pnpm lumenflow:enable to atomically repair every remediable state; restore repository storage access before retrying unavailable. Lifecycle front doors independently reject no-verify, raw-git, forged/replayed-receipt, and synthetic-brief bypasses.

A hostile unsandboxed process with the same OS-user authority can replace local code, hooks, or receipts. Preventing that requires an OS sandbox or protected remote/server authority. Disabled and uninstalled consumers cannot claim lifecycle certification.

Known Gaps

Gap	Risk	Mitigation
Native pre-write feedback	Medium	Git hooks, worktree guards, gates, and lifecycle commands
Emergency overrides	Medium	Mandatory reason, audit records, and operational monitoring
Server-side branch policy	Medium	Require repository status checks and restrict direct updates
Passive audit logs	Low	Monitor audit events when real-time escalation is required

References

• Constraints Capsule
• Configuration Commands
• Configuration Reference