neo-agent-skills 0.1.48 → 0.1.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,93 +1,90 @@
1
- # Reviewer-Instrument Audit
1
+ # Instrument Audit (Author & Reviewer)
2
2
 
3
- Two failure shapes that every other review dimension is blind to, because both produce **green code and confidently-worded findings**. Premise, placement, correctness and evidence all check the *patch*; these check the **instrument** — the gate the patch relies on, and the search the reviewer relies on.
3
+ Three failure shapes every other authoring and review dimension is blind to, because all three produce **green code and confidently-worded claims**. Premise, placement, correctness, and evidence check the *patch*; these check the **instrument** — the count or search the **author** relies on to justify a ticket/PR, the gate the **patch** relies on at runtime, and the search the **reviewer** relies on to assert an absence.
4
4
 
5
- Load this when the diff adds a capability gate, constant guard, feature flag, or a new field/config leaf; or when a review is about to assert that something is absent.
5
+ - **Author (`ticket-create` / `pull-request`):** load when a ticket or PR makes a **load-bearing population count or absence claim** justifying premise, scope, or acceptance.
6
+ - **Reviewer (`pr-review`):** load when the diff adds a capability gate, constant guard, feature flag, or new field/config leaf; or when a review asserts an absence or audits an author's count.
6
7
 
7
8
  ---
8
9
 
9
- ## Shape 1 — a gate that checks a capability EXISTS rather than that it RAN
10
+ ## Author Side — load-bearing counts and absence claims carry publish-safe receipts
10
11
 
11
- The question no dimension asks:
12
+ ### 1. Role-triggered, never number-shaped
12
13
 
13
- > **Does satisfying this gate cause anything to happen, or does it merely describe something?**
14
+ Fires **only** on **load-bearing population counts and absence claims used to justify premise, scope, or acceptance** (e.g., *"19 call sites remain"*, *"zero callers outside X"*, *"15 dock-chrome blocks duplicate Y"*, *"loaded payloads shrank by 241 B"*). The claim's **role** triggers the rule, never its numeric appearance.
14
15
 
15
- A gate written as `typeof PRODUCER !== 'function'` is satisfied by `() => {}`. A gate written as a shape check over a caller-supplied object is satisfied by a correctly-shaped object. In both cases the guard passes, the tests pass, and the thing the guard exists to guarantee never happened. **Type-checking a producer is not invoking it.** Validating a receipt's shape is not obtaining the receipt.
16
+ Error classes caught at counting time: `lines ≠ occurrences` (two calls on one line, or one call across three) · `matches ≠ population` (comments, archived ticket prose, or symbol/app names match alongside code) · `pattern ≠ concept` (narrow tokens undercount; broad regexes match `.429` ms fragments as HTTP 429s) · `unnamed tree` (`"148 vs 150"` — both right on different refs; a count is a claim about a ref, not a repository) · `structure invisible to line tools` (raw `grep` misses multi-line YAML `run:` blocks).
16
17
 
17
- Applied to a diff, in order of how often each has bitten:
18
+ ### 2. Publish-safe instrument receipt shape
18
19
 
19
- 1. **Is the guarded thing ever invoked?** Follow the gate to the code behind it. If the gate opens and nothing runs, the gate is decoration.
20
- 2. **Who owns the observation?** If the value the gate protects arrives as a *caller argument*, the caller can assert it. The honest shape is: the consumer invokes the producer and owns what it observes.
21
- 3. **For a newly declared field or config leaf — does a WRITER exist in production code?** A field that is declared, read, and tested still does nothing if only a spec ever assigns it. A test that hand-injects the value witnesses the pass-through and reads as evidence of wiring; it is evidence of the read path only.
20
+ A qualifying claim carries: (1) **Producer** (command, MCP tool, or query class — normalized, never a raw terminal dump), (2) **Exact tree/ref or external source** (commit SHA, `origin/dev` at `<sha>`, or live API surface), (3) **Scope / filter** (path, tenant, or exclusions), and (4) **Sampled match or positive control** (a representative hit for counts, or a stage-matched positive control for `0` / absence claims per Shape 2).
21
+
22
+ - **Linked-receipt rule:** When a linked CI run or API receipt already carries producer + source + scope, link it in place of inline fields — **never duplicate it inline**.
23
+ - **Forbidden-content boundary (`ticket-create` §12):** Publish-safety outranks receipt literalism — name the instrument, never the operator's machine. **Explicitly forbidden in any public receipt:** **secrets, private identifiers, machine-local paths, and client context**.
22
24
 
