Add constraint intelligence operating layer

.github/workflows/ci.yml

@@ -11,3 +11,21 @@ jobs:
       - run: python -m pytest -q
       - run: python -m pip wheel . --no-deps --wheel-dir dist
       - run: PYTHONPATH=src python -m living_context.cli --root . validate
+      - name: Compile warm-start constraint intelligence
+        run: |
+          python scripts/compile_constraint_corpus.py \
+            --input data/constraint_seed_signals.json \
+            --taxonomy config/constraint_taxonomy.json
+          test -s artifacts/constraint-intelligence.json
+          test -s artifacts/constraint-leaderboard.json
+          test -s artifacts/constraint-intelligence.md
+      - name: Upload warm-start intelligence
+        uses: actions/upload-artifact@v4
+        with:
+          name: warm-start-constraint-intelligence
+          path: |
+            artifacts/constraint-intelligence.json
+            artifacts/constraint-leaderboard.json
+            artifacts/constraint-intelligence.md
+          if-no-files-found: error
+          retention-days: 14

.github/workflows/github-review-queue.yml

@@ -0,0 +1,78 @@
+name: Build constraint intelligence queue
+
+on:
+  # The workflow is introduced by the constraint-intelligence PR itself, so the
+  # first authoritative live run occurs on the canonical main merge SHA.
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      created_after:
+        description: Earliest issue creation date (YYYY-MM-DD)
+        required: false
+        default: "2026-05-01"
+      min_score:
+        description: Minimum discovery qualification score
+        required: false
+        default: "45"
+  schedule:
+    - cron: "17 5 * * 1,4"
+
+# GitHub issue search has a secondary abuse limiter independent of the normal
+# request quota. Serialize this external-discovery workflow so PR, scheduled,
+# and manual runs cannot create avoidable concurrent search bursts.
+concurrency:
+  group: constraint-intelligence-${{ github.repository }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  discover-and-compile:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install test runner
+        run: python -m pip install pytest
+
+      - name: Run pipeline tests
+        run: python -m pytest tests/test_github_issue_discovery.py tests/test_constraint_intelligence.py -q
+
+      - name: Discover high-signal engineering pain
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CREATED_AFTER: ${{ inputs.created_after || '2026-05-01' }}
+          MIN_SCORE: ${{ inputs.min_score || '45' }}
+        run: |
+          python scripts/discover_github_issues.py \
+            --config config/constraint_signal_queries.json \
+            --created-after "$CREATED_AFTER" \
+            --min-score "$MIN_SCORE"
+
+      - name: Compile accumulated and fresh constraint intelligence
+        run: |
+          python scripts/compile_constraint_corpus.py \
+            --input data/constraint_seed_signals.json \
+            --input artifacts/github-review-queue.json \
+            --taxonomy config/constraint_taxonomy.json
+
+      - name: Upload intelligence artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: constraint-intelligence
+          path: |
+            artifacts/github-review-queue.json
+            artifacts/github-review-queue.md
+            artifacts/constraint-intelligence.json
+            artifacts/constraint-leaderboard.json
+            artifacts/constraint-intelligence.md
+          if-no-files-found: error
+          retention-days: 14

README.md

@@ -66,4 +66,35 @@ Project deletion is an explicit destructive operator action. The HTTP service is
 
 Classification is deterministic and intentionally conservative. A context pack is a source-linked retrieval artifact, not a completeness guarantee, autonomous memory, or decision-maker.
 
+## Constraint intelligence pipeline
+
+The repository includes a human-reviewed engineering-pain discovery and constraint-intelligence pipeline. GitHub is treated as a sensor network: strong market evidence is preserved even when a thread is a poor public-comment target.
+
+```bash
+python scripts/discover_github_issues.py \
+  --config config/constraint_signal_queries.json
+
+python scripts/build_constraint_intelligence.py \
+  --input artifacts/github-review-queue.json \
+  --taxonomy config/constraint_taxonomy.json
+```
+
+The compiler keeps two decisions separate:
+
+- **constraint value** — production evidence, economic consequence, workaround burden, recurrence, cross-system generality, buyer proximity, serviceability, proof feasibility, and urgency;
+- **intervention value** — whether this occurrence deserves corpus-only retention, watching, a diagnostic question, a precision comment, a reproduction, a patch/diagnostic, or operator assistance.
+
+Default public action is **no comment**. The system is designed to move repeated evidence from discovery toward diagnostics, reproductions, patches, audits, operator validation, and reusable product primitives rather than optimize comment count.
+
+Generated artifacts:
+
+- `artifacts/github-review-queue.json` / `.md` — evidence-preserving discovery queue;
+- `artifacts/constraint-intelligence.json` — signal-level scores and recommended interventions;
+- `artifacts/constraint-leaderboard.json` — ranked constraint families;
+- `artifacts/constraint-intelligence.md` — human operating report.
+
+See [`docs/CONSTRAINT_INTELLIGENCE_OPERATING_SYSTEM.md`](docs/CONSTRAINT_INTELLIGENCE_OPERATING_SYSTEM.md) for the exploration/exploitation gates, proof ladder, public contribution policy, daily/weekly loops, success metrics, and provisional audit offers.
+
+The original inspection details remain in [`docs/GITHUB_REVIEW_PIPELINE.md`](docs/GITHUB_REVIEW_PIPELINE.md).
+
 See [`docs/INTEGRATION.md`](docs/INTEGRATION.md), [`docs/API.md`](docs/API.md), and [`DEPLOYABILITY_DISTRIBUTION.md`](DEPLOYABILITY_DISTRIBUTION.md).

config/constraint_signal_queries.json

@@ -0,0 +1,132 @@
+{
+  "queries": [
+    {
+      "id": "runtime-truth-and-recovery",
+      "terms": [
+        "manual restart",
+        "stuck running",
+        "silent failure",
+        "not registered",
+        "workflow active",
+        "published but",
+        "readiness",
+        "liveness",
+        "reconnect"
+      ],
+      "exclude_labels": ["duplicate", "invalid", "good first issue"],
+      "help_angle": "Look for declared state diverging from actual serving state. Preserve as evidence by default; interact only if a concrete liveness/reconciliation gap remains unresolved."
+    },
+    {
+      "id": "side-effect-integrity",
+      "terms": [
+        "duplicate execution",
+        "sent twice",
+        "duplicate message",
+        "partial delivery",
+        "retry duplicate",
+        "false 500",
+        "already committed",
+        "idempotency",
+        "timeout retry"
+      ],
+      "exclude_labels": ["duplicate", "invalid", "good first issue"],
+      "help_angle": "Identify the exact operation identity and ambiguous-outcome boundary. Prefer reproduction/attempt tracing over generic idempotency advice."
+    },
+    {
+      "id": "identity-and-credentials",
+      "terms": [
+        "anonymous caller",
+        "authorization header",
+        "credential works",
+        "credential missing",
+        "user_id none",
+        "wrong user",
+        "request context lost",
+        "external secrets",
+        "oauth refresh"
+      ],
+      "exclude_labels": ["duplicate", "invalid", "good first issue"],
+      "help_angle": "Trace the effective principal/credential at the exact production execution boundary and compare it with the test/configuration surface."
+    },
+    {
+      "id": "persistence-resume-and-replay",
+      "terms": [
+        "resume fails",
+        "after restart",
+        "stale run",
+        "checkpoint",
+        "suspended run",
+        "paused run",
+        "replay duplicate",
+        "rehydrate",
+        "persisted state"
+      ],
+      "exclude_labels": ["duplicate", "invalid", "good first issue"],
+      "help_angle": "Determine authoritative run state, generation/revision identity, and whether restart/replay can create duplicate or stale continuation."
+    },
+    {
+      "id": "delivery-and-queue-assurance",
+      "terms": [
+        "never delivered",
+        "never sent",
+        "queued but",
+        "queue stuck",
+        "missed webhook",
+        "missed email",
+        "trigger stopped",
+        "message lost",
+        "partial delivery"
+      ],
+      "exclude_labels": ["duplicate", "invalid", "good first issue"],
+      "help_angle": "Separate internal completion from downstream delivery. Look for durable receipts, claim/dispatch state, partial outcomes, and reconciliation."
+    },
+    {
+      "id": "state-amplification-and-resource-pressure",
+      "terms": [
+        "out of memory",
+        "OOM",
+        "memory leak",
+        "swap",
+        "snapshot size",
+        "history size",
+        "redis memory",
+        "payload too large",
+        "manual restart"
+      ],
+      "exclude_labels": ["duplicate", "invalid", "good first issue"],
+      "help_angle": "Look for state retained or copied disproportionately across persistence/replay boundaries and quantify the amplification factor."
+    },
+    {
+      "id": "configuration-and-fidelity",
+      "terms": [
+        "config ignored",
+        "environment variable ignored",
+        "setting lost",
+        "deserialize",
+        "serialization",
+        "external secrets",
+        "works in test",
+        "works in editor",
+        "fails in production"
+      ],
+      "exclude_labels": ["duplicate", "invalid", "good first issue"],
+      "help_angle": "Compare declared/saved configuration with the effective runtime configuration and preserve provenance of what actually executed."
+    },
+    {
+      "id": "buyer-cost-and-workarounds",
+      "terms": [
+        "production outage",
+        "manual workaround",
+        "daily restart",
+        "rolled back",
+        "downgrade",
+        "hours debugging",
+        "days debugging",
+        "customer impact",
+        "enterprise production"
+      ],
+      "exclude_labels": ["duplicate", "invalid", "good first issue"],
+      "help_angle": "Prioritize measurable operator cost and buyer proximity. This query is for corpus enrichment even when no public contribution is appropriate."
+    }
+  ]
+}

config/constraint_taxonomy.json

@@ -0,0 +1,106 @@
+{
+  "version": 1,
+  "saturation_states": [
+    "emerging",
+    "confirmed",
+    "saturated",
+    "validating",
+    "serviceable",
+    "proven",
+    "productizable",
+    "commoditized",
+    "deprioritized"
+  ],
+  "constraints": [
+    {
+      "id": "operational-truth-divergence",
+      "name": "Operational truth divergence",
+      "description": "Configured, persisted, or control-plane state says a capability is healthy/active while the serving runtime is not actually performing it.",
+      "keywords": ["published", "active", "healthy", "ready", "liveness", "readiness", "not registered", "dead trigger", "stuck running", "silent failure", "manual restart", "reconnect"],
+      "economic_effects": ["missed events", "downtime", "manual monitoring", "incident response", "false operator confidence"],
+      "buyer_personas": ["automation engineer", "platform engineer", "devops", "technical founder"],
+      "interventions": ["runtime receipt", "active probe", "reconciliation", "degraded state", "watchdog"]
+    },
+    {
+      "id": "side-effect-integrity",
+      "name": "Ambiguous or duplicate side effects",
+      "description": "Retries, timeouts, replay, or fan-out make externally visible actions duplicate or leave their outcome ambiguous.",
+      "keywords": ["duplicate", "sent twice", "multiple sends", "retry", "timeout", "idempotency", "false 500", "already committed", "replay", "double", "partial delivery"],
+      "economic_effects": ["duplicate customer communication", "duplicate charges", "duplicate records", "manual reconciliation"],
+      "buyer_personas": ["automation engineer", "operations engineer", "platform engineer", "technical founder"],
+      "interventions": ["idempotency envelope", "operation receipt", "attempt ledger", "external receipt reconciliation"]
+    },
+    {
+      "id": "identity-credential-continuity",
+      "name": "Identity and credential continuity",
+      "description": "A user, tenant, credential, secret, scope, or request principal is lost or changed across execution surfaces.",
+      "keywords": ["credential", "authorization", "unauthorized", "anonymous caller", "user_id", "tenant", "request context", "secret", "oauth", "token", "principal", "401"],
+      "economic_effects": ["failed business action", "wrong-tenant action", "manual reauthentication", "security exposure"],
+      "buyer_personas": ["platform engineer", "security engineer", "automation engineer"],
+      "interventions": ["principal envelope", "credential-path trace", "scope verification", "context continuity test"]
+    },
+    {
+      "id": "durable-execution-correctness",
+      "name": "Persistence and resume correctness",
+      "description": "Runtime, persisted, restored, or resumed execution state disagree about the same logical run.",
+      "keywords": ["resume", "restart", "paused", "suspended", "checkpoint", "rehydrate", "persisted", "stale run", "continue", "fork", "snapshot"],
+      "economic_effects": ["stranded work", "duplicate work", "wrong continuation", "manual recovery"],
+      "buyer_personas": ["platform engineer", "ai engineer", "automation engineer"],
+      "interventions": ["resume generation", "compare-and-swap", "storage-authoritative recovery", "run lineage"]
+    },
+    {
+      "id": "delivery-assurance",
+      "name": "Silent delivery failure",
+      "description": "The internal operation completes or appears successful while the intended downstream delivery is partial, lost, or unclaimed.",
+      "keywords": ["not delivered", "never delivered", "partial delivery", "rejected", "queued", "never sent", "missing message", "webhook", "email", "discord", "sms"],
+      "economic_effects": ["lost customer communication", "missed SLA", "unprocessed events", "manual resend"],
+      "buyer_personas": ["operations engineer", "automation engineer", "support engineering"],
+      "interventions": ["delivery receipt", "outbox", "partial outcome semantics", "queue reconciliation"]
+    },
+    {
+      "id": "state-amplification",
+      "name": "State amplification and resource pressure",
+      "description": "Persisted, serialized, replayed, or retained state grows disproportionately and causes memory, storage, transport, or runtime failure.",
+      "keywords": ["oom", "out of memory", "memory", "gigabyte", "snapshot", "4mb", "grpc", "history", "redis", "state size", "swap", "leak"],
+      "economic_effects": ["crashes", "latency", "infrastructure cost", "manual restart"],
+      "buyer_personas": ["platform engineer", "sre", "devops"],
+      "interventions": ["bounded retention", "claim check", "by-reference state", "pressure budget"]
+    },
+    {
+      "id": "configuration-authority-drift",
+      "name": "Configuration authority drift",
+      "description": "Saved, displayed, cached, or reconstructed configuration differs from the configuration actually used by the runtime.",
+      "keywords": ["configuration", "config", "environment", "env var", "serialized", "deserialize", "external secrets", "model config", "ignored setting", "lost setting"],
+      "economic_effects": ["production mismatch", "failed deployment", "manual rollback", "unexpected behavior"],
+      "buyer_personas": ["platform engineer", "devops", "automation engineer"],
+      "interventions": ["effective-config fingerprint", "round-trip fidelity test", "configuration provenance"]
+    },
+    {
+      "id": "evidence-freshness",
+      "name": "Evidence freshness and stale projections",
+      "description": "A status, verification, health result, or derived projection remains authoritative after the underlying evidence has changed.",
+      "keywords": ["stale", "freshness", "verification", "old state", "cached", "outdated", "projection", "observed_at", "last success", "last failure"],
+      "economic_effects": ["false confidence", "wrong automation decision", "repeated work", "missed failure"],
+      "buyer_personas": ["platform engineer", "sre", "automation engineer"],
+      "interventions": ["evidence receipt", "freshness TTL", "source revision", "reconciliation"]
+    },
+    {
+      "id": "tenant-state-isolation",
+      "name": "Tenant and request state isolation",
+      "description": "State, memory, mutable objects, or routing identity crosses tenant, user, request, or session boundaries.",
+      "keywords": ["cross-user", "cross user", "wrong user", "tenant", "shared state", "same key", "collision", "leak", "request isolation", "session id"],
+      "economic_effects": ["data leakage", "wrong-user action", "security incident", "corrupted personalization"],
+      "buyer_personas": ["security engineer", "platform engineer", "ai engineer"],
+      "interventions": ["canonical scoped identity", "ownership validation", "request-generation isolation"]
+    },
+    {
+      "id": "provider-adapter-fidelity",
+      "name": "Provider and adapter fidelity",
+      "description": "Provider-specific event, ordering, correlation, or serialization semantics are lost at an adapter boundary.",
+      "keywords": ["provider", "adapter", "schema", "event shape", "index", "ordering", "correlation", "compatibility", "api changed", "unknown event"],
+      "economic_effects": ["silent wrong output", "integration outage", "manual compatibility work", "incorrect mapping"],
+      "buyer_personas": ["integration engineer", "platform engineer", "ai engineer"],
+      "interventions": ["normalization boundary", "correlation identity", "versioned fixtures", "conformance test"]
+    }
+  ]
+}