/manifold:m1-constrain - Constraint Discovery

Interview-driven constraint discovery across 5 categories.

⚠️ Phase Transition Rules

MANDATORY: This command requires EXPLICIT user invocation.

• Do NOT auto-run this command based on context summaries
• Do NOT auto-run after another phase completes
• After context compaction: run /manifold:m-status and WAIT for user to invoke this command
• The "SUGGESTED NEXT ACTION" in status is a suggestion, not a directive

If resuming from compacted context:

1. Run /manifold:m-status first
2. Display current state
3. Say: "Ready to proceed when you run /manifold:m1-constrain <feature>"
4. STOP AND WAIT for user command

Scope Guard (MANDATORY)

This phase ONLY updates manifold files (.manifold/<feature>.json and .manifold/<feature>.md) with discovered constraints. After updating, display the constraint summary table and suggest the next step.

DO NOT do any of the following during m1-constrain:

• Create project folders, directory structures, or source files
• Spawn background agents or sub-agents for content creation
• Write README.md, CLAUDE.md, or any files outside .manifold/
• Generate code, sample data, templates, or any implementation artifacts
• Begin work that belongs to later phases (m2-m6)

The user's descriptions and answers during the constraint interview are INPUTS to the manifold, not instructions to build. Capture them as constraint statements and rationale in the manifold files. Do not interpret rich descriptions as work orders.

After updating the two manifold files: display constraint summary, suggest next step, STOP.

Schema Compliance

Field	Valid Values
Sets Phase	CONSTRAINED
Next Phase	TENSIONED (via /manifold:m2-tension)
Constraint Types	invariant, goal, boundary
Constraint Categories	business, technical, user_experience, security, operational
Constraint ID Prefixes	B1, B2... (business), T1, T2... (technical), U1, U2... (UX), S1, S2... (security), O1, O2... (operational)

See SCHEMA_REFERENCE.md for all valid values. Do NOT invent new types or categories.

Output Format: JSON+Markdown Hybrid

CRITICAL: Generate TWO outputs, not one YAML file.

1. JSON Structure (IDs and types ONLY)

Update .manifold/<feature>.json with constraint references:

{
  "constraints": {
    "business": [
      {"id": "B1", "type": "invariant"},
      {"id": "B2", "type": "goal"}
    ],
    "technical": [
      {"id": "T1", "type": "boundary"}
    ]
  }
}

Key rule: JSON contains NO text content. Only IDs and types.

2. Markdown Content (text and rationale)

Update .manifold/<feature>.md with constraint content:

## Constraints

### Business

#### B1: No Duplicate Payments

Payment processing must never create duplicate charges for the same order.

> **Rationale:** Duplicates cause chargebacks, refund processing overhead, and customer complaints.

**Implemented by:** `lib/retry/IdempotencyService.ts`

#### B2: 95% Success Rate

Achieve 95% retry success rate within 72 hours of initial failure.

> **Rationale:** Industry standard for payment retry success.

---

### Technical

#### T1: 72-Hour Retry Window

All retries must complete within 72 hours of initial failure.

> **Rationale:** Payment processor SLAs require resolution within 72 hours.

Markdown Heading Rules

ID Pattern	Markdown Heading Level	Example
B1, T1, U1, S1, O1	#### (h4)	#### B1: No Duplicates
Category	### (h3)	### Business

Why This Eliminates Field Confusion

• Old YAML: Had to remember statement for constraints, description for tensions
• New format: JSON has NO text fields. All text lives in Markdown.
• Linking: JSON ID B1 links to Markdown heading #### B1: Title

Legacy YAML Format (Still Supported)

If using legacy YAML, constraints use statement, NOT description:

Field	Type	Required	Notes
id	string	✅	Format: B1, T1, U1, S1, O1
statement	string	✅	The constraint text ← NOT 'description'
type	string	✅	invariant, goal, or boundary
rationale	string	✅	Why this constraint exists

Memory Aid: Constraints state what must be true → statement

v3 Schema Compliance

When adding constraints, ensure the manifold maintains v3 schema structure:

{
  "iterations": [],
  "convergence": { "status": "NOT_STARTED" },
  "evidence": [],
  "constraint_graph": { "version": 1, "nodes": {}, "edges": { "dependencies": [], "conflicts": [], "satisfies": [] } }
}