23
- ### The converse, which is equally a defect
25
+ ### 3. Worked negative examples (do NOT fire)
24
26
 
25
- > **If I am about to claim nothing invokes this — have I found the real caller?**
27
+ - **Routine workflow attestations:** `"Live latest-open sweep: checked latest 20 open issues at 2026-08-22T00:35Z; no equivalent found"` — a fixed gate receipt, not a population premise.
28
+ - **CI-linked test totals:** `"26/26 green"` or `"4,115 passed"` backed by PR CI or a linked test run — producer, tree, and scope already live in the CI receipt.
29
+ - **Non-argument numbers:** dates, timestamps, versions, issue/PR IDs, and enumerations whose producer is already named in the surrounding table or heading.
26
30
 
27
- A reviewer asserting a gate is forgeable is making an absence claim, and it is subject to Shape 2 below. The honest caller may be one layer above the module under review, in a wrapper the module's own error text names.
31
+ ### Worked author failure (`neomjs/neo#17532` RA-4)
32
+
33
+ In `neomjs/neo#17532`, a load-bearing budget-offset claim (`55,409 → 55,152 B`) was reported twice in one night without naming the merge-base vs head objects, causing two unnamed-tree receipt errors (`RA-4`) before being anchored to exact Git objects (`d959598a5b`: `21,962 + 33,447 = 55,409` → `30c5cbb5e5`: `21,991 + 33,177 = 55,168`, `−241 B`).
28
34
 
29
35
  ---
30
36
 
31
- ## Shape 2 — an absence claim from a search with no positive control
37
+ ## Shape 1 — a gate that checks a capability EXISTS rather than that it RAN
32
38
 
33
- > **"No caller." "Nothing references it." "Not used anywhere."**
39
+ > **Does satisfying this gate cause anything to happen, or does it merely describe something?**
40
+
41
+ `typeof PRODUCER !== 'function'` is satisfied by `() => {}`; a shape check over a caller-supplied object is satisfied by any matching mock. Both pass while the guarded action never ran. **Type-checking a producer is not invoking it.**
34
42
 
35
- Every one of these is a claim about what a *command* returned, not about what exists. An empty result has two explanations — the thing is absent, or the search could not have found it — and they are indistinguishable from the output alone.
43
+ 1. **Is the guarded thing ever invoked?** Follow the gate to the code behind it. If the gate opens and nothing runs, the gate is decoration.
44
+ 2. **Who owns the observation?** If the protected value arrives as a *caller argument*, the caller can assert it. The consumer must invoke the producer and own what it observes.
45
+ 3. **For a newly declared field or config leaf — does a WRITER exist in production code?** A field declared, read, and spec-injected still does nothing if no production code assigns it; hand-injected specs witness the read path only.
36
46
 
37
- Two rules, both cheap:
47
+ **The converse (equally a defect):** *If I am about to claim nothing invokes this — have I found the real caller?* Asserting a gate is forgeable is an absence claim subject to Shape 2; the caller may sit one layer up in a wrapper the module's error text names.
38
48
 
39
- 1. **Carry a positive control that shares the target's blind spot.** The same command must also find something you know is present — and the control must traverse **every stage capable of excluding the target**: the same matcher, the same ref, the same path scope, the same downstream filters. A control that survives a stage the target dies at proves nothing.
49
+ ---
50
+
51
+ ## Shape 2 — an absence claim from a search with no positive control (Author & Reviewer)
52
+
53
+ > **"No caller." "Nothing references it." "Not used anywhere."**
40
54
 
