neo-agent-skills 0.1.53 → 0.1.55
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.
- package/.agents/skills/blog-post/references/blog-authoring-guide.md +1 -1
- package/.agents/skills/document-references.v1.json +67 -2
- package/.agents/skills/epic-create/references/epic-create-workflow.md +1 -0
- package/.agents/skills/guide-authoring/references/guide-authoring-bar.md +20 -0
- package/.agents/skills/ideation-sandbox/references/ideation-sandbox-workflow.md +4 -5
- package/.agents/skills/industry-friction-radar/references/industry-friction-radar-workflow.md +1 -1
- package/.agents/skills/lane-intent/references/lane-intent-protocol.md +3 -3
- package/.agents/skills/neo-identity-update/references/affected-areas-map.md +2 -2
- package/.agents/skills/neo-identity-update/references/facts-ledger.md +1 -1
- package/.agents/skills/neo-identity-update/references/framing-governance.md +6 -6
- package/.agents/skills/neo-identity-update/references/update-protocol.md +2 -2
- package/.agents/skills/structural-pre-flight/references/structural-pre-flight-workflow.md +9 -9
- package/.agents/skills/tech-debt-radar/references/tech-debt-radar-guide.md +1 -1
- package/.agents/skills/ticket-create/references/decision-substrate-sweeps.md +19 -31
- package/.agents/skills/ticket-create/references/ticket-create-workflow.md +3 -2
- package/.agents/skills/ticket-intake/references/adr-successor-risk-audit.md +5 -5
- package/.agents/skills/ticket-intake/references/ticket-intake-workflow.md +2 -0
- package/.agents/skills/video-create/references/native-display-capture.md +2 -2
- package/.agents/skills/video-create/references/video-create-workflow.md +1 -1
- package/package.json +1 -1
|
@@ -53,7 +53,7 @@ A public post ships only after **≥2 model reviews**. The cross-family review i
|
|
|
53
53
|
- **Register (manual):** add a year node + leaf to `apps/portal/resources/data/blog.json` (the portal blog-nav). Confirm it parses (`node -e "JSON.parse(require('fs').readFileSync('apps/portal/resources/data/blog.json','utf8'))"`).
|
|
54
54
|
- **Do NOT hand-edit the SEO surfaces.** `apps/portal/sitemap.xml` and `apps/portal/llms.txt` are **generated** by `buildScripts/docs/seo/generate.mjs` (via `buildScripts/docs/rebuildContentIndexesAndSeo.mjs`) and committed by the `.github/workflows/data-sync-pipeline.yml` data-sync pipeline. A manual edit is overwritten on the next pipeline run.
|
|
55
55
|
- **Ship:** commit + PR per the `pull-request` skill; the PR body `Evidence:` line is L1/L2 (docs — no unit tests). Public-artifact gate: **zero client names** (AGENTS.md §critical_gate).
|
|
56
|
-
- **Identity:** byline carries the author's named-maintainer identity + model + the cross-family team framing (
|
|
56
|
+
- **Identity:** byline carries the author's named-maintainer identity + model + the cross-family team framing (`neomjs/neo#adr:neo-identity-source-of-truth-model`).
|
|
57
57
|
|
|
58
58
|
## Empirical Anchor
|
|
59
59
|
|
|
@@ -38,12 +38,50 @@
|
|
|
38
38
|
"load"
|
|
39
39
|
]
|
|
40
40
|
},
|
|
41
|
+
{
|
|
42
|
+
"token": "learn/agentos/decisions/0006-adrs-as-graph-queryable-entities.md",
|
|
43
|
+
"canonicalOwner": "neomjs/neo-agent-brain",
|
|
44
|
+
"resolution": "https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0006-adrs-as-graph-queryable-entities.md",
|
|
45
|
+
"referencingSkills": [
|
|
46
|
+
"guide-authoring",
|
|
47
|
+
"structural-pre-flight",
|
|
48
|
+
"tech-debt-radar",
|
|
49
|
+
"ticket-intake"
|
|
50
|
+
],
|
|
51
|
+
"kinds": [
|
|
52
|
+
"load"
|
|
53
|
+
]
|
|
54
|
+
},
|
|
41
55
|
{
|
|
42
56
|
"token": "learn/agentos/decisions/0008-skill-anatomy-and-authoring-contract.md",
|
|
43
57
|
"canonicalOwner": "neomjs/neo",
|
|
44
58
|
"resolution": "https://github.com/neomjs/neo/blob/dev/learn/agentos/decisions/0008-skill-anatomy-and-authoring-contract.md",
|
|
45
59
|
"referencingSkills": [
|
|
46
|
-
"create-skill"
|
|
60
|
+
"create-skill",
|
|
61
|
+
"guide-authoring",
|
|
62
|
+
"tech-debt-radar"
|
|
63
|
+
],
|
|
64
|
+
"kinds": [
|
|
65
|
+
"load"
|
|
66
|
+
]
|
|
67
|
+
},
|
|
68
|
+
{
|
|
69
|
+
"token": "learn/agentos/decisions/0010-lane-intent-coordination-primitive.md",
|
|
70
|
+
"canonicalOwner": "neomjs/neo-agent-brain",
|
|
71
|
+
"resolution": "https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0010-lane-intent-coordination-primitive.md",
|
|
72
|
+
"referencingSkills": [
|
|
73
|
+
"lane-intent"
|
|
74
|
+
],
|
|
75
|
+
"kinds": [
|
|
76
|
+
"load"
|
|
77
|
+
]
|
|
78
|
+
},
|
|
79
|
+
{
|
|
80
|
+
"token": "learn/agentos/decisions/0012-model-stats-framework.md",
|
|
81
|
+
"canonicalOwner": "neomjs/neo-agent-brain",
|
|
82
|
+
"resolution": "https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0012-model-stats-framework.md",
|
|
83
|
+
"referencingSkills": [
|
|
84
|
+
"neo-identity-update"
|
|
47
85
|
],
|
|
48
86
|
"kinds": [
|
|
49
87
|
"load"
|
|
@@ -54,7 +92,34 @@
|
|
|
54
92
|
"canonicalOwner": "neomjs/neo",
|
|
55
93
|
"resolution": "https://github.com/neomjs/neo/blob/dev/learn/agentos/decisions/0018-neo-identity-source-of-truth-model.md",
|
|
56
94
|
"referencingSkills": [
|
|
57
|
-
"
|
|
95
|
+
"blog-post",
|
|
96
|
+
"neo-identity-update",
|
|
97
|
+
"video-create"
|
|
98
|
+
],
|
|
99
|
+
"kinds": [
|
|
100
|
+
"load"
|
|
101
|
+
]
|
|
102
|
+
},
|
|
103
|
+
{
|
|
104
|
+
"token": "learn/agentos/decisions/0019-aiconfig-reactive-provider-ssot.md",
|
|
105
|
+
"canonicalOwner": "neomjs/neo-agent-brain",
|
|
106
|
+
"resolution": "https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0019-aiconfig-reactive-provider-ssot.md",
|
|
107
|
+
"referencingSkills": [
|
|
108
|
+
"guide-authoring",
|
|
109
|
+
"tech-debt-radar"
|
|
110
|
+
],
|
|
111
|
+
"kinds": [
|
|
112
|
+
"load"
|
|
113
|
+
]
|
|
114
|
+
},
|
|
115
|
+
{
|
|
116
|
+
"token": "learn/agentos/decisions/0029-docking-design.md",
|
|
117
|
+
"canonicalOwner": "neomjs/neo",
|
|
118
|
+
"resolution": "https://github.com/neomjs/neo/blob/dev/learn/agentos/decisions/0029-docking-design.md",
|
|
119
|
+
"referencingSkills": [
|
|
120
|
+
"guide-authoring",
|
|
121
|
+
"industry-friction-radar",
|
|
122
|
+
"video-create"
|
|
58
123
|
],
|
|
59
124
|
"kinds": [
|
|
60
125
|
"load"
|
|
@@ -55,6 +55,7 @@ Each sub the decomposition creates MUST be a **leaf that a single PR can FULLY d
|
|
|
55
55
|
4. **Author the body** = the `Terminal predicate:` line, then problem-scope + intended-solution (+ ledger if graduated). NO ACs, NO sub-list.
|
|
56
56
|
5. **Label `epic`** + apply title hygiene (per `ticket-create`).
|
|
57
57
|
6. **Create subs separately** (via `ticket-create` — each with its own ACs + Contract Ledger) and **link each via `update_issue_relationship`** (parent = the Epic). Add subs incrementally as decomposition clarifies; that governs Epic life. Goal-scoping graduation is stricter: full v1 leaves are filed/native-linked, while the Epic body stays sub-list-free.
|
|
58
|
+
- If this replaces an older plan, apply [same-turn reconciliation](../../ticket-create/references/decision-substrate-sweeps.md#same-turn-reconciliation) after successor IDs exist; preserve or transfer remaining obligations before retiring old work.
|
|
58
59
|
7. **Verify** (pre-flight, before `create_issue`):
|
|
59
60
|
- [ ] Body contains **no** `## Acceptance Criteria` block.
|
|
60
61
|
- [ ] Body contains **no** hardcoded sub-registry (subs discoverable via parent-child relationship instead).
|
|
@@ -58,6 +58,26 @@ Before any APPROVE, re-grade the whole guide — not the delta:
|
|
|
58
58
|
|
|
59
59
|
If any answer is "no", it is `REQUEST_CHANGES` — name the gap against the bar, not a nitpick. An approve that the operator then rejects is worse than no review.
|
|
60
60
|
|
|
61
|
+
## 7. ADR Custody Redirects, Repository-Qualified Identity & Slug Citations — `MACHINE-ENFORCEABLE-CANDIDATE`
|
|
62
|
+
|
|
63
|
+
Architecture Decision Records are owned per repository; [neomjs/neo-agent-brain#adr:adrs-as-graph-queryable-entities](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0006-adrs-as-graph-queryable-entities.md) (`§§2.6–2.11`) is the single schema authority (do not copy its field tables into other skills or routers):
|
|
64
|
+
|
|
65
|
+
- **Slug citations & required context (`§2.7.1`, `§2.11`):**
|
|
66
|
+
- Ordinary citations use `adr:<slug>` only when the current file/issue/PR has evidenced same-forge, same-repository context; `<org>/<repo>#adr:<slug>` when forge context is established; or `<forge>/<org>/<repo>#adr:<slug>` for explicit forge+repository (e.g. `neomjs/neo-agent-brain#adr:aiconfig-reactive-provider-ssot`, `neomjs/neo#adr:skill-anatomy-and-authoring-contract`).
|
|
67
|
+
- **Organization Discussions, Memory Core memories, and A2A messages (`§2.7.1`):** must explicitly qualify `<org>/<repo>#adr:<slug>` (or `<forge>/<org>/<repo>#adr:<slug>` when the origin envelope does not establish the forge). Never infer repository context from the hosting Discussion repo, seat, `cwd`, or `relatedTickets`.
|
|
68
|
+
- **Packaged skills (`.agents/skills/**`):** materialize across multiple repositories with no single destination repo context, so concrete citations in skill payloads must qualify `<org>/<repo>#adr:<slug>` (or `<forge>/<org>/<repo>#adr:<slug>`). Canonical 4-field machine keys (`adr:<E(forge)>:<E(repositoryId)>:<E(namespace)>:<number>`, schema in `§2.6`) remain exact identity references when repository-rename/reuse disambiguation is needed.
|
|
69
|
+
- **Legacy numeric forms (`§2.7.1`):** existing numeric forms (`ADR 0018`, `adr-0006`, `<forge>/<org>/<repo>#adr-NNNN`) remain resolvable legacy references; new prose and skill payloads prefer qualified slug citations, and bare single-repository filenames (`<NNNN>-<slug>.md` outside a canonical URL) are rejected by `lint-skill-corpus`.
|
|
70
|
+
- **Source-local slug & `Aliases` history (`§2.7.2`, `§2.11`):** Current slug is the lowercase ASCII kebab suffix of `NNNN-<slug>.md` (`^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`). On rename, add the former slug to the single canonical two-column `Attribute | Value` table between initial H1 and first H2 (`| **Aliases** | \`old-slug\`, \`former-slug\` |`; normalize legacy opening metadata in the same edit if needed). Fenced, blockquoted, list-nested, or later-section tables reserve nothing; duplicate rows refuse. Normal creation (`1` file edit) and rename (`1` file + `1` `Aliases` row edit in the same file) require **no second manifest or registration action**.
|
|
71
|
+
- **Authoring-floor observation vs admission eligibility (`§2.6`):** Present-file and unfiltered git-history observations (which must disclose `incompleteHistory` when shallow clones or add/delete-only scans omit renames/moves) are advisory candidate aids only; only the admission owner's proved population (including move-out and historical reservations) certifies number eligibility.
|
|
72
|
+
- **Worked fixtures (`§§2.6–2.10`):**
|
|
73
|
+
1. *Redirect pointer vs full ADR (`§2.9`):* A vacated source path retains only `type: redirect` and `target: adr:github.com:1347756127:neomjs%2Fneo-agent-institution:0038` in frontmatter plus a human locator link in prose — never ADR status/number/title frontmatter or competing decision text.
|
|
74
|
+
2. *Equal numbers in two repositories (`§2.6`):* `adr:github.com:1347756127:neomjs%2Fneo-agent-institution:0038` and `adr:github.com:1344062228:neomjs%2Fneo-agent-brain:0038` are distinct decisions; local numbers do not collide across `(forge, repositoryId)`.
|
|
75
|
+
3. *Rename with `Aliases` + repository rename/reuse (`§§2.6–2.7.2`):* Renaming `<NNNN>-<old-slug>.md` → `<NNNN>-<new-slug>.md` records `| **Aliases** | \`harness-docking-design\` |` on `neomjs/neo#adr:docking-design`; if a repository rename and old-name reuse ever conflict with reserved historical occupancy, disambiguate with the `§2.6` canonical key.
|
|
76
|
+
4. *Unavailable destination (`§2.10`):* When an admitted key's declared source is unreadable, report identity resolution and unavailable document as separate facts (`identityResolved: true, documentAvailable: false, stale: true`) rather than pruning or guessing.
|
|
77
|
+
5. *Missing identity proof / ambiguous bare alias (`§§2.7.1, 2.8`):* An unqualified alias or bare legacy number without evidenced origin context remains unresolved/ambiguous within reader scope — never infer provenance from current custodian, URL occupancy, or traversal order.
|
|
78
|
+
|
|
79
|
+
*Retirement trigger:* Examples retire in favor of executable reader enforcement when the latter owns the same decision.
|
|
80
|
+
|
|
61
81
|
## Empirical Anchor
|
|
62
82
|
|
|
63
83
|
The MemoryCore arc (`#14342` → `#14344` ~6/10 → `#14348` / `#14351` 9/10) and the KnowledgeBase rubber-stamp reversal (`#14346`), 2026-06-29. Each cycle caught exactly one failure mode above; this skill is those cycles distilled.
|
|
@@ -36,10 +36,9 @@ Before Discussion prose, read the Brain-owned [reference-hygiene contract](https
|
|
|
36
36
|
Close Discussion bodies and substantive comments (divergence cycles, sweeps, graduation signals) with `Name (Model, Harness) · session <uuid>` — the fields GitHub does not render. Acks and one-line replies are exempt.
|
|
37
37
|
|
|
38
38
|
## 3. Author's Note Convention (The `#10119` Annotation Pattern)
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
- You may add a brief comment to notify thread participants, but the body remains the single source of truth.
|
|
39
|
+
Keep the current decision in the **body** (`#10119` pattern), using `manage_discussion({action:'update_body',…})`; comments hold history and feedback. Fold changes into the core sections, with a dated update/link below. A corrective comment alone leaves the head stale. Notify participants when needed.
|
|
40
|
+
|
|
41
|
+
<!-- trigger: an accepted fold changes or abandons an approach with older work still pointing to it → apply ../../ticket-create/references/decision-substrate-sweeps.md#same-turn-reconciliation -->
|
|
43
42
|
|
|
44
43
|
## 4. Iterative Review Workflow
|
|
45
44
|
The ideation lifecycle mirrors the PR review protocol. Comments serve as review feedback. When an Open Question (OQ) is resolved through discussion, the author edits the body to reflect the decision.
|
|
@@ -184,7 +183,7 @@ For the canonical markdown template (post-Epic `#11796` family-keyed shape, same
|
|
|
184
183
|
|
|
185
184
|
At §6.2 quorum: file the target artifact for its real `#N` → record `[GRADUATED_TO_TICKET: #N]` plus §6.6 / `Decision Record:` sections → close RESOLVED. Pre-quorum reservations follow `ticket-create-workflow.md §1d`: keep `[PROVISIONAL_UNGRADUATED: D#N]` (and any PR draft with `Refs`) until quorum; then promote, record, remove the marker, and only then become ready/merge-eligible. `Decision Record: REQUIRED` => file/update ADR; name merge gate. Full sequence: [`audits/consensus-mandate.md §author-actions`](../audits/consensus-mandate.md).
|
|
186
185
|
|
|
187
|
-
Closure: [`audits/discussion-lifecycle-closure.md`](../audits/discussion-lifecycle-closure.md); guard: `npm run ai:audit-discussion-lifecycle`.
|
|
186
|
+
Before reporting graduation complete, apply [same-turn reconciliation](../../ticket-create/references/decision-substrate-sweeps.md#same-turn-reconciliation) to superseded trails, including direct ADR/PR graduations. Closure: [`audits/discussion-lifecycle-closure.md`](../audits/discussion-lifecycle-closure.md); guard: `npm run ai:audit-discussion-lifecycle`.
|
|
188
187
|
|
|
189
188
|
### 6.8 Two-Axis Substrate: Discussion-Graduation + PR-Merge
|
|
190
189
|
|
package/.agents/skills/industry-friction-radar/references/industry-friction-radar-workflow.md
CHANGED
|
@@ -51,7 +51,7 @@ You must use the `ideation-sandbox` skill to post a GitHub Discussion proposing
|
|
|
51
51
|
- **No Direct PRs:** This skill produces Ideas (Discussions), never Code (Commits/PRs).
|
|
52
52
|
- **Attribution:** The resulting GitHub Discussion MUST include an Author's Note citing the provenance of the friction point, using the `citations` array from Step 2. (e.g., *"External friction observed in [ecosystem] [date]; this Discussion abstracts and responds natively via Neo's architecture."*)
|
|
53
53
|
- **Adjacency Sweep:** Before posting the Discussion, execute a duplicate sweep (per `ideation-sandbox` guidelines) to ensure the concept isn't already being discussed.
|
|
54
|
-
- **Interaction Grain:** When an external system is a capability floor, author parity rows at interaction grain (what the user feels), never feature-name grain — coarse rows propagate as settled facts (anchor:
|
|
54
|
+
- **Interaction Grain:** When an external system is a capability floor, author parity rows at interaction grain (what the user feels), never feature-name grain — coarse rows propagate as settled facts (anchor: `neomjs/neo#adr:docking-design` §4.1 row 1 / #14934).
|
|
55
55
|
|
|
56
56
|
## Integrations & Context
|
|
57
57
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Lane-Intent Protocol
|
|
2
2
|
|
|
3
|
-
*(Per #11537, graduated from Discussion #11536 OQ1. Deep rationale + canonical examples + edge cases →
|
|
3
|
+
*(Per #11537, graduated from Discussion #11536 OQ1. Deep rationale + canonical examples + edge cases → `neomjs/neo-agent-brain#adr:lane-intent-coordination-primitive`.)*
|
|
4
4
|
|
|
5
5
|
## 0. The Essential
|
|
6
6
|
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
2. **Long V-B-A required** — spans multiple turns OR heavy tooling (`/memory-mining`, `/tech-debt-radar`, deep `ask_knowledge_base`)
|
|
23
23
|
3. **Real duplicate-work risk** — peer could plausibly start parallel exploration within the V-B-A window
|
|
24
24
|
|
|
25
|
-
Missing ANY → just complete V-B-A locally + `[lane-claim]` directly. Canonical positive/negative examples + edge cases:
|
|
25
|
+
Missing ANY → just complete V-B-A locally + `[lane-claim]` directly. Canonical positive/negative examples + edge cases: `neomjs/neo-agent-brain#adr:lane-intent-coordination-primitive`.
|
|
26
26
|
|
|
27
27
|
## 2. Required A2A Shape
|
|
28
28
|
|
|
@@ -70,4 +70,4 @@ Recipient: AGENT:*
|
|
|
70
70
|
|
|
71
71
|
- AGENTS.md §0 Invariant 7 — Map-tier entry-point (per #11534)
|
|
72
72
|
- peer-role-mode §6.5 / §6.5.1 / §6.6 / §7 — `[lane-claim]` semantics + `[lane-override]` + authority hierarchy + anti-patterns
|
|
73
|
-
-
|
|
73
|
+
- `neomjs/neo-agent-brain#adr:lane-intent-coordination-primitive` — substrate-evolution rationale + canonical examples + edge cases + sister primitives
|
|
@@ -7,7 +7,7 @@ Markdown a human edits directly. Failure mode: generations drift apart (one doc
|
|
|
7
7
|
|
|
8
8
|
| Surface | What identity it encodes |
|
|
9
9
|
|---|---|
|
|
10
|
-
| `README.md` | Should LEAD with the canonical apex (
|
|
10
|
+
| `README.md` | Should LEAD with the canonical apex (`neomjs/neo#adr:neo-identity-source-of-truth-model` §2.7 OD-1) and present the whole: Body, Brain and Institution as their own repositories (OD-4); "Who This Is For"; Platform-at-Scale metrics; maintainer roster. Verify apex currency each run — status claims rot; the requirement doesn't. |
|
|
11
11
|
| `.github/VISION.md` | Long-form vision; **known fossil-prone** (carried "web applications" + CEO/PM/Drone hierarchy contradicting Flat Peer-Team) |
|
|
12
12
|
| `ROADMAP.md` | Forward positioning; "Corporate HQ" framing; skill/velocity counts |
|
|
13
13
|
| `CONTRIBUTING.md`, `.github/GETTING_STARTED.md`, `.github/AI_QUICK_START.md` | Contributor-facing identity; MCP-server count; Node requirement |
|
|
@@ -52,7 +52,7 @@ Correct as-of a date; ages silently. Refresh in lock-step.
|
|
|
52
52
|
|
|
53
53
|
## Coverage notes
|
|
54
54
|
- Heritage facts live in `.github/STORY.md`; README + portal About Us reference that home without duplicating milestone lists. OS-Awards claims need an acceptable external public source before publication.
|
|
55
|
-
- Identity handles are routed through `ai/graph/identityRoots.mjs`; handle de-versioning is operator-owned (account rename), the skill only propagates. Model-version stays in the Brain-owned [Model Stats guide](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/ModelStats.md) per
|
|
55
|
+
- Identity handles are routed through `ai/graph/identityRoots.mjs`; handle de-versioning is operator-owned (account rename), the skill only propagates. Model-version stays in the Brain-owned [Model Stats guide](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/ModelStats.md) per `neomjs/neo-agent-brain#adr:model-stats-framework`. Re-run a seam-keyed grep before claiming total coverage.
|
|
56
56
|
- Not yet fully swept: `apps/portal/view/about` (`/about-us`), live neomjs.com `<meta>`/ld+json, and the Engine-owned comparisons corpus. Re-run a fan-out before claiming total coverage.
|
|
57
57
|
|
|
58
58
|
## ACTIONS / CTA overlay
|
|
@@ -7,7 +7,7 @@ Each identity FACT has ONE canonical source. Every other occurrence derives from
|
|
|
7
7
|
| **Package version** | `package.json` `version` | extend `buildScripts/release/prepare.mjs` to derive version-bearing structured surfaces + the Engine-owned [Neural Link guide](https://github.com/neomjs/neo/blob/dev/learn/agentos/NeuralLink.md) version line; coherence-check the rest | Engine-owned Neural Link guide; `FooterContainer.mjs` literal |
|
|
8
8
|
| **MCP-server count / audience split** | `package.json` scripts matching `ai:mcp-server-*` — NOT `ls ai/mcp/server/` (that returns 7: it includes `shared/` infra + `gitlab-workflow/` PoC; functional = 5: knowledge-base, memory-core, github-workflow, neural-link, file-system). Frontier-harness defaults expose 4 because Codex, Claude, Gemini CLI, and Antigravity already provide native filesystem/tools; file-system is for `Neo.ai.Agent` / local harnessless loops. | derive into prose/JSON or lint coherence-check against the script manifest plus the audience split | README; AI_QUICK_START; ApplicationEngine.md; index.html FAQ; AiToolchain.mjs; llms.txt header |
|
|
9
9
|
| **Node requirement** | `package.json` `engines.node` | derive doc mentions; lint | AI_QUICK_START; structured-data `softwareRequirements` if reintroduced |
|
|
10
|
-
| **Identity handle** | `ai/graph/identityRoots.mjs` | route references through the seam. Account rename is operator-owned (Tier-4); the skill propagates. Model-version stays in the Brain-owned [Model Stats guide](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/ModelStats.md) per
|
|
10
|
+
| **Identity handle** | `ai/graph/identityRoots.mjs` | route references through the seam. Account rename is operator-owned (Tier-4); the skill propagates. Model-version stays in the Brain-owned [Model Stats guide](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/ModelStats.md) per `neomjs/neo-agent-brain#adr:model-stats-framework` — do NOT de-version the prose | hand-maintained current surfaces can retain stale handles after a graph/code migration; re-run a seam-keyed grep |
|
|
11
11
|
| **Recurring motto** | Brain-owned [Dream Pipeline guide](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/DreamPipeline.md) (origin of "the system evolves by predicting its own evolution") | reference a single quotable constant; don't re-type | Dream Pipeline (2×), README, ROADMAP |
|
|
12
12
|
| **Codebase-scale metrics** | Engine-owned [Codebase Overview](https://github.com/neomjs/neo/blob/dev/learn/guides/fundamentals/CodebaseOverview.md) | README "Platform at Scale" refreshes in lock-step; carry an explicit as-of date | README |
|
|
13
13
|
| **GA / public repo start date** | first git commit (`git log --reverse`, = `2019-11-11`) | heritage = append-only; write once into `.github/STORY.md` | README / portal should reference the story, not duplicate the date |
|
|
@@ -3,9 +3,9 @@
|
|
|
3
3
|
Framing (taglines, positioning, audience) is **deliberately plural** — different surfaces address different audiences and may legitimately differ. Governance means keeping each surface *compatible with* the canonical apex, NOT identical to it.
|
|
4
4
|
|
|
5
5
|
## The canonical apex
|
|
6
|
-
The apex is the operator-DECIDED frame below (
|
|
6
|
+
The apex is the operator-DECIDED frame below (`neomjs/neo#adr:neo-identity-source-of-truth-model` §2.7 OD-1) — the source of authority for "what Neo is." The `README.md` opening is the surface that should *lead* with this apex; every other framing is a governed projection of it. (If the README currently leads with an older frame, that is drift the skill corrects — the apex is the decided frame, not "whatever the README says today".)
|
|
7
7
|
|
|
8
|
-
GRADUATED via Discussion #12234 (full cross-family triad, 2026-05-31;
|
|
8
|
+
GRADUATED via Discussion #12234 (full cross-family triad, 2026-05-31; `neomjs/neo#adr:neo-identity-source-of-truth-model` §2.7 OD-1). Canonical apex line (human-facing — README + portal hero):
|
|
9
9
|
|
|
10
10
|
> **Neo.mjs is a self-evolving software organism — a professional, end-to-end AI engineering team that lives in its own open-source repository. Where the industry runs one AI agent and gets slop, Neo runs a swarm of minds from rival labs — Claude, Gemini, GPT — that read each other's reasoning through shared memory and Active Hybrid GraphRAG, catching what no single model can see in itself. Through the Neural Link possession interface, the swarm does not just read code; it inhabits live applications, inspecting semantic runtime state, mutating UI and data in real time, and turning conversational UIs from chat panels into agents collaborating inside the application. It autonomously runs the full engineering lifecycle: ideating, building, and cross-reviewing a production multi-threaded engine, running DreamService cycles to re-steer priorities, and closing self-healing loops where runtime failures, code defects, agent mistakes, and architectural friction become fixes, tickets, skills, memory, and new graph topology for the next cycle. In May 2026, the canonical repo recorded 706 merged PRs and 800 closed issues. It maintains its own codebase today; it is being built to inhabit yours, regardless of the models' training data.**
|
|
11
11
|
|
|
@@ -15,7 +15,7 @@ Concise form for machine surfaces that present the whole (never the word "slop")
|
|
|
15
15
|
|
|
16
16
|
**Dated proof point** (NOT inline in the apex — proof layer only; use a FIXED calendar anchor, not a rolling window): **in May 2026 the canonical repo recorded 706 merged PRs and 800 closed issues** (GitHub search, verified 2026-05-31). NEVER write "peer-reviewed" counts (search verifies *merged*, not review-state) or a month-over-month ratio / "accelerating" claim (date-stamps the identity; the April→May delta was mis-stated as ~3×) without a precise metric spec + audit — per @neo-gpt V-B-A `dc-17119216`/`dc-17119231` + operator flag.
|
|
17
17
|
|
|
18
|
-
Structure beneath the apex (
|
|
18
|
+
Structure beneath the apex (`neomjs/neo#adr:neo-identity-source-of-truth-model` §2.7 OD-4: three repositories, three products):
|
|
19
19
|
> - **Body — `neomjs/neo`, the Engine:** the high-performance off-main-thread UI runtime — JSON-first since 2019, App Worker as the main actor, web multi-window. The adoption substrate. (Engine-category mental models apply *here only*.)
|
|
20
20
|
> - **Brain — `neomjs/neo-agent-brain`, the Agent OS:** Memory Core (**Active Hybrid GraphRAG**), Knowledge Base, A2A, orchestrator, DreamService, the MX loop; gives agents continuity, runs without the Fleet Manager.
|
|
21
21
|
> - **Institution — `neomjs/neo-agent-institution`, the Fleet Manager:** makes Neo accessible; starts the harnesses over the Brain's Fleet transport.
|
|
@@ -28,7 +28,7 @@ Structure beneath the apex (ADR 0018 §2.7 OD-4: three repositories, three produ
|
|
|
28
28
|
|
|
29
29
|
Proof asset: blog #10074 (cross-family self-healing, first-person, verified-true).
|
|
30
30
|
|
|
31
|
-
When the operator changes the apex, update this section and
|
|
31
|
+
When the operator changes the apex, update this section and `neomjs/neo#adr:neo-identity-source-of-truth-model` §2.7 in the same PR.
|
|
32
32
|
|
|
33
33
|
## Audience-segmented clusters (deliberate — do NOT flatten)
|
|
34
34
|
The same product reads differently per audience; these are kept as ONE coupled cluster each, governed for *compatibility* with the apex:
|
|
@@ -40,7 +40,7 @@ The same product reads differently per audience; these are kept as ONE coupled c
|
|
|
40
40
|
| "self-maintaining codebase / autonomous AI engineering team" | the Brain's and Institution's repo descriptions | AI-platform / agent-infra builders (the audience that funds the comparison tools) |
|
|
41
41
|
| "self-evolving software organism / two hemispheres" | `.github/VISION.md`, AGENTS.md anchors, deeper learn/ docs | researchers, the swarm itself |
|
|
42
42
|
|
|
43
|
-
All four are projections of the **canonical apex** — the self-evolving software organism (§ The canonical apex), with Body/Brain the two hemispheres beneath it. The label leads its surfaces, with the apex behind it as the proof paragraph (
|
|
43
|
+
All four are projections of the **canonical apex** — the self-evolving software organism (§ The canonical apex), with Body/Brain the two hemispheres beneath it. The label leads its surfaces, with the apex behind it as the proof paragraph (`neomjs/neo#adr:neo-identity-source-of-truth-model` §2.3). Members of a cluster must stay coherent with **each other** (don't let package.json and GitHub description diverge) and **compatible** with the apex (a narrower projection, not a contradiction). Each repository's own metadata projects its own product — for `neomjs/neo` the Engine (OD-4, `./affected-areas-map.md` Class 4); an organism-wide description there is drift.
|
|
44
44
|
|
|
45
45
|
## Drift vs intentional-divergence (the escalation branch)
|
|
46
46
|
When a surface's framing **contradicts** the apex, classify:
|
|
@@ -62,5 +62,5 @@ Identity copy attracts superlatives. Gate every one:
|
|
|
62
62
|
| Client/partner/customer names | **Forbidden** on every surface. Cloud/multi-tenant = generic capability terms only. |
|
|
63
63
|
| Awards / external facts | Verify against an external source before public citation. |
|
|
64
64
|
|
|
65
|
-
## Why a cross-family review gate (
|
|
65
|
+
## Why a cross-family review gate (`neomjs/neo#adr:neo-identity-source-of-truth-model` §2.6)
|
|
66
66
|
An identity edit is a single-author change to canonical framing — the self-authored-blind-spot risk class that cross-family review reliably catches (anchors: PRs #12146, #11999, #11962). Mandatory before merge; the human merge-gate is the backstop when only one family is active.
|
|
@@ -30,14 +30,14 @@ Before writing any "fastest / only / first / Nth" into a surface, run the check
|
|
|
30
30
|
For ACTIONS, also run the liveness and proof-adjacency checks in `./cta-governance.md`. A CTA that points at a dead / low-retention / unverified surface cannot be primary. A strong claim with no nearby proof door fails the ACTIONS gate even if the prose is otherwise accurate.
|
|
31
31
|
|
|
32
32
|
## Step 4 — One PR, cross-family review
|
|
33
|
-
- Branch + PR targeting `dev` (per repo pull-request workflow). Reference the identity ticket and
|
|
33
|
+
- Branch + PR targeting `dev` (per repo pull-request workflow). Reference the identity ticket and `neomjs/neo#adr:neo-identity-source-of-truth-model`.
|
|
34
34
|
- **Mandatory: request a cross-family review.** Identity edits are single-author, high-blast canonical-framing changes — exactly the self-authored-blind-spot class cross-family review catches (anchors: PRs #12146, #11999, #11962). If only one family is active, the human merge-gate is the backstop; say so in the PR.
|
|
35
35
|
- In the PR body, list the out-of-tree (Class 4) changes separately so the reviewer can confirm them.
|
|
36
36
|
|
|
37
37
|
## Step 5 — Post-merge
|
|
38
38
|
- If a fact's SSOT or propagation tooling was missing (e.g. `prepare.mjs` didn't cover a surface), file the gap as a follow-up so the next update auto-propagates.
|
|
39
39
|
- If a CTA needs operator-owned offer content, lead-capture routing, pricing, or business language, record the dependency instead of inventing it.
|
|
40
|
-
- If you sharpened the apex, confirm
|
|
40
|
+
- If you sharpened the apex, confirm `neomjs/neo#adr:neo-identity-source-of-truth-model` §2.7 reflects it.
|
|
41
41
|
|
|
42
42
|
## Anti-patterns
|
|
43
43
|
- Editing only the README and declaring identity "updated."
|
|
@@ -20,7 +20,7 @@ Stage 1 — Pattern-match check: "Does this file's role match an established sib
|
|
|
20
20
|
✓ YES → fast-path: sibling-file-lift suffices; emit a one-line Pre-Flight
|
|
21
21
|
statement and proceed (under 30 seconds)
|
|
22
22
|
✗ NO → full structural-pre-flight: ArchitectureOverview.md consultation,
|
|
23
|
-
|
|
23
|
+
repository-qualified ADR sweep, chief-architect framing questions,
|
|
24
24
|
map-maintenance discipline, optional ADR genesis
|
|
25
25
|
```
|
|
26
26
|
|
|
@@ -56,9 +56,9 @@ Fires when no clear sibling pattern matches the new file's role. The cost is ~5-
|
|
|
56
56
|
Before drafting the file, you MUST read:
|
|
57
57
|
|
|
58
58
|
1. **The Engine's [Architecture Overview](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md)** — specifically the **Structural Inventory** section (currently lines 350-382). This is the canonical map of the codebase's directory taxonomy.
|
|
59
|
-
2. **Relevant ADRs in
|
|
60
|
-
- `
|
|
61
|
-
- `
|
|
59
|
+
2. **Relevant ADRs in their canonical owning repositories** (per [neomjs/neo-agent-brain#adr:adrs-as-graph-queryable-entities](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0006-adrs-as-graph-queryable-entities.md) and [`guide-authoring-bar.md §7`](../../guide-authoring/references/guide-authoring-bar.md#7-adr-custody-redirects-repository-qualified-identity--slug-citations--machine-enforceable-candidate)) — these document cross-system architectural trade-offs that constrain directory choice. Examples:
|
|
60
|
+
- `neomjs/neo-agent-brain#adr:cross-process-cache-coherence` (singleton-cache reasoning)
|
|
61
|
+
- `neomjs/neo-agent-brain#adr:phase3-wake-substrate-standards-alignment` (wake-substrate standards)
|
|
62
62
|
- Any newer ADR whose subsystem overlaps your candidate destination.
|
|
63
63
|
3. **The [Agent OS v13 path](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/v13-path.md)** when the new file lives in `ai/`-side substrate — this is the M-milestone source-of-authority for current architectural posture (M1 deployment-pipeline, M2 BaseServer, M3 Orchestrator, M4 Dream/Sandman, M5 NEO_MC_PRIMARY retirement, M6 SDK migration, M7 closeout). PR #11008 misplaced because authoring did not consult this document.
|
|
64
64
|
4. **1-2 sibling files in EACH candidate destination directory** — even when the role doesn't match exactly. Reading siblings in `ai/scripts/` and `ai/daemons/` side-by-side reveals which directory the new file actually belongs in. The empirical anchor would have surfaced immediately.
|
|
@@ -101,7 +101,7 @@ Per Discussion #10447 OQ4 resolution, the threshold for filing an ADR vs an inli
|
|
|
101
101
|
- **Cross-system trade-off** (touches multiple subsystems, sets a precedent for future code, affects load-bearing invariants): **file an ADR** in the repository that canonically owns the affected substrate. If the current checkout is not that owner, route a linked companion change there and keep the ADR-genesis gate failed; never create a consumer-local decisions tree.
|
|
102
102
|
- **Localized constraint** (specific to one file or one method, doesn't generalize): **inline Anchor & Echo guard** in the JSDoc with `@see` references.
|
|
103
103
|
|
|
104
|
-
**Example — ADR-class:** "Memory Core uses singleton cache instead of cross-process IPC because IPC overhead exceeds memory pressure cost at expected scale" (became `
|
|
104
|
+
**Example — ADR-class:** "Memory Core uses singleton cache instead of cross-process IPC because IPC overhead exceeds memory pressure cost at expected scale" (became `neomjs/neo-agent-brain#adr:cross-process-cache-coherence`).
|
|
105
105
|
|
|
106
106
|
**Example — Anchor-and-Echo-class:** "this method's `await` is intentional because the caller relies on serialized cache writes; do not refactor to parallel without re-reading `MailboxService#addMessage`."
|
|
107
107
|
|
|
@@ -123,8 +123,8 @@ When the new file lives in `ai/` substrate (Right Hemisphere / Agent OS):
|
|
|
123
123
|
|
|
124
124
|
- The [Agent OS v13 path](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/v13-path.md) — current M-milestone architectural posture (M1-M7).
|
|
125
125
|
- The Engine [Architecture Overview](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md) §Right Hemisphere + §Structural Inventory § Agent OS (Node.js).
|
|
126
|
-
- [
|
|
127
|
-
- [
|
|
126
|
+
- [neomjs/neo-agent-brain#adr:cross-process-cache-coherence](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0001-cross-process-cache-coherence.md) (Memory Core).
|
|
127
|
+
- [neomjs/neo-agent-brain#adr:phase3-wake-substrate-standards-alignment](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0002-phase3-wake-substrate-standards-alignment.md) (wake substrate).
|
|
128
128
|
- Sibling files in EACH candidate `ai/{daemons,scripts,services,graph,mcp,...}/` directory.
|
|
129
129
|
|
|
130
130
|
### 3.2 `src/`-side authoring
|
|
@@ -133,7 +133,7 @@ When the new file lives in `src/` substrate (Left Hemisphere / Runtime Engine):
|
|
|
133
133
|
|
|
134
134
|
- The Engine [Architecture Overview](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md) §Left Hemisphere + §Structural Inventory § Runtime Engine (Browser).
|
|
135
135
|
- `learn/guides/<subsystem>/` — subsystem-specific guides (e.g., `learn/guides/grid/` for grid work).
|
|
136
|
-
- `
|
|
136
|
+
- Canonical ADRs in their owning repositories (see [`guide-authoring-bar.md §7`](../../guide-authoring/references/guide-authoring-bar.md#7-adr-custody-redirects-repository-qualified-identity--slug-citations--machine-enforceable-candidate)) whose stated subsystem touches your candidate destination.
|
|
137
137
|
- Sibling files in EACH candidate `src/{component,container,grid,data,state,worker,vdom,main,...}/` directory.
|
|
138
138
|
|
|
139
139
|
### 3.3 Test-tree authoring
|
|
@@ -193,7 +193,7 @@ The skill does NOT fire for:
|
|
|
193
193
|
|
|
194
194
|
### 7.2 Full Pre-Flight Example (Hypothetical Orchestrator-Class File)
|
|
195
195
|
|
|
196
|
-
> *"Pre-Flight (structural full): considered destinations `ai/scripts/`, `ai/daemons/`, and `ai/daemons/services/` for `Orchestrator.mjs`; consulted the Engine [Architecture Overview](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md) Structural Inventory (`ai/daemons/` sibling = `DreamService.mjs`, `ai/scripts/` sibling = one-shot scripts, `ai/daemons/services/` sibling = service-class daemons), and the [Agent OS v13 path](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/v13-path.md) §M3 (current architectural posture explicitly mandates `ai/daemons/Orchestrator.mjs` Neo-class + `ai/daemons/services/SummarizationCoordinatorService.mjs` decomposition + thin `ai/scripts/orchestrator-daemon.mjs` boot wrapper); no relevant ADR conflict (
|
|
196
|
+
> *"Pre-Flight (structural full): considered destinations `ai/scripts/`, `ai/daemons/`, and `ai/daemons/services/` for `Orchestrator.mjs`; consulted the Engine [Architecture Overview](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md) Structural Inventory (`ai/daemons/` sibling = `DreamService.mjs`, `ai/scripts/` sibling = one-shot scripts, `ai/daemons/services/` sibling = service-class daemons), and the [Agent OS v13 path](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/v13-path.md) §M3 (current architectural posture explicitly mandates `ai/daemons/Orchestrator.mjs` Neo-class + `ai/daemons/services/SummarizationCoordinatorService.mjs` decomposition + thin `ai/scripts/orchestrator-daemon.mjs` boot wrapper); no relevant ADR conflict (`neomjs/neo-agent-brain#adr:cross-process-cache-coherence` about caching, `neomjs/neo-agent-brain#adr:phase3-wake-substrate-standards-alignment` about wake substrate); chose `ai/daemons/Orchestrator.mjs` for the class body + `ai/daemons/services/SummarizationCoordinatorService.mjs` for the per-task service + `ai/scripts/orchestrator-daemon.mjs` for the thin wrapper, because the v13 path §M3 establishes this exact split as the canonical architectural posture and the orchestrator class is a long-running coordination primitive (not a one-shot script). Map-maintenance: not-needed (existing Structural Inventory row for `ai/daemons/` covers Orchestrator without addition). Chief-architect framing: scalability (good — `ai/daemons/services/` accommodates future per-task services); ADR-conflict (none); ADR-genesis (not needed — the v13 path §M3 already documents the trade-off at the M-milestone-plan level); future-self regression-risk (low — split mirrors existing decomposition discipline)."*
|
|
197
197
|
|
|
198
198
|
The full-pre-flight statement is verbose by design. Brevity hides reasoning; verbosity creates audit substrate.
|
|
199
199
|
|
|
@@ -11,7 +11,7 @@ Run this meta-analysis with frontier-tier capability — it synthesizes document
|
|
|
11
11
|
A copied canon decays by construction and eventually inverts — the radar then flags sanctioned shapes as debt. At sweep time, load the debt taxonomy FROM the living authorities, and keep three classes separate: **authority** (what the canon prescribes), **observation** (what the tree currently is), and **hypothesis** (candidate findings awaiting an owning lane):
|
|
12
12
|
|
|
13
13
|
1. The Engine's [Architecture Overview](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md) — the structural baseline (Body/Brain topology). *Authority.*
|
|
14
|
-
2.
|
|
14
|
+
2. **The repository-qualified ADR canon** ([neomjs/neo-agent-brain#adr:adrs-as-graph-queryable-entities](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0006-adrs-as-graph-queryable-entities.md); custody redirects, 4-field keys, and `<org>/<repo>#adr:<slug>` rules in [`guide-authoring-bar.md §7`](../../guide-authoring/references/guide-authoring-bar.md#7-adr-custody-redirects-repository-qualified-identity--slug-citations--machine-enforceable-candidate)) — minimum reads: `neomjs/neo-agent-brain#adr:aiconfig-reactive-provider-ssot` (the `ai/`-config antipattern catalog) for config debt; `neomjs/neo#adr:skill-anatomy-and-authoring-contract` for skill-shape debt. *Authority.* Follow `type: redirect` (`target: <canonical-key>`) / `Status: Moved` pointer stubs to their canonical target; never treat a redirect stub as retired.
|
|
15
15
|
3. `npm run ai:structure-map -- --files --loc` — current-tree measurement: where things ARE and how large. Brain-hosted; where absent, record N/A and never add `--silent`, which hides npm's `Missing script` behind an empty exit-1. *Observation only — no intended-placement policy; observed placement is never its own authority.*
|
|
16
16
|
4. The `pr-review` guide's anti-pattern tables and `AGENTS.md` §edge_case_triggers (the `apps/**` data-path/style gate, `core.Base` as the quality bar). *Authority.*
|
|
17
17
|
|
|
@@ -1,16 +1,10 @@
|
|
|
1
1
|
# Decision-substrate sweeps — arms `(iii)`, `(iv)` and `(v)` of §1a
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
A `NOT_PLANNED` predecessor is a **ruling**. An artifact sweep surfaces its title and never its reason, so it fails silently: a clean sweep, filed with confidence, carrying a fresh-timestamp attestation proving the sweep ran.
|
|
3
|
+
Declined predecessors carry decisions; read their reasons.
|
|
6
4
|
|
|
7
5
|
## (iii) Memory Core rationale sweep
|
|
8
6
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
```js
|
|
12
|
-
query_raw_memories({query: '<repo> <mechanism> <file/symbol> <prior-decision terms>', nResults: 6})
|
|
13
|
-
```
|
|
7
|
+
Immediately before `create_issue`, run at least one `query_raw_memories` keyed on the **problem's nouns**: repo, package, file/symbol and existing failed mechanism, never the proposed solution.
|
|
14
8
|
|
|
15
9
|
**Query the PROBLEM's nouns, never the SOLUTION's.** This is the distinction the arm turns on, and it is not "search harder":
|
|
16
10
|
|
|
@@ -20,9 +14,9 @@ query_raw_memories({query: '<repo> <mechanism> <file/symbol> <prior-decision ter
|
|
|
20
14
|
| ❌ structural / boilerplate phrasing | *"should we add a gate for…"* | session boilerplate; Memory Core indexes artifacts |
|
|
21
15
|
| ✅ the problem's nouns — the symptom as observed | *"vast amounts of additional tickets"*, *"different casualty each run"* | prior art that solved the same problem **differently** |
|
|
22
16
|
|
|
23
|
-
|
|
17
|
+
Use the operator's symptom vocabulary; searching only your proposed mechanism hides other solutions.
|
|
24
18
|
|
|
25
|
-
> **
|
|
19
|
+
> **2026-08-31 anchors:** `neo-agent-skills#32` missed `neomjs/neo#16212` by querying the proposed mechanism instead of *"vast amounts of additional tickets"*. `neomjs/neo#18000` missed `neomjs/neo#17796` by querying a suite name instead of *"different casualty each run"*. Match the symptom across different solutions and suites.
|
|
26
20
|
|
|
27
21
|
`query_summaries` and `explore_lane_landscape` widen the sweep when the first call returns only noise.
|
|
28
22
|
|
|
@@ -32,9 +26,7 @@ The problem's nouns are frequently **the operator's own words for the symptom**,
|
|
|
32
26
|
gh issue list --repo <r> --state open --assignee @me --json number,title
|
|
33
27
|
```
|
|
34
28
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
Neither `(i)` (recency-bounded) nor a closed-issue search reaches an **open, old, self-assigned** parent. A defect found *while measuring something else* is the high-risk shape: it feels like discovery precisely because no retrieval preceded it.
|
|
29
|
+
Read the **bodies** of the two or three same-surface hits, including tables and deferred clauses. Old open self-assignments escape both `(i)`'s recency window and closed-state queries; incidental discoveries need this check too.
|
|
38
30
|
|
|
39
31
|
## (v) Epic-layer outcome-authority sweep
|
|
40
32
|
|
|
@@ -46,14 +38,12 @@ gh issue list --repo <r> --label epic --state open --json number,title
|
|
|
46
38
|
|
|
47
39
|
Compare **terminal predicates**, not titles: *what state of the world does this Epic declare finished?* Two Epics that finish the same sentence are one Epic, however differently they open.
|
|
48
40
|
|
|
49
|
-
**Read every
|
|
50
|
-
|
|
51
|
-
1. **Predicate scan (every row).** Read each open epic's `Terminal predicate:` line. Cheap enough to be exhaustive, which is the only reason "every" is honest here.
|
|
52
|
-
2. **Body read (the ranked few).** For rows predating the field, or whose predicate is close enough to yours to be arguable, run the semantic outcome-overlap query and read only the bodies it ranks. Retrieval surfaces the candidates; **only a reader can rule** — that is the judgement the arm exists to force, and it is not the part that was expensive.
|
|
41
|
+
**Read every predicate, then selected bodies.** `epic-create` puts `Terminal predicate:` first to keep this exhaustive read affordable:
|
|
53
42
|
|
|
54
|
-
|
|
43
|
+
1. **Every row:** read each open epic's terminal predicate.
|
|
44
|
+
2. **Ranked bodies:** for missing or arguably overlapping predicates, run the semantic outcome-overlap query and read its ranked candidates. Retrieval proposes; the reader judges overlap.
|
|
55
45
|
|
|
56
|
-
|
|
46
|
+
**Cost control:** read predicates exhaustively, bodies selectively. On 2026-09-02, 29 Engine epics implied ~290k characters for an all-body read; re-query populations rather than calling them small. Standing outcomes can predate `(i)`'s window and use different nouns, splitting ownership when missed.
|
|
57
47
|
|
|
58
48
|
> **Anchor — `neomjs/neo-agent-brain#38` vs open `#54`, 2026-08-13.** Two roots, 17 and 16 children, the same two terminal predicates. The author's §1a sweep ran honestly and **passed**; a peer's epic review caught it after filing.
|
|
59
49
|
|
|
@@ -69,24 +59,22 @@ Epic sweep: <n> open epics read, no shared terminal predicate # epic-labeled
|
|
|
69
59
|
|
|
70
60
|
Prose discipline that leaves no artifact cannot be checked, and these arms exist because prose discipline failed.
|
|
71
61
|
|
|
72
|
-
## Same-turn
|
|
62
|
+
## Same-turn reconciliation
|
|
73
63
|
|
|
74
|
-
If content belongs on a parent
|
|
64
|
+
If content belongs on a surviving parent, port it there in the same turn. An accepted direction-changing fold, graduation or successor publication must also reconcile the older work it replaces. A new exploratory option alone retires nothing.
|
|
75
65
|
|
|
76
|
-
|
|
66
|
+
Reuse adjacency results and predecessor PR links: read affected tickets, open PRs (draft or ready), research recommendations, tool assumptions and active handovers/checklists. Find predecessors before filing; disposition them once successor IDs exist. Abandonment reconciles immediately against existing outcome/research owners:
|
|
77
67
|
|
|
78
|
-
|
|
68
|
+
1. Cite the accepted decision and compare each recommendation with the **current outcome and required interactions**, not just its technical feasibility. A reusable reference does not authorize a superseded research/delivery path. Keep, narrow, transfer or retire each prescription; move unique obligations, evidence and dissent to a named surviving owner first. Existing research can own the remainder without another ticket.
|
|
69
|
+
2. Update old entry heads and both sides' successor links. Retire obsolete instructions; preserve history. Close superseded PRs with decision/successor links, or retarget surviving scope. A finally rejected narrow implementation ticket closes `not_planned` per `ticket-intake` §4; unresolved outcomes stay open, and partial overlap leaves remaining obligations current. Epic closure uses `epic-resolution`.
|
|
70
|
+
3. Apply own-authored or explicitly authorized changes. For foreign bodies/ACs, follow `ticket-create` §11: propose exact text and record the owner/application still owed. A pending proposal is not applied reconciliation.
|
|
71
|
+
4. For immutable entries, put exact superseded IDs → current authority on the surviving owner's current entry and active handover. Preserve history. Read back bodies, links, states and mappings; mutable old heads must reveal disposition/owner. Report pending owner actions separately; unapplied cleanup is incomplete.
|
|
79
72
|
|
|
80
|
-
|
|
73
|
+
## Empirical anchor
|
|
81
74
|
|
|
82
|
-
|
|
83
|
-
|---|---|
|
|
84
|
-
| recency-shaped | the standing parent is older than the latest-20 window |
|
|
85
|
-
| open/closed-shaped | the decline lives in a closed issue; `(i)` reads open |
|
|
86
|
-
| ownership-shaped | the parent is open, old, and already assigned to the filer |
|
|
87
|
-
| authority-shaped | the standing Epic is open, old, owned by **someone else**, and titled in the outcome's vocabulary — arm `(v)` |
|
|
75
|
+
**`neomjs/neo#17997`, 2026-08-31.** Re-filed **row 3** of `#17868` — open, older than the `(i)` window, and assigned to the filer — four hours after that same filer's own `#17961` closing comment recorded that row 3's blocker belonged **on `#17868`**.
|
|
88
76
|
|
|
89
|
-
|
|
77
|
+
The missed decision can live in an older parent, a closed decline, a prior self-assignment or someone else's standing outcome; a latest-open artifact scan alone covers none of those cases.
|
|
90
78
|
|
|
91
79
|
**Why the sweeps run LAST.** `#12856`, 2026-06-10: four agents raced one prompt into three duplicates, each having swept honestly; the one who re-checked immediately before filing produced none. Check-at-start decays across a multi-minute protocol.
|
|
92
80
|
|
|
@@ -141,8 +141,8 @@ Skeleton tickets are forbidden — so are world atlases: sections complete, each
|
|
|
141
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).
|
|
142
142
|
- **The Fix** — concrete prescription: files, symbols, architectural primitives touched. What changes, and where.
|
|
143
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.
|
|
144
|
-
- **Decision Record impact** *(architecture/substrate tickets)* — the §2 step-6 declaration (`none` … `challenges
|
|
145
|
-
- **Decision Record** *(Discussion-origin tickets)* — Preserve the source Discussion's ADR classification when present: `Not needed`, `Optional: <ADR/ticket/discussion anchor>`, or `Required:
|
|
144
|
+
- **Decision Record impact** *(architecture/substrate tickets)* — the §2 step-6 declaration (`none` … `challenges <org>/<repo>#adr:<slug>` or same-repo `adr:<slug>`).
|
|
145
|
+
- **Decision Record** *(Discussion-origin tickets)* — Preserve the source Discussion's ADR classification when present: `Not needed`, `Optional: <ADR/ticket/discussion anchor>`, or `Required: <org>/<repo>#adr:<slug> / PR #N / ticket #N` (records the graduation's authority target; `Decision Record impact` records what this ticket itself does to ADR authority).
|
|
146
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
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
148
|
- **Out of Scope** — what this ticket deliberately does NOT do.
|
|
@@ -190,6 +190,7 @@ The `create_issue` tool returns the new issue number. The ownership disposition
|
|
|
190
190
|
- **`manage_issue_labels(action: 'add', ...)`** — only if the label set needs adjustment post-creation (e.g., label list was incomplete at `create_issue` time). Prefer getting labels right in the initial call.
|
|
191
191
|
- **`update_issue_relationship(parent_id: N, child_id: M, type: 'SUB_ISSUE')`** — required when filing sub-issues under an Epic. Native graph linkage only; do NOT rely on inline `- [ ] #N` markdown checkboxes (see §6). Count the parent's subs first (`gh api repos/<r>/issues/N/sub_issues --paginate --jq length`); past ~25, file or link to a successor epic (`epic-create` Procedure 1).
|
|
192
192
|
- **Ticket body edits:** Update GitHub directly with `gh issue edit N --body-file <path>` (or the equivalent live GitHub write surface). GitHub remains canonical; scheduled mirroring may lag.
|
|
193
|
+
- **Replacement work:** once successor IDs exist, run [same-turn reconciliation](decision-substrate-sweeps.md#same-turn-reconciliation) on the predecessors found by §1a; preserve surviving outcomes before retiring old prescriptions.
|
|
193
194
|
- **Picking up the ticket:** If you intend to start working on this newly created ticket immediately, you MUST run the `ticket-intake` skill next (your assignee claim fulfills the primary gate).
|
|
194
195
|
|
|
195
196
|
Minimize chained calls where possible — a well-formed `create_issue` call with complete `title`, `body`, and `labels` at creation time avoids all of the above except `update_issue_relationship` (which can only run after the issue exists).
|
|
@@ -6,7 +6,7 @@ This payload provides the ADR-specific branch of the ticket-intake successor-ris
|
|
|
6
6
|
|
|
7
7
|
Run this audit when any architecture-bearing ticket, Discussion, Epic, or PR:
|
|
8
8
|
|
|
9
|
-
- cites an ADR, Decision Record, or `learn
|
|
9
|
+
- cites an ADR (`<org>/<repo>#adr:<slug>`, same-repo `adr:<slug>`, or canonical key `adr:<E(forge)>:<E(repositoryId)>:<E(namespace)>:<number>` per [neomjs/neo-agent-brain#adr:adrs-as-graph-queryable-entities](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0006-adrs-as-graph-queryable-entities.md) and [`guide-authoring-bar.md §7`](../../guide-authoring/references/guide-authoring-bar.md#7-adr-custody-redirects-repository-qualified-identity--slug-citations--machine-enforceable-candidate)), Decision Record, or `learn/**/decisions/` file;
|
|
10
10
|
- predates a related accepted ADR and prescribes a conflicting shape;
|
|
11
11
|
- postdates an accepted ADR and proposes a different architecture;
|
|
12
12
|
- introduces, amends, supersedes, or retires durable agent/workflow substrate;
|
|
@@ -19,7 +19,7 @@ If no related ADR exists and the proposal does not affect decision-record substr
|
|
|
19
19
|
Before classifying, gather:
|
|
20
20
|
|
|
21
21
|
- `Artifact`: ticket / Discussion / Epic / PR number, author, `createdAt`, and `updatedAt`.
|
|
22
|
-
- `Related ADR(s)`: ADR
|
|
22
|
+
- `Related ADR(s)`: repository-qualified ADR identifier (`<org>/<repo>#adr:<slug>`, same-repo `adr:<slug>`, or §2.6 canonical key), canonical path, `Status`, and decision date if present. If a local file is a redirect stub (`type: redirect` + `target: <canonical-key>` per §2.9, or `Status: Moved`), resolve its `target` through the admitted catalog to the canonical repository/path — a redirect pointer is a custody redirect, **never** `Superseded` or `Retired`.
|
|
23
23
|
- `Chronology`: whether the artifact predates, postdates, or is same-cycle with the ADR.
|
|
24
24
|
- `Conflict surface`: the concrete contract, workflow, service boundary, or architectural premise that overlaps.
|
|
25
25
|
- `Evidence`: source/docs/tests/tickets/Discussions/PRs proving alignment, conflict, supersession, or fresh challenge.
|
|
@@ -47,16 +47,16 @@ Do not classify from title similarity alone. The conflict must be tied to a spec
|
|
|
47
47
|
|
|
48
48
|
## 5. Required Output Shape
|
|
49
49
|
|
|
50
|
-
When this audit fires, record a compact line in the current workflow artifact:
|
|
50
|
+
When this audit fires, record a compact line in the current workflow artifact using the repository-qualified ADR reference (`<org>/<repo>#adr:<slug>` or same-repo `adr:<slug>`):
|
|
51
51
|
|
|
52
52
|
```md
|
|
53
|
-
ADR successor-risk: <verdict> — artifact <#N/date>; ADR
|
|
53
|
+
ADR successor-risk: <verdict> — artifact <#N/date>; ADR <org>/<repo>#adr:<slug> (<status>/<date>); evidence <path|issue|PR|discussion>; route <continue|supersede|challenge|amendment-required|pending-authority>.
|
|
54
54
|
```
|
|
55
55
|
|
|
56
56
|
For public artifacts that create new work, also include:
|
|
57
57
|
|
|
58
58
|
```md
|
|
59
|
-
Decision Record impact: none | aligned-with
|
|
59
|
+
Decision Record impact: none | aligned-with <org>/<repo>#adr:<slug> | depends-on <org>/<repo>#adr:<slug> | amends <org>/<repo>#adr:<slug> | supersedes <org>/<repo>#adr:<slug> | challenges <org>/<repo>#adr:<slug>
|
|
60
60
|
```
|
|
61
61
|
|
|
62
62
|
## 6. Workflow Surface Map
|
|
@@ -149,6 +149,8 @@ You are **FORBIDDEN** from executing the following tools while on the `dev` or `
|
|
|
149
149
|
|
|
150
150
|
If you determine the ticket is stale or harmful, you MUST execute the Rejection Protocol instead of attempting to build it.
|
|
151
151
|
|
|
152
|
+
For surviving obligations or stale entry points, use [same-turn reconciliation](../../ticket-create/references/decision-substrate-sweeps.md#same-turn-reconciliation) within this rejection step, without another sweep.
|
|
153
|
+
|
|
152
154
|
**Close Policy:**
|
|
153
155
|
- **Architecture Exploration / Epic Tickets:** **DO NOT close the ticket.** It must be preserved so the Swarm can formally evaluate the paradox. Record what it waits on via `update_issue_relationship(blocked_by)`. Not a label: `needs-re-triage` is for externally-authored tickets below the bar (see `ticket-triage`), so stamping it here pollutes that queue.
|
|
154
156
|
- **1:1 Implementation Tickets (Including Substrate):** If the ticket is a narrow, final declined implementation task (e.g., `already-resolved`, `duplicate`, `invalid-or-negative-roi`), you MUST close the ticket as `not_planned` to prevent preserving bad payloads as future traps, even if the ticket prescribes substrate edits.
|
|
@@ -38,7 +38,7 @@ Create a fresh observational fingerprint for the intended target immediately bef
|
|
|
38
38
|
- a topology snapshot and timestamp;
|
|
39
39
|
- a safe screenshot or digest of the clean frame.
|
|
40
40
|
|
|
41
|
-
The fingerprint is not durable routing authority.
|
|
41
|
+
The fingerprint is not durable routing authority. `neomjs/neo#adr:docking-design` §2.8.5 keeps semantic names, URLs, titles, timing, and runtime IDs from becoming physical-handle authority. Treat the fingerprint only as a short-lived selection/revalidation receipt.
|
|
42
42
|
|
|
43
43
|
## 4. Recorder revalidation and frame zero
|
|
44
44
|
|
|
@@ -65,7 +65,7 @@ Native footage and application truth are complementary:
|
|
|
65
65
|
|
|
66
66
|
Bind each receipt to the exact take ID, source head, timestamp range, and evidence claim. If the Neural Link server/OpenAPI/harness projection changed, rerun capability discovery and the smoke proof before capture.
|
|
67
67
|
|
|
68
|
-
For a claim about physical close,
|
|
68
|
+
For a claim about physical close, `neomjs/neo#adr:docking-design` §2.8.5 is explicit: a native `close()` return is provisional. The receipt becomes terminal only after the connected runtime `windowId` disappears from topology. For focus/position or other physical effects, record the corresponding before/after observation and semantic state; never treat dispatch success as effect proof.
|
|
69
69
|
|
|
70
70
|
Independently opened, cross-origin, stale, or uncorrelated windows can remain observable, but physical control fails closed.
|
|
71
71
|
|
|
@@ -19,7 +19,7 @@ Start by copying `../assets/video-project-record-template.md`. That record is th
|
|
|
19
19
|
|
|
20
20
|
It consumes, without duplicating:
|
|
21
21
|
|
|
22
|
-
- `/neo-identity-update` and
|
|
22
|
+
- `/neo-identity-update` and `neomjs/neo#adr:neo-identity-source-of-truth-model` for identity-bearing claims and framing;
|
|
23
23
|
- `/neural-link` for semantic live-application inspection or interaction;
|
|
24
24
|
- `/whitebox-e2e` and `/unit-test` for app-owned runnable/test evidence;
|
|
25
25
|
- `/imagegen` for generated still-image mechanics;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "neo-agent-skills",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.55",
|
|
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",
|