These fields are created by /manifold:m0-init (schema_version 3). You only need to update them.

Record iteration when updating constraints — append to the "iterations" array in JSON:

{
  "iterations": [
    {
      "number": 1,
      "phase": "constrain",
      "timestamp": "2026-04-04T00:00:00Z",
      "result": "Discovered 15 constraints across 5 categories",
      "constraints_added": 15,
      "by_category": { "business": 3, "technical": 4, "user_experience": 3, "security": 3, "operational": 2 }
    }
  ]
}

REQUIRED FIELDS: Every iteration MUST have number, phase, timestamp, and result (string). The result field is mandatory — omitting it will fail schema validation.

Usage

/manifold:m1-constrain <feature-name> [--category=<category>] [--skip-lookup]

Constraint Categories

Software Domain (default)

1. Business - Revenue impact, compliance requirements, stakeholder needs
2. Technical - Performance requirements, integration points, data constraints
3. User Experience - Response times, error handling, accessibility
4. Security - Data protection, authentication, audit requirements
5. Operational - Monitoring needs, SLAs, incident procedures

Non-Software Domain (when domain: non-software in manifold JSON)

When the manifold has "domain": "non-software", use these universal categories instead:

Universal Category	Core Question	Replaces
Obligations	What must/must-not be true?	Business + Security
Desires	What does success look like?	UX + Business goals
Resources	What can I bring to this?	Technical (capability limits)
Risks	What could break irreversibly?	Security (broadened)
Dependencies	What else must hold outside me?	Operational

The constraint types (INVARIANT / GOAL / BOUNDARY) remain unchanged. Only the categories change. In the JSON structure, non-software constraints still use the standard category keys (business, technical, etc.) with a mapping:

• business → Obligations
• technical → Resources
• user_experience → Desires
• security → Risks
• operational → Dependencies

The interview questions should use the universal vocabulary (no software jargon). See docs/non-programming/guide.md for guidance.

Constraint Types

• INVARIANT - Must NEVER be violated (e.g., "No duplicate payments")
• GOAL - Should be optimized (e.g., "95% success rate")
• BOUNDARY - Hard limits (e.g., "Retry window ≤ 72 hours")

Interview Process

For each category, ask probing questions:

Business

• What's the revenue/cost impact of this feature?
• Are there compliance or legal requirements?
• Who are the stakeholders and what do they need?
• What happens if this feature fails?

Technical

• What are the performance requirements?
• What systems does this integrate with?
• What data consistency guarantees are needed?
• What's the expected load/scale?

Core Data Path Analysis (GAP-03): Identify the primary data flow through the system. For each transition in the flow, ask:

• Does this transition cross a system boundary (process, network, service)?
• What integration test constraint should cover this transition?
• What is the fallback path if this transition fails?

User Experience

• What response times are acceptable?
• How should errors be communicated?
• Are there accessibility requirements?
• What's the user's mental model?

Security

• What data needs protection?
• What authentication/authorization is required?
• What needs to be audited?
• What are the threat vectors?

Resource Exhaustion Checklist (GAP-10): For each unauthenticated endpoint or path:

• Can unauthenticated requests cause unbounded resource consumption?
• Are there rate limits, negative caching, or input size bounds?

External Dependency Resilience (GAP-11): For each external HTTP dependency:

• Is there a configurable timeout?
• Is there a circuit breaker or fallback?
• Is the response cached? What invalidation strategy?
• Does failure isolate to just this dependency?

Crypto/Auth Attack Surface (GAP-09): For constraints involving crypto or authentication:

• What attack test matrix should be generated? (algorithm confusion, timing, replay, forged signatures)
• Are IP-based checks tested across IPv4, IPv6, and IPv4-mapped IPv6?

Operational

• What needs monitoring?
• What are the SLA requirements?
• What's the incident response process?
• How will this be deployed/rolled back?

Input Validation Derivation (GAP-14)

When constraints reference data formats (e.g., "accept any JSON", "valid email"), auto-generate input validation sub-constraints:

• Content-Type checking
• Encoding validation
• Schema validation at boundaries