41
- This is the rule's own Shape-1 trap, and it is easy to write the weak version. "A control exists" is a *declaration*; "a control runs the failing path" is an *execution*. Worked counterexample — names the reviewed SHA, carries a known-present control, and still publishes a false absence:
55
+ An empty result has two indistinguishable explanations: the target is absent, or the search could not find it.
56
+
57
+ 1. **Carry a positive control that shares the target's blind spot.** The same command must find something known-present and traverse **every stage capable of excluding the target** (matcher, ref, path scope, downstream filters). "A control exists" is a declaration; "a control runs the failing path" is an execution. Counterexample — names the SHA, carries a control, and still publishes a false absence because `name: pr-review` survives `grep -v` while the target dies at it:
42
58
 
43
59
  ```sh
44
60
  git grep -n -E '<target>|name: pr-review' <sha> -- .agents/skills/pr-review \
45
61
  | grep -v 'reviewer-instrument-audit.md'
46
62
  ```
47
63
 
48
- The generic control (`name: pr-review`) survives the `grep -v`; the target does not. Both rules as naively written are satisfied — control present, SHA stated — while the finding is false. Where one control cannot cover every stage, place a control **at each** failure-prone stage.
49
- 2. **State the tree.** A review asserting an absence must name the **branch or SHA** it searched. A local checkout is not the PR; `git grep` on `dev` cannot see a branch's code, and it exits 0 with empty output while doing so.
50
-
51
- ### Worked failure
52
-
53
- `git grep <name>` run against a **local checkout still on `dev`**, proving an absence against a tree that structurally could not contain the branch's code. `git grep` exits 0 with empty output while doing it, so the result is indistinguishable from a genuine absence.
54
-
55
- A stage-matched control kills it instantly: the control is missing too, because the wrong tree contains neither.
64
+ Where one control cannot cover every stage, place a control **at each** failure-prone stage.
65
+ 2. **State the tree.** Any absence claim (ticket, PR, or review) must name the **branch or SHA** searched. `git grep` on local `dev` cannot see a branch's code and exits 0 with empty output; a stage-matched control kills the error because the control is missing too.
56
66
 
57
- **A caution the same review earned.** A second reviewer reached the *same* false absence on the same module and published a `grep -v` as the cause. An exact-object probe at the cited head later showed the filter did **not** remove the proving line — so the finding was false but the stated mechanism was never established. Diagnosing your own broken search is itself a claim, and it is subject to this section: an unverified account of *why* a search failed is not evidence, and it propagates faster than the finding because it sounds like a lesson.
67
+ **Caution:** A second reviewer reached the same false absence and blamed `grep -v`; an exact-object probe at the cited head showed the filter did **not** remove the proving line. Diagnosing a broken search is itself a claim subject to this audit.
58
68
 
59
69
  ---
60
70
 
61
- ## Empirical anchor — four events, one day, three PRs, two reviewers
71
+ ## Empirical anchors
62
72
 
63
- Each row verified against its exact Git object, not against the review text that reported it. An earlier draft of this table carried five rows and two wrong coordinates, both lifted from peer review prose — which is the failure this file exists to prevent, committed by this file.
73
+ - **Author-side six-case series (`neomjs/neo-agent-skills#12`):** six cross-family incidents (2026-05..2026-08), culminating in the Drop+Supersede of `neomjs/neo#17513` → `#17534` (where `"19 call sites"` was a grep line count including archived ticket prose and a two-call line), showed that catching broken counting instruments only at review manufactures avoidable RC/D+S rounds.
74
+ - **Reviewer-side four-event series (one day, three PRs, two reviewers, verified at exact Git objects):**
64
75
 
65
76
  | # | event | verified at | shape |
66
77
  |---|---|---|---|
