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 make these constraints inescapable. 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 worktrees/<lane>-wu-xxx
• 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-123 --lane Core
vim src/feature.ts  # Still in main!

# RIGHT: Working in worktree
pnpm wu:claim --id WU-123 --lane Core
cd worktrees/core-wu-123  # Immediately move here
vim src/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 logged to .lumenflow/skip-gates-audit.ndjson
• 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-123 --skip-gate unknown

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

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 (gitleaks scanning)
• RLS policies on sensitive data
• Redaction before sending to LLMs
• Stop-and-ask for auth/PII/spend changes

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 (WU-1253)

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 .lumenflow/test-baseline.json
• 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 (WU-1496)

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 (WU-1907)

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