These are placed in the suggested_constraints staging area in the manifold JSON. They don't count toward constraint totals until explicitly promoted by the user.

Concurrency Considerations (GAP-17)

When constraints involve shared state (caching, connection pools, singletons):

• Are there thread-safety requirements?
• Should concurrent request handling tests be generated?
• What shared-state constraints exist?

GAP Checklist Compliance (MANDATORY)

After all five category interviews, you MUST run each GAP checklist or explicitly record a skip with reason. These checklists catch constraints that interviews alone miss -- early manifolds that skipped them had thin, untestable constraint sets.

GAP	Checklist	When Required
GAP-03	Core Data Path Analysis	Always (any feature with data flow)
GAP-09	Crypto/Auth Attack Surface	When constraints involve auth/crypto
GAP-10	Resource Exhaustion	When unauthenticated endpoints or paths exist
GAP-11	External Dependency Resilience	When external HTTP dependencies exist
GAP-14	Input Validation Derivation	When constraints reference data formats
GAP-17	Concurrency Considerations	When constraints involve shared state

Record compliance in JSON under "gap_checklist_compliance":

{
  "gap_checklist_compliance": [
    {"gap": "GAP-03", "status": "COMPLETED"},
    {"gap": "GAP-09", "status": "SKIPPED", "skip_reason": "No auth/crypto constraints in this feature"},
    {"gap": "GAP-10", "status": "COMPLETED"},
    {"gap": "GAP-11", "status": "SKIPPED", "skip_reason": "No external HTTP dependencies"},
    {"gap": "GAP-14", "status": "COMPLETED"},
    {"gap": "GAP-17", "status": "SKIPPED", "skip_reason": "CLI tool, no shared state"}
  ]
}

Each checklist MUST be either COMPLETED or SKIPPED with documented reason. Omission is not allowed -- if you forget a checklist, the post-phase validation should surface it.

Pre-mortem Pass (run after elicitation, before phase closes)

After all five category interviews are complete, run a stress-test pass before committing the phase.

Say to the user:

"Before we close constraint discovery, let's stress-test what we have. Imagine it is [TIMEFRAME from outcome]. This has clearly failed — not partially, just failed. Give me three failure stories:

1. One you could have seen coming
2. One that surprised you
3. One caused by someone else's action or inaction"

Three stories are required. One story produces the obvious failure. Three stories reliably surface assumption violations and external dependencies.

For each story:

• Identify which category the violated constraint belongs to
• If not already in the constraint set: add it, tag source: pre-mortem
• If already in the set: confirm and tag source: validated-pre-mortem
• Use AskUserQuestion to present the three failure story prompts

Constraint Quality Check (Post-Elicitation)

After all constraints are discovered (including pre-mortem additions), score each on three dimensions (1-3 scale):

Score	Specificity	Measurability	Testability
1	Vague ("should be fast")	Unmeasurable ("code quality")	Requires judgment ("user-friendly")
2	Directional ("under 500ms")	Proxy-measurable ("coverage > 70%")	Requires manual test ("audit passes")
3	Precise ("p99 < 200ms, p50 < 80ms")	Directly measurable ("APM response time")	Automatable ("test asserts < 200ms")

Constraints scoring 1 on any dimension get flagged with a suggestion:

"Consider refining [ID]: [dimension] is weak. Current: '[text]'. Suggestion: '[improved version]'"

Store scores in JSON (optional field on each constraint):

{"id": "B1", "type": "invariant", "quality": {"specificity": 3, "measurability": 3, "testability": 3}}

Low scores are warnings, not blockers. The user may accept a vague constraint if it cannot be further specified. But surfacing the weakness drives improvement -- early manifolds had constraints like "must work" that later had to be reworked.

Draft Required Truths (Seeding for m3)

After all interviews, pre-mortem, and quality scoring, auto-generate a draft_required_truths list to seed m3-anchor. This reduces context loss between phases.

Generation rules:

1. For each INVARIANT constraint, draft: "For [constraint statement] to hold, [inferred precondition] must be true"
2. For each pair of constraints sharing hidden dependency keywords (ACID, durable, secure, etc.), draft a dependency RT
3. For each constraint scored 1 on testability, draft: "[constraint] requires a testable proxy metric"

