@momentiq/dark-factory-cli 3.0.0 → 3.0.2

package/README.md

@@ -42,8 +42,8 @@ relevant) as `df` subcommands:
 
 The package also ships five reusable GitHub Actions workflows
 (`.github/workflows/*.yml`) that consumers wire up via `uses:`. See the
-[root README](../../README.md#reusable-workflows) for the consumer wiring
-pattern.
+[root README](https://github.com/momentiq-ai/dark-factory/blob/main/README.md#reusable-workflows)
+for the consumer wiring pattern.
 
 ## Status
 
@@ -163,22 +163,19 @@ used when:
   hooks locally.
 - A hook bypass landed and the CI gate needs to re-evaluate.
 - The developer hasn't logged in to a vendor CLI yet
-  (`cursor login` / `codex login` / Claude desktop OAuth).
+  (`cursor-agent login` / `codex login` / Claude desktop OAuth).
 
 ### `.agent-review/config.json` — the profile that pins subscription auth
 
 ```json
 {
   "version": 2,
-  "critics": [
-    { "id": "cursor-local-chief-engineer", "adapter": "cursor-sdk", ... },
-    { "id": "codex-local-chief-engineer", "adapter": "codex-sdk", ... }
-  ],
   "profiles": {
     "local": {
-      "criticIds": ["cursor-local-chief-engineer", "codex-local-chief-engineer"],
-      "quorum": 1,
+      "criticIds": ["cursor-cli-chief-engineer", "codex-local-chief-engineer"],
+      "quorum": 2,
       "auth": {
+        "cursor-cli-chief-engineer": "chatgpt",
         "codex-local-chief-engineer": "chatgpt"
       }
     },
@@ -193,10 +190,22 @@ used when:
 }
 ```
 
-The `local` profile pins `codex` to `"chatgpt"` — the Codex SDK will use
-`~/.codex/auth.json` (from `codex login`) and **NOT** fall back to
-`CODEX_API_KEY` even if it's set in env. This is the firewall against
-accidental API-token billing.
+The block shows the **`profiles`** map — the local/cloud profile wiring. The
+ids it references (e.g. `cursor-cli-chief-engineer`) are critics defined in the
+config's top-level `critics` array — each with `id`, `name`, `adapter`,
+`required`, `runtime`, and `model` — omitted here to keep the focus on the auth
+wiring. Step 2 of the setup checklist below points to the complete, schema-valid
+file.
+
+The `local` profile wires Cursor to the **`cursor-cli`** subscription
+adapter (`cursor-agent login`, no API key) and pins both
+`cursor-cli-chief-engineer` and `codex-local-chief-engineer` to
+`"chatgpt"` — each vendor CLI uses its logged-in subscription session
+(`~/.codex/auth.json` for Codex) and does **NOT** fall back to
+`CURSOR_API_KEY` / `CODEX_API_KEY` even if set in env. This is the
+firewall against accidental API-token billing. The `cloud` profile
+deliberately keeps the API-key `cursor-sdk` critic — CI runners have no
+subscription login.
 
 `df doctor --profile local` validates the configured subscription source
 is reachable. Run it after first-time setup.
@@ -253,10 +262,19 @@ API — see `packages/cli/src/doppler-bootstrap.ts` for the
 ### First-time setup checklist
 
 1. `npm install --ignore-scripts @momentiq/dark-factory-cli`
-2. Add `.agent-review/config.json` with the `local` profile (above).
+2. Create `.agent-review/config.json`: copy the canonical
+   [`.agent-review/config.json`](https://github.com/momentiq-ai/dark-factory/blob/main/.agent-review/config.json)
+   from the `momentiq-ai/dark-factory` repo and adjust it to your source layout
+   (see the [consumer-adoption guide](https://github.com/momentiq-ai/dark-factory/blob/main/docs/CONSUMER-ADOPTION.md)
+   §6). To avoid drift, swap `blob/main` in those links for the tag matching
+   your installed CLI version (e.g. `blob/dark-factory-cli-v3.0.1`); `df doctor`
+   flags a mismatch. No API key needed — it pins the `local`
+   profile to your Cursor / Codex subscription logins. (Optional: with an
+   `ANTHROPIC_API_KEY` set, `df onboard --apply --profile local` generates a
+   repo-tailored config for you.)
 3. Add `.husky/post-commit` + `.husky/pre-push` (samples above).
 4. `git config --local core.hooksPath .husky`
-5. `cursor login` / `codex login` (or Claude desktop OAuth) on the workstation.
+5. `cursor-agent login` / `codex login` (or Claude desktop OAuth) on the workstation.
 6. Run `df doctor --profile local` — should report all OK.
 7. Commit something — observe `.git/agent-reviews/<sha>.json` arrives.
 8. (Optional) Set up CI with `CURSOR_API_KEY` / `CODEX_API_KEY` /

package/dist/branch-protection/audit_branch_protection.py

@@ -59,7 +59,11 @@ Environment:
 
 Outputs:
 
-  exit 0  — spec == live, no divergence;
+  exit 0  — spec == live, no divergence. May still print advisory
+            ``[branch-protection-audit] WARNING: ...`` lines above the OK
+            banner — e.g. a required EXTERNAL reusable-workflow context whose
+            inner job name cannot be resolved offline is skipped-with-warning
+            (issue #341). Warnings never change the exit code;
   exit 1  — divergence (structured field-by-field report on stdout);
   exit 2  — usage / configuration error (e.g., spec.yaml missing).
 """
@@ -124,20 +128,33 @@ class Divergence:
 @dataclass
 class AuditReport:
     divergences: list[Divergence] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
 
     @property
     def ok(self) -> bool:
+        # Warnings are advisory (e.g. an unverifiable external reusable-workflow
+        # context, issue #341); only divergences fail the audit.
         return not self.divergences
 
     def add(self, *args: Any, **kwargs: Any) -> None:
         self.divergences.append(Divergence(*args, **kwargs))
 
+    def warn(self, message: str) -> None:
+        self.warnings.append(message)
+
     def render(self) -> str:
+        warning_block = "".join(
+            f"[branch-protection-audit] WARNING: {w}\n" for w in self.warnings
+        )
         if self.ok:
-            return "[branch-protection-audit] OK: spec.yaml matches live ruleset.\n"
+            return (
+                warning_block
+                + "[branch-protection-audit] OK: spec.yaml matches live ruleset.\n"
+            )
         body = "\n".join(d.render() for d in self.divergences)
         return (
-            "[branch-protection-audit] FAIL: spec.yaml vs live ruleset divergence:\n"
+            warning_block
+            + "[branch-protection-audit] FAIL: spec.yaml vs live ruleset divergence:\n"
             f"{body}\n"
         )
 
@@ -152,37 +169,126 @@ def load_spec(path: Path) -> dict[str, Any]:
     return data
 
 
-def extract_workflow_emitted_contexts(workflows_dir: Path) -> set[str]:
+@dataclass
+class EmittedContexts:
+    """Status-check contexts a workflow directory statically emits.
+
+    ``static`` — contexts resolvable offline: each job's ID, its static
+    ``name:``, and — for a job that calls a LOCAL reusable workflow
+    (``uses: ./.github/workflows/<wf>.yml``) — the compound context
+    ``<caller-job-id> / <callee-job-name>`` for every top-level job of that
+    reusable workflow (GitHub emits one status check per inner job, prefixed
+    by the CALLER JOB ID; CONSUMER-ADOPTION.md §8).
+
+    ``unresolvable_external_callers`` — maps a reusable-caller job's ID to its
+    ``uses:`` ref, for callers that invoke an EXTERNAL reusable workflow
+    (``<owner>/<repo>/.github/workflows/..@<ref>``). Their inner job names live
+    in another repo and cannot be resolved offline, so a required compound
+    context ``<caller-job-id> / <x>`` is UNVERIFIABLE here — skipped with a
+    warning rather than failed (issue #341).
+    """
+
+    static: set[str] = field(default_factory=set)
+    unresolvable_external_callers: dict[str, str] = field(default_factory=dict)
+
+
+def _job_display_label(job_id: str, job: dict[str, Any]) -> str:
+    """A job's display name: its static ``name:`` when set (and free of
+    unresolved ``${{ }}`` expressions), else the job ID. For a reusable
+    workflow's inner job this is the ``<callee-job-name>`` segment of the
+    emitted check (it defaults to the job id when no ``name:`` is set). The
+    CALLER segment of a reusable context is always the caller JOB ID, not this
+    label (CONSUMER-ADOPTION.md §8)."""
+    name = job.get("name")
+    if isinstance(name, str) and name and "${{" not in name:
+        return name
+    return job_id
+
+
+def _read_workflow_jobs(path: Path) -> dict[str, Any] | None:
+    """Parse a workflow file and return its ``jobs`` mapping, or ``None`` if the
+    file is missing, unreadable, malformed, or declares no jobs mapping."""
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    jobs = data.get("jobs")
+    return jobs if isinstance(jobs, dict) else None
+
+
+def extract_workflow_emitted_contexts(workflows_dir: Path) -> EmittedContexts:
     """Collect status-check contexts that workflow files statically emit.
 
-    A workflow job emits a context equal to its ``name:`` value if one is
-    declared, otherwise its job ID. This is the simple, static case. We do
-    **not** expand matrix job names because that requires evaluating the
-    matrix at runtime; callers must supplement with a manual exception for
-    matrix-generated contexts if needed.
+    A normal job emits a context equal to its ``name:`` if declared, else its
+    job ID. A job that calls a reusable workflow (a job-level ``uses:``) emits
+    one status check per inner job of that reusable workflow, named
+    ``<caller-job-id> / <callee-job-name>`` — the caller segment is the job id,
+    not a caller ``name:`` override (CONSUMER-ADOPTION.md §8):
+
+      * LOCAL reusable (``uses: ./.github/workflows/<wf>.yml``) — reusable
+        workflows must live in ``.github/workflows/``, i.e. the directory being
+        scanned, so the referenced file is read by basename and every top-level
+        inner job's compound context is added to ``static`` (full offline
+        verification; a bogus ``<caller-job-id> / <x>`` still fails).
+      * EXTERNAL reusable (``<owner>/<repo>/.github/workflows/..@<ref>``) — the
+        inner jobs live in another repo, so the caller job id is recorded in
+        ``unresolvable_external_callers`` and its compound contexts are
+        skipped-with-warning instead of failed-closed (issue #341).
+
+    Matrix job names are still **not** expanded (they require runtime
+    evaluation); a required matrix-expanded context still surfaces as a
+    divergence.
     """
-    emitted: set[str] = set()
+    result = EmittedContexts()
     if not workflows_dir.exists():
-        return emitted
+        return result
     for ext in ("*.yml", "*.yaml"):
         for path in workflows_dir.glob(ext):
-            try:
-                data = yaml.safe_load(path.read_text(encoding="utf-8"))
-            except (OSError, yaml.YAMLError):
-                continue
-            if not isinstance(data, dict):
-                continue
-            jobs = data.get("jobs") or {}
-            if not isinstance(jobs, dict):
+            jobs = _read_workflow_jobs(path)
+            if jobs is None:
                 continue
             for job_id, job in jobs.items():
                 if not isinstance(job, dict):
                     continue
-                emitted.add(job_id)
+                result.static.add(job_id)
                 job_name = job.get("name")
                 if isinstance(job_name, str) and job_name:
-                    emitted.add(job_name)
-    return emitted
+                    result.static.add(job_name)
+
+                uses = job.get("uses")
+                if not isinstance(uses, str) or not uses.strip():
+                    continue  # normal job — bare job_id/name already recorded.
+
+                # GitHub prefixes a reusable workflow's emitted checks with the
+                # CALLER JOB ID — never the caller's `name:` display override:
+                # `<caller-job-id> / <callee-job-name>` (CONSUMER-ADOPTION.md §8;
+                # a caller `name:` broke this contract in issue #27).
+                if uses.startswith("./"):
+                    # LOCAL reusable workflow. Resolve by basename within the
+                    # workflows dir (reusable workflows must live there) and add
+                    # every inner job's compound context to `static`.
+                    inner_path = workflows_dir / Path(uses.split("@", 1)[0]).name
+                    inner_jobs = _read_workflow_jobs(inner_path)
+                    if inner_jobs is None:
+                        # Genuinely unresolvable local ref (missing/broken
+                        # file). Add nothing so a required compound context
+                        # falls through to the normal fail path, preserving the
+                        # #168/#175 never-goes-green guard.
+                        continue
+                    for inner_id, inner_job in inner_jobs.items():
+                        if not isinstance(inner_job, dict):
+                            continue
+                        callee_name = _job_display_label(inner_id, inner_job)
+                        result.static.add(f"{job_id} / {callee_name}")
+                else:
+                    # EXTERNAL reusable workflow — inner jobs are in another
+                    # repo, unresolvable offline. Key on the caller JOB ID (the
+                    # documented context prefix) so
+                    # compare_emitted_status_checks can skip-with-warning.
+                    result.unresolvable_external_callers[job_id] = uses
+    return result
 
 
 def compare_emitted_status_checks(
@@ -200,9 +306,28 @@ def compare_emitted_status_checks(
         return
     emitted = extract_workflow_emitted_contexts(workflows_dir)
     for context in required_contexts:
-        if context in emitted:
+        if context in emitted.static:
             continue
-        closest = difflib.get_close_matches(context, sorted(emitted), n=1, cutoff=0.5)
+        # Reusable-workflow caller (issue #341): a compound context
+        # ``<caller> / <inner>`` whose ``<caller>`` invokes an EXTERNAL reusable
+        # workflow is unverifiable offline — skip WITH A WARNING, do not fail.
+        # LOCAL reusable callers are already fully enumerated in `static`, and a
+        # ``<caller>`` that is a normal/nonexistent job is NOT in this set, so
+        # both still fall through to the fail path below (non-weakening).
+        caller = context.partition(" / ")[0] if " / " in context else None
+        if caller and caller in emitted.unresolvable_external_callers:
+            uses_ref = emitted.unresolvable_external_callers[caller]
+            report.warn(
+                f"Required context {context!r} is emitted by reusable-workflow "
+                f"caller job {caller!r} (uses: {uses_ref}), whose inner job name "
+                f"lives in an external repo and cannot be resolved offline. "
+                f"Emission is UNVERIFIED here — skipped, not failed (issue #341). "
+                f"Confirm that reusable workflow emits this check at runtime."
+            )
+            continue
+        closest = difflib.get_close_matches(
+            context, sorted(emitted.static), n=1, cutoff=0.5
+        )
         closest_name = closest[0] if closest else None
         report.add(
             field="required_status_checks.contexts.emitted",
@@ -211,8 +336,9 @@ def compare_emitted_status_checks(
             detail=(
                 f"Required context {context!r} is not emitted by any job ID or "
                 f"job name in {workflows_dir / '*.yml'} or {workflows_dir / '*.yaml'}. "
-                f"Matrix-expanded names and reusable-workflow caller contexts are not "
-                f"statically checked."
+                f"Matrix-expanded names are not statically checked; reusable-workflow "
+                f"caller contexts are verified against LOCAL reusable workflows and "
+                f"skipped-with-warning only for EXTERNAL ones."
             ),
         )
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@momentiq/dark-factory-cli",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Dark Factory OSS CLI — multi-vendor adversarial critic orchestration (Cursor, Codex, Gemini, Grok) with min-complete-quorum aggregation and trusted-surface rebind",
   "license": "Apache-2.0",
   "homepage": "https://momentiq.ai/dark-factory",

package/skills/designer-handoff/SKILL.md.tmpl

@@ -27,18 +27,30 @@ unassigned; it prints the Issue URL. Link the relevant PR or issue with
 
 ```bash
 df handoff --link pr:<PR#> <<'EOF'
-<the composed, scrubbed note — see structure below>
+<the composed, scrubbed note from "Dual-register" below —
+ INCLUDING its <!-- agent-context:v1 --> … <!-- /agent-context:v1 --> markers>
 EOF
 ```
 
+The note **must** be wrapped in the `<!-- agent-context:v1 -->` …
+`<!-- /agent-context:v1 -->` markers (they anchor the Issue-body upsert);
+`df handoff` refuses a note that is missing them.
+
 ## Dual-register: two audiences, one artifact
 
 Write the note for the **engineer**, and speak a separate plain sentence to the
 **operator**.
 
-Engineer-facing note (structured, precise):
+Engineer-facing note (structured, precise). Keep the `agent-context:v1` markers
+around the whole note — copy this verbatim into the heredoc above:
 
 ```markdown
+<!-- agent-context:v1 -->
+> 🤖 **Handoff context** — transient working memory, not a source of truth.
+> _Updated: <YYYY-MM-DD> by <your session>_
+
+**Work-stream:** `<the ask, in one line>` · the handoff Issue's title.
+
 ## Intent
 What the operator asked for, in their words.
 
@@ -48,6 +60,7 @@ What is already built and where (branch or PR), and what is verified visually.
 ## Blocked — why
 The specific boundary: which scope, protected path, dependency, or gate — and
 what an engineer needs to decide or do next.
+<!-- /agent-context:v1 -->
 ```
 
 Operator-facing sentence (plain, framed as progress):

package/skills/designer-ship/SKILL.md.tmpl

@@ -18,12 +18,14 @@ The brief's **Done-when checkboxes are the acceptance criteria.** Before
 shipping, confirm each is satisfied and backed by the before/after screenshots
 from `/designer-build` — a Done-when item with no visible proof is not done.
 
-Make "done" proof-bound, not free text. Where the change has a
-`.darkfactory/objectives.yaml`, verify it and read the closeout proof with
-`df prove` (per-objective proven/pending/failed); see the `/objectives` skill
-for authoring and binding mechanics. (Automated derivation of objectives
-directly from a brief is a later Designer-Mode phase; today, treat the Done-when
-list as the contract and verify each item visually.)
+Make "done" proof-bound, not free text. Derive an objectives contract straight
+from the brief with **`df objectives derive --brief <brief-path> --apply`** — it
+writes one objective per `## Done-when` checkbox to `.darkfactory/objectives.yaml`,
+each text-hash-bound to its source line (id form `brief-<slug>#ac<k>`). Verify the
+bindings and read the closeout proof with `df prove` (per-objective
+proven/pending/failed); see the `/objectives` skill for authoring and binding
+mechanics. Still confirm each Done-when item **visually** — the before/after
+screenshots are the evidence behind the proof.
 
 ## 2. Run the gates locally first
 
@@ -42,14 +44,15 @@ Mode: designer
 Closes #<N>
 ```
 
-The `Mode: designer` trailer tags the PR as designer-driven. Today, scope is
-enforced live by the PreToolUse guard during the session, and the change still
-faces the full multi-vendor critic quorum + merge queue like any other PR. The
-deterministic mode-scope critic — which reads this trailer to validate the diff
-against the catalog's writeScopes / protectedPaths / diffBudget and block an
-out-of-scope diff at merge time, even from a jailbroken local session — lands in
-a later Designer-Mode phase; the trailer is the label it will key on.
-`Closes #<N>` links the tracking issue.
+The `Mode: designer` trailer is what the **deterministic mode-scope critic**
+keys on: it reads the trailer, loads the catalog, and validates the diff against
+the mode's `writeScopes` / `protectedPaths` / `diffBudget` / `dependencyPolicy`,
+blocking an out-of-scope diff at merge time — even from a jailbroken local
+session, because CI re-derives scope from the *committed* trailer + catalog
+independently of whatever happened locally. Scope is *also* enforced live
+in-session by the PreToolUse guard, and the change still faces the full
+multi-vendor critic quorum + merge queue like any other PR. `Closes #<N>` links
+the tracking issue.
 
 Open the PR and embed the **before/after screenshots** in the body so the change
 is visible to reviewers and the operator: