@bompus/house-rules 0.11.0 → 0.13.0

package/skills/hr-what-next/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hr-what-next
-description: "Reconcile remaining work and recommend priorities. Use for next, next?, what's next, what remains, backlog reviews, full-session audits of tasks and unanswered or past questions, and equivalent requests. Do not use for go or continue, which retain their acceptance/continuation meaning, or progress/ETA-only requests."
+description: "Reconcile remaining work and recommend priorities. Use for next, next?, what's next, what remains, backlog reviews, walk-throughs of the backlog item by item, full-session audits of tasks and unanswered or past questions, and equivalent requests. Do not use for go or continue, which retain their acceptance/continuation meaning, or progress/ETA-only requests."
 ---
 
 # What next
@@ -17,25 +17,55 @@ completed state before the completion message; a report alone does not do so.
 1. Choose the review scope from the request and its context. For a short
    "next?", check the current task, its ledger and latest results, plus this
    floor whatever the scope: every question from an earlier offer in this
-   conversation that the user has not answered, every owned uncommitted file,
-   unpushed commit or held checkout, and the number of other live ledger items
-   (deferred, unselected, blocked or follow-up) with a link to the ledger.
+   conversation that the user has not answered, every item deferred with only the
+   user's selection as its trigger, every owned uncommitted file, unpushed commit
+   or held checkout, and the number of other live ledger items (deferred,
+   awaiting selection, blocked or follow-up) with a link to the ledger.
+   When the session keeps a plan file, `scripts/check-open-work.mjs <plan>`
+   computes this floor (add `--checkout <path>` for each checkout touched, or
+   `--app-managed <path>` for one an app retires, which is reported but not a
+   finding): run it and quote its result instead of recalling the ledger. Its
+   "awaiting your yes/no" group lists the user-trigger deferrals by a text match.
+   Its "possibly finished" group lists items whose named pull requests or
+   issues are all merged or closed (add `--repo <owner/repo>` for bare numbers),
+   unless a named commit sits outside a `--checkout`'s default branch,
+   and "re-check due" lists `recheck:` dates that are past or within a week.
+   Look at each before reporting it as done or still waiting.
+   It also prints `unanswered offers: N`, the number of offer IDs ("Offer
+   ABC-12") on open ledger lines that no line records as answered, dropped or
+   superseded, and warns at three. Plans that number offers without an ID are
+   not counted.
+   When the plan's header has a `Project: <name>` line, it also warns when that
+   project's last `hr-forgotten-work-audit` record is missing or over 30 days
+   old; offer the audit then.
    Report each floor item, or state that the floor is empty. While any floor
    item remains, do not say that nothing is left or that nothing needs the
-   user; re-present the unanswered questions as an offer instead. When asked
+   user; re-present the unanswered questions and ask the undecided items (step 6). When three
+   or more offers from this conversation are open and unanswered, do not
+   re-present them one by one: start a walk-through over them. When asked
    for all current and past items, review the available session transcript,
    relevant plans, task lists, handoffs and linked follow-ups. Name source
    ranges and missing, inaccessible or truncated records. Sweep other
    sessions' records only within the requested project and scope.
 2. Trace requests, unanswered questions, commitments, offered alternatives
-   and findings to their latest disposition. Reconcile duplicate, superseded
+   and findings to what was last decided or done about them. Reconcile duplicate, superseded
    and stale rows with completion or replacement evidence. Keep owners,
    deferred triggers and other sessions' context visible. An old task
    description alone does not establish current activity or ownership.
 3. Preserve the latest selected scope and valid unanswered offer in the
-   durable ledger. Distinguish done, authorized unfinished, unselected,
+   durable ledger. Distinguish done, authorized unfinished, awaiting selection, dropped,
    blocked, deferred and other-owner items. A completed implementation does
-   not complete required checks or landing; deferral does not mean done.
+   not complete required checks or landing; deferral does not mean done. A
+   deferral is not a yes or no: an item deferred with only the user's selection
+   as its trigger is undecided, so it sorts under needs your decision.
+   Sort every open item by what it waits on: **actionable now** (this session
+   can advance it under existing authority), **needs your decision** (a
+   selection or answer only the user can give) or **waiting on others** (an
+   external release, issue or pull request, another project or owner, a date,
+   or an app that retires it). Keep each waiting item's trigger and owner. A
+   waiting item stays in the ledger and in the report with its trigger, but it
+   is not work this session can do yet: do not recommend it as a next step
+   before its trigger fires.
 4. Rank remaining items toward the current goal and explicit priorities.
    Explain the objective and weigh expected impact, next-decision value,
    urgency, dependencies, effort and evidence confidence. Keep priority,
@@ -47,15 +77,75 @@ completed state before the completion message; a report alone does not do so.
    For a full audit, put the full individual table in a durable report
    and link it beside the immediate decisions. Answer whether items are
    accounted for separately from whether selected work is complete.
+   Where the user's rules have a backlog view (§ Backlog view, an optional
+   rule), show it beside the table whenever any item remains, in the format that
+   rule gives. Without one, the table alone is the report. The offer itself
+   follows the offer rules, which make an offer visual only when the user asks
+   for one.
 6. Continue work that can advance under existing authorization. Ask only for
-   unresolved choices using the governing offer format. Preserve schedules
+   unresolved choices using the governing offer format. Invoking this skill is
+   asking for the backlog (§ Session purpose), so present every needs-your-decision
+   item as an offer, or as a walk-through when three or more questions are open,
+   instead of only counting it. Record each answer as yes, no
+   (dropped) or defer with a trigger other than the user's selection, so the
+   item is not asked again on every run. A no is dropped, even when it names
+   what would make the user reconsider. Defer only work the user wants done later. Items waiting on others stay listed
+   with their trigger and are not asked. Preserve schedules
    and ownership; this audit grants no authority to start, transfer, publish
    or clean up work merely because it appears in the inventory.
 
+## Walk-through
+
+When the user asks to go through the backlog item by item, or three or more
+offers are open and unanswered, run it in groups:
+
+1. Rank and save the report as above. Where the user's rules have a backlog
+   view (§ Backlog view), show it for the whole ranked backlog with the
+   current group marked and placed last among the decisions. The decisions
+   stay in the text offer. When
+   stacked offers start the walk-through, mark each superseded in the ledger,
+   keep its option text, and queue its questions as groups.
+2. Put items in one group when one answer can cover them: the same owner, the
+   same action or one dependency. Ask one group per reply, one numbered
+   question per item with one combined acceptance line. Ask first the group
+   whose answers change or unblock the others, then one with a date, then the
+   rest; a decision whose prerequisite is still open waits for a later group.
+   Say how many groups remain and name the next.
+3. Before asking a group, look up what one read-only call can answer (why a
+   run failed, whether a setting already exists) and show the finding beside
+   the question. Ask the user only the decision.
+4. Record each answer in the ledger before acting, then close that group's
+   offer. Show the backlog view again, when there is one, with the next group
+   marked before asking it.
+   `go` selects the recommendation in the latest open group only. A result or
+   handoff that brings its own offer while the queue is open joins the queue
+   with one line; it does not become another standalone offer.
+5. Stop when no decision remains that the user can make now. Record each
+   leftover with the condition that would reopen it. Say what closed in the
+   text, and show the backlog view, when there is one, with what still waits;
+   the view lists open items only.
+
 For a full audit, save a mapping from reviewed source records to items or
-reviewed context-only dispositions. If `hr-handoff` and its reconciliation
+reviewed records kept only as context. When the report rebuilds a ledger or
+inventory from an earlier one, treat the earlier one as a source. Carry each of
+its open or deferred lines over as an item, marked done with its outcome when it
+has closed. Several lines may share one item only when the same next action
+and completion evidence satisfy every line. A summary row such as "the rest,
+reopen only if asked" loses those lines. If `hr-handoff` and its reconciliation
 resources are available, reuse its `references/reconciliation.md` procedure
 and `scripts/check-reconciliation.mjs` checker. Otherwise retain the mapping
 and coverage gaps without claiming a mechanical check. A passing checker
 accounts for supplied records; it does not prove every promise was understood
 or that unavailable history contains no other work.
+
+## Machine reconciliation
+
+For a host that checks the reply boundary, add `--json --session <id> --turn <id>`
+to the existing floor command. It emits a bound `reconciliation` receipt alongside
+the usual report. An invalid plan exits `1`, even when displayed groups are empty.
+Exit `2` reports open work or findings and does not classify readiness or authority.
+
+The house-rules repository's `evals/end-of-reply/README.md`, Adapter migration,
+defines version-2 records, exact item coverage and adapter migration. The floor
+only supplies snapshot identities; the producer must explicitly classify each
+item. Source availability does not establish host enforcement.

package/skills/hr-what-next/references/reporting.md

@@ -6,26 +6,20 @@ for actions the user must perform.
 
 During long work, give frequent useful progress updates with completed evidence,
 the current action and what remains. Show clock-time forecasts in the user's
-local timezone. Use the timezone provided by the user or session environment;
-ask if neither establishes it.
+local timezone. Use the timezone provided by the user or session environment,
+including the host clock zone (`date +%Z`, or `Get-TimeZone` on Windows). Check
+it before reporting UTC or saying the zone is unknown; ask if neither
+establishes it.
 
-Use a visual when it makes a change, behavior or decision clearer; keep a short
-text explanation beside it. For visible interface changes, prefer actual
-before/after captures with comparable content, viewport and state when available.
-Label mockups and simulated behavior as illustrations, not verification. Use
-interaction when exploring states or alternatives helps the reader, and provide
-an accessible text or static equivalent. Use the host's available tools within
-existing browser and task authorization.
+For routine replies, aim for at most five items per list or group. Rank the
+items by relevance to the current task and retain undisplayed candidates in
+the ledger. When the user requests a full inventory, or needs more items to
+make a decision, show every relevant item. This presentation target does not
+limit investigation, required disclosures or the options required by § Offers.
 
-Use a Markdown table when comparing items on common criteria or reporting
-repeated records with useful shared fields. When asked about benefits,
-tradeoffs or how a proposal differs from current behavior, use a compact
-table for multiple items. Explain one item per row. For changes, show current
-and proposed behavior and why the difference matters. Include relevant
-tradeoffs and evidence or uncertainty; label unknowns rather than inventing
-gains. Keep columns consistent and cells short. Label missing or unverified values and put units in headings. Put
-explanations and caveats beside the table. Split wide tables or use lists when
-long cells obscure the comparison. Preserve § Offers and any enabled offer format.
+Use a visual when it makes a change or decision clearer, with a short text explanation beside it. For interface changes prefer real before/after captures with comparable content, viewport and state; label mockups as illustrations. Give an interactive visual a text or static equivalent.
+
+Use a Markdown table to compare items on shared criteria: one item per row, short cells, units in headings. For proposed changes, show current behavior, proposed behavior and why it matters. Label unknown or unverified values instead of inventing gains, and put caveats beside the table. Numeric before/after tables get a benefit column (percent or times; absolute when a ratio cannot be computed); label changes inside the noise band "no clear change". Keep any enabled offer format.
 
 When asked for a backlog, research list or remaining work, check the current
 session and relevant task records within the requested scope. Reconcile
@@ -50,10 +44,7 @@ Label expected gains and unknowns; do not invent measurements or scores.
 Keep priority separate from readiness, and preserve § Finishing work's
 requirements for continuing authorized work and making offers.
 
-Put the answer, and anything the user must read or act on, in the reply's text
-after its last tool call. Text written between tool calls can be collapsed or
-lost. When the reply ends with a question card, that text goes after every
-other tool call, right before the card.
+Put the answer and anything the user must act on in the text after the reply's last tool call; some hosts hide earlier text behind a summary row. Finish bookkeeping first. If a tool call must follow the answer, repeat the whole answer after it, with any closing lines the rules ask for (such as the parked-item note), unless that call is a question-card tool call. When the reply ends with a question-card tool call, that text goes right before the card.
 
 Verify work with completed checks and their output. Confirm each check's exit status or final
 result before claiming a pass, and do not hide failures by filtering output. Report changes,