Store in JSON as "draft_required_truths":

{
  "draft_required_truths": [
    {"id": "DRT-1", "seed_from": ["B1"], "draft_statement": "Error classification system must exist to distinguish transient from permanent failures", "confidence": "high"},
    {"id": "DRT-2", "seed_from": ["T3", "O4"], "draft_statement": "File splits and sync pipeline must be updated atomically", "confidence": "medium"}
  ]
}

These are DRAFTS, not finalized required truths. m3-anchor will validate, refine, or discard each one. Mark explicitly: "These seed m3 -- they are NOT commitments."

Constraint Genealogy Tagging (applied during elicitation)

Every constraint carries two optional tags that record its origin and challengeability. These are populated in the JSON structure file.

Source tag (how the constraint was discovered):

Source	Meaning	Default?
interview	Named explicitly during elicitation	Yes — applied automatically
pre-mortem	Discovered through failure analysis	Applied by pre-mortem pass
assumption	Believed true, unverified	Must be explicitly set

Challenger tag (can it be challenged?):

Challenger	Meaning	Resolution implication
regulation	Legal/regulatory requirement	Cannot be challenged. Route around it.
stakeholder	Named party's stated need	Can be negotiated
technical-reality	Physical/architectural limit	Cannot change within scope
assumption	Believed true, unverified	Must be confirmed before m4. Blocks generation if unconfirmed.

CRITICAL: These are separate enums. Do NOT mix them.

• source accepts ONLY: interview, pre-mortem, assumption
• challenger accepts ONLY: regulation, stakeholder, technical-reality, assumption
• technical-reality is a challenger, not a source. Using it as a source will fail schema validation.

Smart defaults (U2): Source defaults to interview. Challenger is inferred — only prompt the user when the challenger classification would change the resolution direction (e.g., when a constraint seems like it could be either regulation or stakeholder). Never make the user fill in both tags for every constraint.

Downstream use:

• m2-tension: When two constraints conflict, their challenger tags determine resolution direction. Challenge the assumption, not the regulation.
• m4-generate: All challenger: assumption constraints are surfaced. User must acknowledge before generation proceeds.
• m5-verify: Flag any INVARIANT with challenger: assumption as a convergence risk.

Probabilistic Bounds (applied to metric-based constraints only)

When a constraint contains a measurable threshold (latency, success rate, cost, time, count), prompt:

"Is this a hard ceiling that must hold for every instance, or a statistical target? If statistical, what percentile or confidence level applies?"

Examples:

• Deterministic: "must never exceed 500ms" → threshold: {kind: deterministic, ceiling: "500ms"}
• Statistical: "p99 < 200ms, p50 < 80ms" → threshold: {kind: statistical, p99: "200ms", p50: "80ms"}
• Rate-based: "< 0.1% failure rate over rolling 24h" → threshold: {kind: statistical, failure_rate: "< 0.1%", window: "24h"}
• Non-software: "budget must not exceed ₹40L" → deterministic. "Project profitable within 18 months" → statistical (what confidence?)

Firing rule (U3): Only prompt for constraints with measurable quantities. Skip qualitative constraints ("code should be readable", "interface should feel intuitive"). If in doubt, ask the user rather than guessing.

Schema: Add threshold object to the constraint in .manifold/<feature>.json:

{"id": "T1", "type": "boundary", "threshold": {"kind": "statistical", "p99": "200ms"}}

Example

/manifold:m1-constrain payment-retry

CONSTRAINT DISCOVERY: payment-retry

CONSTRAINTS DISCOVERED:

Business:
- B1: No duplicate payments (INVARIANT)
- B2: 95% success rate for transient failures (GOAL)
- B3: Retry window ≤ 72 hours (BOUNDARY)

Technical:
- T1: API response < 200ms including retries (BOUNDARY)
- T2: Support 10K concurrent retry operations (GOAL)

UX:
- U1: Clear retry status visible to user (GOAL)
- U2: No user action required for automatic retries (INVARIANT)

Security:
- S1: Retry logs must not contain card numbers (INVARIANT)
- S2: All retry attempts audited (INVARIANT)

