Constraints

Software Delivery Pack constraints

These constraints are defined by the Software Delivery Pack. They govern software delivery workflows specifically. The kernel provides the underlying enforcement mechanisms (scope intersection, policy engine, evidence recording) that enforce these constraints for every tool call dispatched through it. Other packs define their own domain-specific constraints.

The Constraints Capsule contains eleven non-negotiable rules that every agent and developer using the Software Delivery Pack must follow. These rules are designed to prevent common mistakes and ensure consistent, safe workflow execution.

Why Constraints?

LumenFlow is designed to give AI agents and developers autonomy. But autonomy without guardrails leads to chaos. Constraints provide:

• Safety - Prevent irreversible mistakes
• Consistency - Same workflow everywhere
• Auditability - Know what happened and why
• Recoverability - When things go wrong, fix them

Tip

Think of constraints as “rules that protect you from yourself” - they prevent the mistakes that seem obvious in hindsight.

The 11 Non-Negotiable Constraints

1. Worktree Discipline and Git Safety

Rule

Work only in worktrees, treat main as read-only, never run destructive git commands on main.

Enforcement:

• After pnpm wu:claim, immediately cd into the worktree it created
• Hooks block WU commits from main checkout
• Forbidden commands on main: git reset --hard, git stash, git clean -fd, git push --force

Why: Worktree isolation prevents cross-contamination between parallel WUs and protects the main branch from accidental damage.

Example:

# WRONG: Working in main
pnpm wu:claim --id <wu-id> --lane Core
vim app/feature.ts  # Still in main!

# RIGHT: Working in worktree
pnpm wu:claim --id <wu-id> --lane Core
cd <worktree-path>  # Immediately move here
vim app/feature.ts  # Now you're isolated

2. WUs Are Specs, Not Code

Rule

Respect code_paths boundaries, no feature creep, no code blocks in WU YAML files.

Enforcement:

• Only modify files listed in code_paths
• WU YAML contains acceptance criteria, not implementation code
• Scope discipline: implement only what the spec requires

Why: WUs define WHAT to build, not HOW. Implementation decisions belong in code, not specs. This keeps specs clean and prevents scope creep.

Example:

# WRONG: Code in WU YAML
acceptance:
  - |
    function validate(email) {
      return email.includes('@');
    }

# RIGHT: Behavior specification
acceptance:
  - Email field validates format on blur
  - Invalid emails show "Please enter a valid email"
  - Validation uses standard email regex pattern

3. Docs-Only vs Code WUs

Rule

Documentation WUs use --docs-only gates, code WUs run full gates.

Enforcement:

• type: documentation in WU YAML triggers docs-only mode
• pnpm gates --docs-only skips lint/typecheck/tests
• Path validation prevents code files in docs WUs

Why: Documentation changes shouldn’t require the full test suite. Code changes must pass all gates. Mixing them causes friction.

Example:

# Documentation WU
pnpm gates --docs-only

# Code WU
pnpm gates

