@codedrifters/configulator 0.0.402 → 0.0.403

package/lib/index.js

@@ -4674,6 +4674,35 @@ function buildBaseBundle(paths = DEFAULT_AGENT_PATHS) {
           "schema and consumer example. `status:deferred` is a valid",
           "override value reserved for this exact use case.",
           "",
+          "### The `status:deferred` invariant",
+          "",
+          "**No agent, procedure, or sweep ever removes `status:deferred`.",
+          "Only a human promotes a deferred issue.**",
+          "",
+          "`status:deferred` records a deliberate human decision to park",
+          "work. Automation may read it, count it, and log it \u2014 but the",
+          "label is cleared exclusively by a human (or by a scheduled task",
+          "a human configured for that purpose). Concretely:",
+          "",
+          "- **Unblock sweeps skip it.** Both `check-blocked.sh unblock`",
+          "  and `unblock-dependents.sh` leave a `status:deferred` +",
+          "  `status:blocked` issue blocked when its dependencies close,",
+          "  emitting a `SKIP_DEFERRED #<n>` line instead of flipping to",
+          "  `status:ready`. Dependency resolution is not a promotion",
+          "  signal for parked work.",
+          "- **Dispatch scans exclude it.** `check-blocked.sh eligible`",
+          "  drops any issue carrying `status:deferred`, so a stray",
+          "  `status:ready` + `status:deferred` pairing never reaches a",
+          "  worker.",
+          "- **No sweep writes it either.** Automation adds",
+          "  `status:deferred` only at filing time via the configured",
+          "  `issueDefaults` \u2014 never as a runtime triage decision.",
+          "",
+          "An issue that legitimately needs to leave the parked backlog is",
+          "promoted by a human removing `status:deferred` and setting the",
+          "appropriate base status. Any automation that removes the label",
+          "is a bug.",
+          "",
           "### Blocking Rules",
           "",
           "Two rules force `status:blocked` \u2014 both are non-negotiable:",
@@ -15166,13 +15195,16 @@ function renderUnblockDependentsSection(ud) {
     "",
     "1. Searches open issues for `Depends on: #<closed>` references in",
     "   their body.",
-    "2. For each match, re-reads every dependency listed across",
+    "2. Skips any match carrying `status:deferred`, emitting a",
+    "   `SKIP_DEFERRED` line. A human-parked issue is never promoted by",
+    "   a sweep, no matter how its dependencies resolve.",
+    "3. For each remaining match, re-reads every dependency listed across",
     "   **all** `Depends on:` lines in the body (bodies routinely list",
     "   one dependency per line) and checks whether they are all closed.",
-    "3. If **all** dependencies are closed, flips the dependent from",
+    "4. If **all** dependencies are closed, flips the dependent from",
     "   `status:blocked` to `status:ready` and posts a one-line comment",
     "   citing the resolving issue.",
-    "4. If **some** dependencies are still open, leaves the dependent",
+    "5. If **some** dependencies are still open, leaves the dependent",
     "   as `status:blocked` and optionally posts a partial-unblock",
     "   comment (see the **Partial unblock behaviour** subsection",
     "   below).",
@@ -15206,6 +15238,7 @@ function renderUnblockDependentsSection(ud) {
     'UNBLOCKED #<dep> \u2014 all deps closed (<closed-list>) \u2014 "<title>"',
     'UNBLOCK_FAILED #<dep> \u2014 label flip failed (all deps closed: <closed-list>) \u2014 "<title>"',
     'STILL_BLOCKED #<dep> \u2014 waiting on <open-list> \u2014 "<title>"',
+    'SKIP_DEFERRED #<dep> \u2014 status:deferred; human-parked, not promoting \u2014 "<title>"',
     "NO_DEPENDENTS #<closed>",
     "```",
     "",
@@ -15215,7 +15248,10 @@ function renderUnblockDependentsSection(ud) {
     "error, permissions, or the dependent went stale between the",
     "search and the edit) \u2014 a human needs to retry or flip the label",
     "manually. `STILL_BLOCKED` lines mean the dependent stays blocked",
-    "pending other open deps. `NO_DEPENDENTS` means no open issue",
+    "pending other open deps. `SKIP_DEFERRED` lines mean the dependent",
+    "carries `status:deferred` and was deliberately left blocked even",
+    "though its dependencies resolved \u2014 the sweep never promotes a",
+    "human-parked issue. `NO_DEPENDENTS` means no open issue",
     "references the just-closed issue in a `Depends on:` line.",
     "",
     "### Partial unblock behaviour",
@@ -15366,7 +15402,7 @@ function renderUnblockDependentsScript(ud) {
     "# `status:blocked` \u2192 `status:ready` directly on the overflow.",
     'dependents=$(gh issue list --label "status:blocked" --state open \\',
     '  --search "in:body \\"Depends on:\\"" \\',
-    '  --json number,title,body --limit 100 2>/dev/null || echo "[]")',
+    '  --json number,title,body,labels --limit 100 2>/dev/null || echo "[]")',
     "",
     `count=$(echo "$dependents" | jq 'length')`,
     'if [[ "$count" -eq 0 ]]; then',
@@ -15374,6 +15410,18 @@ function renderUnblockDependentsScript(ud) {
     "  exit 0",
     "fi",
     "",
+    "# Human-parked candidates (`status:deferred`). Collected jq-side into a",
+    "# space-delimited lookup string rather than threaded through the",
+    "# tab-separated records below: an extra TSV field would either sit after",
+    "# dep_line (displacing the mandatory-last optional field) or before it",
+    "# (reintroducing the #884 IFS tab-collapse bug). The skip itself happens",
+    "# inside the loop, after the closed-issue reference test, so an unrelated",
+    "# deferred issue in the search window never emits a line. No agent or",
+    "# sweep ever removes `status:deferred` \u2014 only a human promotes it.",
+    `deferred_set=" $(echo "$dependents" | jq -r '`,
+    '  .[] | select(.labels | map(.name) | index("status:deferred")) | .number',
+    `' | tr '\\n' ' ')"`,
+    "",
     "# Union every `Depends on:` line per candidate (a body may list one",
     "# dependency per line) into a single space-joined dep string and stream",
     "# as tab-separated number / title / dep-line tuples.",
@@ -15409,6 +15457,14 @@ function renderUnblockDependentsScript(ud) {
     "",
     "  found_any=true",
     "",
+    "  # Deliberately-parked dependents never get promoted by a sweep, even",
+    "  # when every dependency has closed. Only a human clears",
+    "  # `status:deferred`.",
+    '  if [[ "$deferred_set" == *" ${num} "* ]]; then',
+    '    echo "SKIP_DEFERRED #${num} \u2014 status:deferred; human-parked, not promoting \u2014 \\"${title}\\""',
+    "    continue",
+    "  fi",
+    "",
     "  # Re-check every dep in the list. Fully-closed \u2192 unblock.",
     "  all_closed=true",
     '  open_deps=""',
@@ -15598,15 +15654,26 @@ function buildCheckBlockedScript(tiers, scopeGate, _runRatio) {
     "  # position.",
     "  local issues",
     '  issues=$(gh issue list --label "status:blocked" --state open \\',
-    '    --json number,body --limit 1000 2>/dev/null || echo "[]")',
+    '    --json number,body,labels --limit 1000 2>/dev/null || echo "[]")',
     "",
     "  local count",
     `  count=$(echo "$issues" | jq 'length')`,
     '  if [[ "$count" -eq 0 ]]; then',
-    '    echo "TRIAGE_DONE unblocked=0 still_blocked=0"',
+    '    echo "TRIAGE_DONE unblocked=0 still_blocked=0 deferred_skipped=0"',
     "    return 0",
     "  fi",
     "",
+    "  # Human-parked candidates (`status:deferred`). Collected jq-side into",
+    "  # a space-delimited lookup string rather than threaded through the",
+    "  # tab-separated records below: an extra TSV field would either sit",
+    "  # after dep_line (displacing the mandatory-last optional field) or",
+    "  # before it (reintroducing the #884 IFS tab-collapse bug). No agent",
+    "  # or sweep ever removes `status:deferred` \u2014 only a human promotes it.",
+    "  local deferred_set",
+    `  deferred_set=" $(echo "$issues" | jq -r '`,
+    '    .[] | select(.labels | map(.name) | index("status:deferred")) | .number',
+    `  ' | tr '\\n' ' ')"`,
+    "",
     "  local issue_data",
     `  issue_data=$(echo "$issues" | jq -r '`,
     "    .[] |",
@@ -15619,10 +15686,20 @@ function buildCheckBlockedScript(tiers, scopeGate, _runRatio) {
     "  # mirroring unblock-dependents.sh.",
     "  local unblocked_count=0",
     "  local still_blocked_count=0",
+    "  local deferred_skipped_count=0",
     "",
     "  while IFS=$'\\t' read -r num dep_line; do",
     '    [[ -z "$num" ]] && continue',
     "",
+    "    # Deliberately-parked issues never get promoted by a sweep, even",
+    "    # when every dependency has closed. Only a human clears",
+    "    # `status:deferred`.",
+    '    if [[ "$deferred_set" == *" ${num} "* ]]; then',
+    '      echo "SKIP_DEFERRED #${num} \u2014 status:deferred; human-parked, not promoting"',
+    "      deferred_skipped_count=$((deferred_skipped_count + 1))",
+    "      continue",
+    "    fi",
+    "",
     '    if [[ -z "$dep_line" ]]; then',
     '      echo "BLOCKED #${num} \u2014 no Depends on field found"',
     "      still_blocked_count=$((still_blocked_count + 1))",
@@ -15683,7 +15760,7 @@ function buildCheckBlockedScript(tiers, scopeGate, _runRatio) {
     '  done <<< "$issue_data"',
     "",
     "  # Single summary line consumed by the orchestrator.",
-    '  echo "TRIAGE_DONE unblocked=${unblocked_count} still_blocked=${still_blocked_count}"',
+    '  echo "TRIAGE_DONE unblocked=${unblocked_count} still_blocked=${still_blocked_count} deferred_skipped=${deferred_skipped_count}"',
     "}",
     "",
     "cmd_eligible() {",
@@ -15707,11 +15784,26 @@ function buildCheckBlockedScript(tiers, scopeGate, _runRatio) {
     "      continue",
     "    fi",
     "",
+    "    # Dispatch exclusions. `gh issue list` has no negative-label filter",
+    "    # for a label-filtered (non-search) listing, so both exclusions run",
+    "    # jq-side over the labels already fetched above \u2014 no new TSV field",
+    "    # is needed, and the mandatory-last dep_line ordering is untouched.",
+    "    #   - `status:needs-attention` is additive (it no longer replaces the",
+    "    #     base status), so a scope-gate-flagged issue keeps `status:ready`",
+    "    #     and would re-surface in every scan until a human clears the flag",
+    "    #     (#901). It is never dispatchable, so drop it from the scan.",
+    "    #   - `status:deferred` is human-parked: captured for provenance and",
+    "    #     never auto-dispatched. `status:ready` + `status:deferred` is",
+    "    #     reachable (e.g. after an unblock or a manual edit), so exclude",
+    "    #     it here as the dispatch-side half of the #887 guard.",
     "    local issue_data",
     `    issue_data=$(echo "$issues" | jq -r '`,
     "      .[] |",
+    "      (.labels | map(.name)) as $names |",
+    '      select($names | index("status:needs-attention") | not) |',
+    '      select($names | index("status:deferred") | not) |',
     '      (.body | split("\\n") | map(select(test("Depends on:"; "i"))) | join(" ")) as $dep_line |',
-    '      (.labels | map(.name) | map(select(startswith("type:"))) | .[0] // "") as $type_label |',
+    '      ($names | map(select(startswith("type:"))) | .[0] // "") as $type_label |',
     '      "\\(.number)\\t\\(.title)\\t\\($type_label)\\t\\($dep_line)"',
     "    ')",
     "",
@@ -16355,7 +16447,7 @@ function buildCheckBlockedScript(tiers, scopeGate, _runRatio) {
 function buildCheckBlockedProcedure(tiers, scopeGate = resolveScopeGate(), runRatio = resolveRunRatio()) {
   return {
     name: "check-blocked.sh",
-    description: "Token-efficient issue triage script with subcommands: eligible, unblock, stale, orphaned, lease-reconcile, maintenance, prs, scope. Sorts eligible issues by priority desc \u2192 funnel tier asc \u2192 issue number asc; the scope subcommand classifies a single issue against the scope-gate thresholds; the unblock subcommand applies the `status:blocked` \u2192 `status:ready` label flip itself, posts the canned unblock comment, and emits a single `TRIAGE_DONE unblocked=N still_blocked=M` summary line; the lease-reconcile subcommand auto-reconciles stuck `review:fixing` PR leases \u2014 re-applying `review:needs-worker` on an orphaned lease (fix-list stale, no worker report) so the Phase B1 drain retries, and removing `review:needs-worker` on a consumed-but-uncleared wedge (branch HEAD advanced past the fix-list, marker still set, no worker report) so the reviewer confirm pass can merge, always posting an audit-trail note comment and emitting a single `LEASE_RECONCILE orphaned=N consumed_uncleared=M` summary line; the maintenance subcommand flags stale issues with `status:needs-attention` (never auto-resets to `status:ready`), counts orphan branches/PRs, folds in the lease-reconcile sweep, and emits a `MAINTENANCE_DONE flagged_stale=N flagged_blocked=M orphan_branches=A orphan_prs=B needs_attention_total=T` summary line followed by the `LEASE_RECONCILE` line.",
+    description: "Token-efficient issue triage script with subcommands: eligible, unblock, stale, orphaned, lease-reconcile, maintenance, prs, scope. Sorts eligible issues by priority desc \u2192 funnel tier asc \u2192 issue number asc, excluding issues carrying `status:needs-attention` or `status:deferred`; the scope subcommand classifies a single issue against the scope-gate thresholds; the unblock subcommand applies the `status:blocked` \u2192 `status:ready` label flip itself, posts the canned unblock comment, skips human-parked `status:deferred` candidates with a `SKIP_DEFERRED` line, and emits a single `TRIAGE_DONE unblocked=N still_blocked=M deferred_skipped=K` summary line; the lease-reconcile subcommand auto-reconciles stuck `review:fixing` PR leases \u2014 re-applying `review:needs-worker` on an orphaned lease (fix-list stale, no worker report) so the Phase B1 drain retries, and removing `review:needs-worker` on a consumed-but-uncleared wedge (branch HEAD advanced past the fix-list, marker still set, no worker report) so the reviewer confirm pass can merge, always posting an audit-trail note comment and emitting a single `LEASE_RECONCILE orphaned=N consumed_uncleared=M` summary line; the maintenance subcommand flags stale issues with `status:needs-attention` (never auto-resets to `status:ready`), counts orphan branches/PRs, folds in the lease-reconcile sweep, and emits a `MAINTENANCE_DONE flagged_stale=N flagged_blocked=M orphan_branches=A orphan_prs=B needs_attention_total=T` summary line followed by the `LEASE_RECONCILE` line.",
     content: buildCheckBlockedScript(tiers, scopeGate, runRatio)
   };
 }
@@ -17037,14 +17129,20 @@ var orchestratorSubAgent = {
     "The script emits one summary line in this shape:",
     "",
     "```",
-    "TRIAGE_DONE unblocked=<N> still_blocked=<M>",
+    "TRIAGE_DONE unblocked=<N> still_blocked=<M> deferred_skipped=<K>",
     "```",
     "",
     "Per-issue informational lines (`UNBLOCKED #N`, `UNBLOCK_FAILED #N`,",
-    "`STILL_BLOCKED #N`, `BLOCKED #N \u2014 no Depends on field found`) are",
-    "emitted for log visibility but are **not** load-bearing for the",
-    "orchestrator \u2014 partial failures (one bad `gh` call) do not abort",
-    "the sweep, they are simply counted toward `still_blocked`.",
+    "`STILL_BLOCKED #N`, `SKIP_DEFERRED #N`, `BLOCKED #N \u2014 no Depends on",
+    "field found`) are emitted for log visibility but are **not**",
+    "load-bearing for the orchestrator \u2014 partial failures (one bad `gh`",
+    "call) do not abort the sweep, they are simply counted toward",
+    "`still_blocked`.",
+    "",
+    "`deferred_skipped` counts candidates the sweep deliberately left",
+    "blocked because they carry `status:deferred`. Those issues are",
+    "human-parked: no agent or sweep ever removes `status:deferred`, so",
+    "a non-zero count is expected steady-state noise, not a failure.",
     "",
     "This phase is the **fallback safety net** for agent-driven",
     "unblocking. Every agent that applies `status:done` already runs",
@@ -18224,9 +18322,11 @@ var checkBlockedCommand = {
     "reference, applies the `status:blocked` \u2192 `status:ready` label flip",
     "itself, posts the canned `Dependencies resolved \u2014 unblocking.`",
     "comment, and emits a single",
-    "`TRIAGE_DONE unblocked=<N> still_blocked=<M>` summary line. Per-issue",
-    "informational lines (`UNBLOCKED`, `UNBLOCK_FAILED`, `STILL_BLOCKED`)",
-    "are also emitted for log visibility.",
+    "`TRIAGE_DONE unblocked=<N> still_blocked=<M> deferred_skipped=<K>`",
+    "summary line. Candidates carrying `status:deferred` are skipped",
+    "rather than promoted \u2014 only a human clears that label. Per-issue",
+    "informational lines (`UNBLOCKED`, `UNBLOCK_FAILED`, `STILL_BLOCKED`,",
+    "`SKIP_DEFERRED`) are also emitted for log visibility.",
     "",
     "Summarise the output (the `TRIAGE_DONE` counts and the first few",
     "per-issue lines) \u2014 do **not** apply additional label flips yourself;",