Operational:
- O1: Retry queue depth monitored (GOAL)
- O2: Alert on retry success rate < 90% (BOUNDARY)

Updated: .manifold/payment-retry.json + .manifold/payment-retry.md (12 constraints)

Next: /manifold:m2-tension payment-retry

Context Lookup (MANDATORY)

Before starting constraint discovery, research the feature's domain to ground the interview in current facts. AI training data may be outdated—constraints based on stale information lead to rework.

Steps

1. Extract domain topics from the feature name, outcome statement, and any user-provided context (e.g., feature payment-retry → topics: payment processing, retry strategies, idempotency, PCI compliance)
2. Use WebSearch to look up:
   • Current best practices and industry standards for the domain
   • Recent API changes, deprecations, or version updates for relevant technologies
   • Current regulatory or compliance requirements (if applicable)
   • Known pitfalls or failure modes documented by practitioners
3. Summarize findings in a brief "Domain Context" block shown to the user before the interview begins:

DOMAIN CONTEXT (via web search):
- [Key finding 1 with source]
- [Key finding 2 with source]
- [Key finding 3 with source]

4. Use these findings to inform the constraint interview—ask sharper questions and propose constraints that reflect current reality rather than assumptions

When to Skip

• --skip-lookup flag is passed
• The feature is purely internal with no external dependencies or domain standards (e.g., refactoring an internal utility)

Why This Matters

Without context lookup, the AI may:

• Propose constraints based on outdated API behaviors or deprecated standards
• Miss recent security advisories or compliance changes
• Overlook newer, better approaches that didn't exist at training time
• Force the user to repeatedly correct factual errors during the interview

Execution Instructions

For JSON+Markdown Format (Default)

1. Run Context Lookup (see above) — research the feature domain via WebSearch
2. Read existing structure from .manifold/<feature>.json
3. Read existing content from .manifold/<feature>.md
4. If --category specified, focus on that category only
5. For each category, ask probing questions and classify responses
6. Assign constraint IDs (B1, T1, U1, S1, O1, etc.)
7. Update TWO files:
   • .manifold/<feature>.json — Add {"id": "B1", "type": "invariant"} to constraints
   • .manifold/<feature>.md — Add #### B1: Title + statement + rationale
8. Set phase to CONSTRAINED in JSON
9. Display summary and next step

For Legacy YAML Format

1. Run Context Lookup (see above) — research the feature domain via WebSearch
2. Read existing manifold from .manifold/<feature>.yaml
3. If --category specified, focus on that category only
4. For each category, ask probing questions and classify responses
5. Assign constraint IDs (B1, T1, U1, S1, O1, etc.)
6. Update the manifold YAML with discovered constraints
7. Set phase to CONSTRAINED
8. Display summary and next step

Format Detection & Lock

The CLI auto-detects format:

• If .json + .md exist → JSON+Markdown hybrid
• If only .yaml exists → Legacy YAML
• Use manifold show <feature> to see current format

Format lock: If .manifold/<feature>.json exists, you MUST use JSON+Markdown format for ALL subsequent updates. Never create or update a .yaml file when .json exists for the same feature.

⚠️ Mandatory Post-Phase Validation

After updating manifold files, you MUST run validation before showing results:

manifold validate <feature>

If validation fails, fix the errors BEFORE proceeding. The JSON structure must conform to the schema defined in install/manifold-structure.schema.json. The pre-commit hook will also enforce this — invalid manifolds cannot be committed.

Schema reference: cli/lib/structure-schema.ts (Zod) / install/manifold-structure.schema.json (JSON Schema)

Interaction Rules (MANDATORY)

<!-- Satisfies: RT-1 (next-step templates), RT-3 (structured input), U1 (suggest next), U2 (AskUserQuestion) -->

1. Questions → AskUserQuestion: When you need user input during this phase, use the AskUserQuestion tool with structured options. NEVER ask questions as plain text without options.
2. Phase complete → Suggest next: After completing this phase, ALWAYS include the concrete next command (/manifold:mN-xxx <feature>) and a one-line explanation of what the next phase does.
3. Trade-offs → Labeled options: When presenting alternatives, use AskUserQuestion with labeled choices (A, B, C) and descriptions.