# WU YAML for docs
type: documentation
code_paths:
  - docs/**
  - '*.md'

4. LLM-First, Zero-Fallback Inference

Rule

Use LLMs for semantic tasks, fall back to safe defaults (never regex/keywords).

Enforcement:

• Prompt-based classification for ambiguous inputs
• Structured output parsing for LLM responses
• No brittle keyword matching for semantic decisions

Why: Regex and keyword matching are brittle and fail on edge cases. LLMs handle natural language variation better. When the LLM fails, use safe defaults - never fall back to keyword hacks.

Example:

// WRONG: Keyword matching
function classifyIntent(input: string) {
  if (input.includes('cancel')) return 'cancellation';
  if (input.includes('refund')) return 'refund';
  return 'unknown';
}

// RIGHT: LLM-first with safe default
async function classifyIntent(input: string) {
  const result = await llm.classify(input, {
    schema: IntentSchema,
    fallback: 'needs_human_review', // Safe default, not keyword hack
  });
  return result;
}

5. Gates and Named Gate Skips

Rule

Complete via pnpm wu:prep (gates) then pnpm wu:done; only explicitly named skippable gates can be skipped, with --reason and --fix-wu.

Enforcement:

• pnpm wu:prep runs gates in the worktree
• The legacy --skip-gates binary is removed and always rejected
• Named --skip-gate <name> requests require both --reason and --fix-wu
• Skip events are written to the skip-gates audit log
• format:check, lint, typecheck, co-change, spec:linter, claim-validation, unread-directed-signal, invariants, and safety-critical-test are immutable; configuration rejects skippable: true for these gates
• Trusted applicability_paths can narrow only format:check, lint, typecheck, co-change, spec:linter, and safety-critical-test. claim-validation and invariants remain always-on; unread-signal exceptions use the audited --allow-unread-signals --reason flow after signal triage
• Missing format:check, lint, typecheck, or spec:linter scripts block in default mode

Why: Gates ensure quality. Skipping requires accountability and a plan to fix the underlying issue. Without this, quality degrades over time.

Example:

# WRONG: Skipping a gate without naming it or providing evidence
pnpm wu:done --id <wu-id> --skip-gate unknown

# RIGHT: Skipping one explicitly named skippable gate with full accountability
pnpm wu:done --id <wu-id> \
  --skip-gate lane-health \
  --reason "Pre-existing test failure in legacy module" \
  --fix-wu <wu-id>

Only skip when ALL are true:

1. Test failures existed before your WU
2. Your WU work is genuinely complete
3. A separate WU exists to fix the failures
4. Failures are unrelated to your code

6. Safety and Governance

Rule

Respect privacy rules, approved sources, security policies; when uncertain, choose the safer path.

Enforcement:

• No hardcoded secrets in code you write; code review remains required
• Installed pre-push hooks support opt-in local Gitleaks committed-content scanning; scanning is disabled by default
• RLS policies on sensitive data
• Redaction before sending to LLMs
• Stop-and-ask for auth/PII/spend changes

Enable scanning through the validated workspace configuration:

software_delivery:
  git:
    secret_scanning:
      enabled: true
      timeout_ms: 30000

Supply a native Gitleaks executable on PATH separately (version 8.19 or newer, with the git command). LumenFlow does not download it or enable the policy automatically. Install the updated managed hook through the normal init, enable or upgrade workflow. A source change alone does not update an existing consumer installation.

When enabled, the hook scans historical file diffs for every published non-deletion ref before the tmp/* lifecycle exemption. Updates exclude only that ref’s advertised remote commit; new branches and tags scan their complete reachable local history, including root commits and merge changes. This can report an older credential even when the current tree is clean. Alternate remotes and the configured integration target do not narrow this scope. Annotated tags must resolve to a commit. Shallow history, unavailable objects, malformed input, findings, missing executables, scanner errors, timeout and output overflow refuse the push with safe diagnostics. Fix the published history and rotate exposed credentials; use your scanner’s own local tools to investigate a refusal.

The total scan deadline defaults to 30 seconds and accepts 1–300000 milliseconds, shared by Git validation and all refs. Scope is bounded to 128 ref updates and 1 MiB of stdin; each subprocess has 64 KiB of combined captured output, followed by at most five seconds of forced cleanup. Scanner output is discarded, including on errors. No report or credential content is written by LumenFlow. The scanner runs locally using its normal rules/configuration; existing Gitleaks configuration or allowlists can affect detection. LumenFlow does not add or change those rules or ignores. Its Gitleaks git command receives the repository root as a positional operand.

The Linux fixture has been exercised with real Gitleaks 8.30.1 through the generated pre-push hook and built checker under a fixture-only licence: a clean push to a local bare remote passed, while a synthetic finding was refused and left the remote ref unchanged. This is a local compatibility check, not production package closure, a customer licence grant, public release or deployment validation, macOS or Windows certification, or a guarantee that every credential will be detected. The release archive SHA-256 matched its downloaded publisher checksum manifest before extraction; the executable SHA-256 is a local fingerprint only. No signed-certificate provenance is claimed.

Historical diff scanning does not scan commit or tag messages, every Git object, binary/archive or submodule repository content, uncommitted files, or files omitted by the engine’s rules. It cannot guarantee detection of every credential. Bypassed or modified hooks and other publication paths provide no local scan guarantee. Git operations disable lazy object fetching and replacement refs for the scan; use Git 2.45 or newer for the local-only missing-object guard. A dependency-free temporary worktree uses the primary checkout’s existing installed CLI while reading both policy and history from the original temporary root.

Why: Safety first. Some mistakes are irreversible. When in doubt, stop and ask rather than proceed and regret.

Stop and ask when:

Trigger	Action
Same error 3 times	Stop, ask
Auth/permission changes	Stop, ask
PII/secrets involved	Stop, ask
Cloud spend decisions	Stop, ask
Policy changes needed	Stop, ask

7. Test Ratchet Pattern

Rule

NEW test failures block gates; pre-existing failures (already in the baseline) warn but do not block.

Enforcement:

• Gates compare current test results against the committed test baseline file
• pnpm test:baseline:init creates the baseline from the current failing test set
• pnpm test:baseline:update refreshes the baseline after an intentional ratchet change
• NEW failures (not in the baseline) block the WU; pre-existing failures warn and let it proceed

Why: Agents should not be blocked by unrelated, pre-existing failures. The ratchet ensures quality only improves over time — failures can be removed from the baseline, but never silently added without justification.

8. Lane-Fit Reasoning

Rule

Evaluate lane fitness during WU and initiative scoping, and propose a lane change when a WU’s scope no longer fits its lane’s boundaries.

Enforcement:

• Before claiming a WU, verify its code_paths align with the claimed lane’s code_paths in workspace.yaml
• Propose a lane change or split the WU when scope expands beyond the lane’s boundaries
• Use pnpm lane:suggest --paths "..." to get lane recommendations for ambiguous scoping
• If the ideal lane is occupied (WIP limit reached), use a nearby lane or ask the user — never touch, release, or complete another agent’s WU to free it

Why: Lane boundaries define ownership, WIP limits, and parallel execution safety. Misassigned WUs undermine these guarantees and create coordination confusion.

9. YAML Files Must Be Modified via CLI Tooling Only

Rule

Never use raw Write/Edit tools to modify workspace.yaml or WU YAML specification files — always use the dedicated CLI commands.

Enforcement:

• workspace.yaml → pnpm config:set (write) / pnpm config:get (read)
• WU YAML specs → pnpm wu:edit (modify) / pnpm wu:create (create)
• Reading YAML files with a Read tool is fine for inspection; writing or editing them directly is not

Why: CLI tooling provides schema validation, atomic commits, an audit trail, and automatic type coercion. Raw edits bypass all of these safeguards and can produce invalid configuration that breaks downstream commands.

10. Stop and Escalate After 3 Failures

Rule

If the same operation fails three times, stop retrying and escalate to the user with a summary of what failed and why.

Enforcement:

• Applies to CLI commands (wu:create, wu:claim, wu:done, gates, etc.), git operations, build/install steps, and any repeated validation failure
• Retrying the same command with slightly different flags after each error still counts as one operation failing repeatedly
• Escalate with: what was attempted, the errors seen each time, a root-cause guess, and options (or “I don’t know”)

Why: Retry loops waste user time and context window. Three failures usually means the agent has the wrong mental model of the problem — escalating early lets the user correct course before additional mess accumulates.

11. Client-Facing Content Accuracy

Rule

When writing or updating content shown to external stakeholders, do not treat internal docs as ground truth for factual claims — flag specific claims to the user for verification.

Enforcement:

• Claims requiring user verification: headcount/org structure, revenue/financial figures, product status (shipped vs planned), customer-specific details, and competitive claims
• Before committing client-facing copy with specific factual claims, present a summary to the user for confirmation
• If internal docs contradict each other, flag the contradiction rather than picking one
• Never cite an external source to “verify” an internal claim without telling the user — the external source may also be stale

Why: Internal docs go stale. The user always knows what’s current; an agent confidently restating a stale internal fact in client-facing material undermines trust in both the material and the agent.

Mini Audit Checklist

Before running wu:done, verify:

• Working in worktree (not main)
• Only modified files in code_paths
• Gates pass (pnpm gates or pnpm gates --docs-only)
• No forbidden git commands used
• No secrets committed
• Acceptance criteria satisfied

Forbidden Commands Reference

These commands are blocked on main checkout:

# Data destruction
git reset --hard
git clean -fd

# Hidden work
git stash

# History rewrite
git push --force
git push -f
git rebase -i main

# Bypass safety
--no-verify

Caution

Hooks enforce these restrictions. If you find yourself wanting to bypass them, stop and think about why. There’s usually a better way.

Allowed in worktrees: Most commands are safe in isolated worktrees on lane branches. The restrictions apply specifically to the main checkout.

Force Bypass Policy

Caution

AI agents MUST NOT use force bypass mechanisms without explicit user approval.

Why: Force bypass mechanisms circumvent all git hook protections. While legitimate for emergency human interventions, agents using them autonomously undermines the entire workflow enforcement model.

Agent Escalation Path:

1. Detect need: Agent encounters hook blocking operation
2. Stop and ask: Present situation to user with context
3. Get approval: User must explicitly approve bypass with reason
4. Execute with audit: Document the reason
5. Document: Note the bypass in commit message or WU notes

Legitimate bypass scenarios:

• Fixing YAML parsing bugs in WU specs
• Emergency production hotfixes (with user present)
• Recovering from corrupted workflow state
• Bootstrap operations when CLI not yet built

Never bypass for:

• Skipping failing tests
• Avoiding code review
• Working around gate failures
• Convenience or speed

Escalation Triggers

Stop and ask a human when:

• Same error repeats 3 times
• Auth or permissions changes required
• PII/safety issues discovered
• Cloud spend or secrets involved
• Policy changes needed

Context Limits

When approaching context limits (high token usage, 50+ tool calls), spawn a fresh agent instead of continuing after compaction.

Why: Context compaction causes agents to lose critical rules. Starting fresh ensures constraints remain in working memory.

Next Steps

• Agent Onboarding - Get productive quickly
• Gates - Quality enforcement
• Troubleshooting - When things go wrong