67
- | 1 | Gate written `typeof PROMOTION_REPLAY_PRODUCER !== 'function'`; a no-op satisfied it (#16037) | `de2b17d614` | 1 |
68
- | 2 | `daemonState` / `daemonDegradedReason` declared and read in production, **assigned nowhere**; the unit spec injects them (#16050, Drop+Supersede) | `c3d28ca76d` | 1 |
69
- | 3 | Reviewer asserted a gate forgeable while the producer *was* invoked one layer up (#16053) | `6f8406178c` | 1-converse |
70
- | 4 | `git grep` over a local checkout still on `dev` — an absence proven against a tree that could not contain the code (#16053) | `6f8406178c` | 2 |
71
-
72
- Events 3 and 4 are **reviewer** error rather than author error, and they are the same false conclusion reached independently by two reviewers on one module — which is what moved this from a personal lesson into substrate.
73
-
74
- **Why four and not five.** A fifth row claimed a `grep -v` had deleted the proving line. An exact-object probe at the cited head returned that line intact, so the finding was real but its published cause was not. A false finding plus a *claimed* explanation is **one event**, not two; counting the explanation separately would have inflated the ledger with the very kind of unverified account the rest of this file rejects.
75
-
76
- ---
77
-
78
- ## Why the asymmetry makes these worth a slot
79
-
80
- A detection failure announces itself: something escapes and someone eventually notices. A **permission** failure announces nothing — the gate opens, the suite is green, and the green then reads as evidence the thing was checked and approved. Same for an absence claim: a wrong finding is loud and gets retracted, while a wrong *exemption* is silent forever.
81
-
82
- Both shapes here sit on the silent side. That is the entire argument for a checklist entry rather than reviewer memory: the failure mode produces no signal to remember it by.
83
-
84
- ---
78
+ | 1 | Gate `typeof PROMOTION_REPLAY_PRODUCER !== 'function'` satisfied by no-op (`#16037`) | `de2b17d614` | 1 |
79
+ | 2 | `daemonState` / `daemonDegradedReason` read in prod, **assigned nowhere**; spec injects (`#16050`, D+S) | `c3d28ca76d` | 1 |
80
+ | 3 | Reviewer asserted gate forgeable while producer *was* invoked one layer up (`#16053`) | `6f8406178c` | 1-converse |
81
+ | 4 | `git grep` on local `dev` checkout — absence proven against wrong tree (`#16053`) | `6f8406178c` | 2 |
85
82
 
86
- ## Net-load accounting
83
+ *(A fifth claimed row blaming `grep -v` was excluded after an exact-object probe returned the proving line intact.)*
87
84
 
88
- Per `AGENTS.md §self_evolving_systems`, substrate additions state their cost.
85
+ ## Why the asymmetry makes these worth a slot & Net-load accounting
89
86
 
90
- - **Always-loaded cost:** `SKILL.md` 1673 → 2068 bytes, **+395**, measured not estimated. The Map gains a pointer, not a rule.
91
- - **Conditional cost:** this file, loaded only when a review meets the trigger — a gate/flag/field in the diff, or an absence claim in the review.
92
- - **Justification:** four exact-object-verified events in one day across three PRs and two reviewers, independently flagged `[TOOLING_GAP]` by both with the same wording. The slot is justified by recurrence, not by novelty.
93
- - **Retirement trigger:** if a mechanical check ever lands that fails a review body asserting an absence without a named tree/SHA, the Shape-2 half retires into that check and this file shrinks to Shape 1 alone.
87
+ A detection failure announces itself; a **permission** or **counting-instrument** failure is silent — the count reads as authority, the gate opens, CI is green, and the error surfaces only after build and review cost are paid.
88
+ - **Always-loaded cost:** `SKILL.md` routers untouched (`0 B` delta); `ticket-create-workflow.md` carries a one-line `compress-to-trigger` pointer paid in-file (`<= 0 B` net).
89
+ - **Conditional cost:** loaded only when an author makes a load-bearing count/absence claim or a reviewer audits a gate/absence/count.
90
+ - **Retirement trigger:** if a lint fails absence claims lacking a named tree/SHA, Shape 2 retires into that check.
@@ -17,7 +17,7 @@ A ticket that calls an existing behavior wrong carries its `Design authority:` l
17
17
  ### 1a. The Content Sweep (Duplicate Detection)
18
18
  Verify no equivalent ticket already exists. Redundant tickets pollute the Knowledge Base.
19
19
 
20
- Duplicates hide in **two substrates**, and you MUST sweep **both as the LAST step immediately before `create_issue`** — not at turn-start, not when you begin drafting. A sweep run before authoring goes stale while you write the Fat Ticket: in a thundering herd (multiple agents booting on the same prompt), a peer's ticket can land in the minutes between your sweep and your create call. The turn-start mailbox check (`§mailbox_check_protocol`) is for general coordination — it is **not** the dup gate.
20
+ Duplicates hide in **two substrates**; sweep **both as the LAST step immediately before `create_issue`** — never at turn-start or before drafting. A pre-draft sweep goes stale while you write the Fat Ticket: in a thundering herd, a peer's ticket can land between your sweep and your `create_issue` call. The turn-start mailbox check (`§mailbox_check_protocol`) is for general coordination, **not** the dup gate.
21
21
 
22
22
  **(i) GitHub live freshness sweep (mandatory) — catches already-FILED duplicates:** read at least the latest 20 open GitHub issues from the live tracker, including issue number, title, author, labels, and URL.
23
23
 
@@ -46,6 +46,7 @@ list_messages({ status: 'all', limit: 30 }) // ALL read-states — recency is t
46
46
  **(v) Epic-layer sweep (epic-labeled filings only, mandatory):** both artifact axes are blind to an outcome authority — the payload says why. Read every open `label:epic` issue's `Terminal predicate:` line, then body-read only what an outcome-overlap query ranks, and attest beside `(i)`.
47
47
 
48
48
  <!-- trigger: filing a ticket, filing an EPIC, or a defect found while measuring something else -> read ./decision-substrate-sweeps.md (query shape, the epic sweep, attestation lines, same-turn porting, the #17997 / #12856 anchors) -->
49
+ <!-- trigger: load-bearing population count or absence claim justifying premise, scope, or acceptance -> read ../../pr-review/references/reviewer-instrument-audit.md (role-triggered publish-safe instrument receipt; routine receipts and CI totals exempt) -->
49
50
 
50
51
  Semantic sweep: `ask_knowledge_base(query='...', type='ticket')` — surfaces conceptual duplicates that title scanning misses; its rows come from the `github-content-sync` tenant.
51
52
  Exact/historical sweep: `query_documents` (issues, archived issues, discussions) or a live `gh search issues --owner neomjs "<keyword>"`.
@@ -102,7 +103,7 @@ Apply at creation time — not just at intake. Every stage must pass before the
102
103
  2. **Prescription** — is the stated fix the right substrate for the problem, or does it treat a symptom? Could a different layer (config, service, daemon, schema) solve it better?
103
104
  **Verify-Before-Assert Integration:** Before making architectural claims or prescribing solutions in your Fat Ticket body (Stage 2 Prescription), you MUST apply the **Verify-Before-Assert Pre-Flight Check** (`AGENTS.md` §verify_before_assert). You cannot assert that a bug exists or a pattern is flawed without empirical confirmation (a falsifying tool call) prior to filing the ticket.
104
105
  3. **Substrate** — where does this work belong? Service layer? Build script? CI workflow? Framework core? Documentation? Match the fix to the substrate that owns the concern.
105
- **Structural Pre-Flight Integration:** when the prescription introduces or relocates a `.mjs` file, the directory choice MUST be validated via `.agents/skills/structural-pre-flight/` before drafting the ticket body. Stage 0 mechanical trigger fires; Stage 1 fast-path handles sibling-pattern matches in 30 seconds; novel directory choices route through full Pre-Flight (ArchitectureOverview.md + ADR consultation). The empirical anchors PR `#11008` (`orchestrator-daemon.mjs` misplaced in `ai/scripts/`) and earlier `ai/daemons/wake/daemon.mjs` (originally misplaced in `ai/scripts/` as `bridge-daemon.mjs`) demonstrate the cost of skipping this check at ticket-creation time.
106
+ **Structural Pre-Flight Integration:** when the prescription introduces or relocates a `.mjs` file, validate the directory choice via `.agents/skills/structural-pre-flight/` before drafting the ticket body (Stage 0 mechanical trigger; Stage 1 30s sibling-match fast-path; full Pre-Flight for novel directory choices; anchors: PR `#11008` `orchestrator-daemon.mjs`, `ai/daemons/wake/daemon.mjs`).
106
107
  4. **Consumer** — who reads the output of this change? Human developer, agent, Memory Core, Native Edge Graph, Knowledge Base? Different consumers need different shapes (markdown prose vs structured metadata vs MCP payload).
107
108
  5. **Service-Boundary** — does the fix cross a service boundary it shouldn't? Config added to the wrong owning service creates future migration debt.
108
109
  6. **Decision Record impact** — for architecture/substrate tickets, declare whether the work is `none`, `aligned-with`, `depends-on`, `amends`, `supersedes`, or `challenges` an ADR. If it challenges or supersedes an accepted ADR, apply the ADR successor-risk audit in [`../../ticket-intake/references/adr-successor-risk-audit.md`](../../ticket-intake/references/adr-successor-risk-audit.md) before filing.
@@ -139,16 +140,16 @@ Skeleton tickets are forbidden — so are world atlases: sections complete, each
139
140
  - **The Problem** — deep background, insights from recent Memory Core explorations, reproducer if applicable. Historical "why" for the agent picking up the ticket later.
140
141
  - **The Architectural Reality** — exactly which Neo.mjs patterns, class topologies, or service boundaries this issue interacts with. Cite file:line when known. Distinguishes intent-level framing (Problem) from structural specificity (Reality).
141
142
  - **The Fix** — concrete prescription: files, symbols, architectural primitives touched. What changes, and where.
142
- - **Contract Ledger Matrix** *(when applicable)* — For any ticket introducing, modifying, or deprecating a surface consumed by humans, agents, or external systems (e.g. public methods, configs, MCP tools), you MUST include a formal Contract Ledger matrix. This matrix defines Target Surface, Source of Authority, Proposed Behavior, Fallback, Docs, and Evidence. Rows that name existing fields, methods, helpers, tools, config keys, docs paths, or runtime surfaces must satisfy the row-level Surface-Anchor V-B-A discipline in the [Contract Ledger protocol](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/process/contract-ledger.md) before the ticket asserts them.
143
+ - **Contract Ledger Matrix** *(when applicable)* — For any ticket introducing, modifying, or deprecating a surface consumed by humans, agents, or external systems (public methods, configs, MCP tools), include a formal Contract Ledger matrix (Target Surface, Source of Authority, Proposed Behavior, Fallback, Docs, Evidence). Rows naming existing surfaces must satisfy the row-level Surface-Anchor V-B-A discipline in the [Contract Ledger protocol](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/process/contract-ledger.md) before the ticket asserts them.
143
144
  - **Decision Record impact** *(architecture/substrate tickets)* — the §2 step-6 declaration (`none` … `challenges ADR ####`).
144
- - **Decision Record** *(Discussion-origin tickets)* — Preserve the source Discussion's ADR classification when present: `Not needed`, `Optional: <ADR/ticket/discussion anchor>`, or `Required: ADR #### / PR #N / ticket #N`. This is distinct from `Decision Record impact`: the classification records the Discussion graduation's authority target; the impact line records what this ticket itself does to ADR authority.
145
- - **Discussion Criteria Mapping** *(when graduating from a Discussion)* — A section mapping the upstream Discussion's `[RESOLVED_TO_AC]` criteria to this Epic's ACs. See `ideation-sandbox-workflow.md §6.6` for the required format. This satisfies the `epic-resolution` Closeout Gates upfront.
146
- - **Acceptance Criteria** — bulleted checklist. Each item independently verifiable. Post-merge-only items explicitly flagged. **Epic exception:** for `epic`-labeled tickets, ACs live in the **SUB** tickets (not the epic body) — author the epic per `epic-create` (epic body = problem-scope + intended-solution; subs linked via `update_issue_relationship`, each a one-PR-deliverable leaf). See `.agents/skills/epic-create/`.
147
- - **Out of Scope** — what this ticket deliberately does NOT do. Prevents scope creep during implementation.
148
- - **Avoided Traps** / **Gold Standards Rejected** *(when applicable)* — alternatives considered and rejected, with rationale. Especially critical when rejecting a generic industry/LLM "best practice" (e.g. standard React patterns, generic node workflows) that is a trap in Neo.mjs's multi-threaded architecture.
145
+ - **Decision Record** *(Discussion-origin tickets)* — Preserve the source Discussion's ADR classification when present: `Not needed`, `Optional: <ADR/ticket/discussion anchor>`, or `Required: ADR #### / PR #N / ticket #N` (records the graduation's authority target; `Decision Record impact` records what this ticket itself does to ADR authority).
146
+ - **Discussion Criteria Mapping** *(when graduating from a Discussion)* — Maps the upstream Discussion's `[RESOLVED_TO_AC]` criteria to this Epic's ACs (`ideation-sandbox-workflow.md §6.6`), satisfying `epic-resolution` Closeout Gates upfront.
147
+ - **Acceptance Criteria** — bulleted checklist; each item independently verifiable, post-merge-only items flagged. **Epic exception:** for `epic`-labeled tickets, ACs live in the **SUB** tickets (author per `.agents/skills/epic-create/`: problem-scope + intended-solution; subs linked via `update_issue_relationship`, each one-PR-deliverable).
148
+ - **Out of Scope** — what this ticket deliberately does NOT do.
149
+ - **Avoided Traps** / **Gold Standards Rejected** *(when applicable)* — alternatives considered and rejected with rationale (especially generic LLM/React patterns that fail in Neo.mjs's multi-threaded architecture).
149
150
  - **Related** — sibling tickets, superseded tickets, dependencies, PRs.
150
151
  - **Origin Session ID** — `Origin Session ID: <uuid>` on its own line near the end of the body; optional but highly recommended for genuinely single-session tickets.
151
- - **Handoff Retrieval Hints** — Semantic query patterns (`query_raw_memories`, `query_summaries`) or exact Git commit-range anchors to assist subsequent agents in resuming the workstream across fragmented session IDs post-restart. **REQUIRED for architecturally substantive tickets or multi-session workflows.** Example: `Retrieval Hint: "cross-harness MCP singleton cache divergence"` or `Retrieval Hint: Commit SHA 1234abcd..5678efgh`.
152
+ - **Handoff Retrieval Hints** — Semantic query patterns (`query_raw_memories`, `query_summaries`) or exact commit-range anchors (**REQUIRED** for architecturally substantive or multi-session tickets; e.g. `Retrieval Hint: "cross-harness MCP singleton cache divergence"`).
152
153
 
153
154
  ### 5.1 Reference Hygiene: Backtick-Escape for Descriptive `#N`
154
155
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "neo-agent-skills",
3
- "version": "0.1.48",
3
+ "version": "0.1.49",
4
4
  "description": "Install the workflow substrate a cross-model AI team actually runs on: ticket intake, PR review gates, lane coordination and guards, versioned as a package. The skills Neo.mjs maintainers load every session — materialized into your repo, not copied.",
5
5
  "type": "module",
6
6
  "license": "MIT",