Repository navigation
docs(harness): move specs, ADRs and knowledge to the .agents layout - #168
Conversation
- Add tracked `.mstarc` declaring the harness layout: process under `.mstar/`, results under `.agents/`. - Move `.mstar/knowledge/` to `.agents/knowledge/` unchanged. - Split the former `.mstar/specs/` corpus into current-state specs (`.agents/specs/<class>/<topic>.md`, fixed five-section skeleton) and decision records (`.agents/adr/implemented/<class>/yyyy-mm-dd-topic.md`). - Add the specs index and rewrite every tracked reference to the moved paths; update catalog rows for the relocated documents. - Refresh `docs/public/llms.txt` from the updated docs sources.
 [Low impact] The PR changes how repository documentation is organized and found. The layout migration appears safe to merge, with three non-blocking documentation fixes recommended. Findings
Fix with agent prompt### Issue 1
.agents/specs/connect/spoke-connect.md:797
The new invariant says every denied request leaves session state unchanged. But the detailed serving order and the responder advance the inbound counter before the capability gate. A peer following this summary would fall one request behind after a capability denial and reject the next valid request. Limit the no-advance rule to sequence and envelope-auth failures.
```suggestion
- No op handler runs unless the op's required capability is in `negotiated_capabilities`; every deny path answers the existing wire code and leaves no handler side effect. Sequence and envelope-auth denies leave session state unadvanced; capability denials occur after the inbound counter advances.
```
### Issue 2
AGENTS.md:54
The rewritten reference still names “Session-core parity,” but the replacement ADR has no such section. The remote-adapter spec also cites “Helper boundary” at line 133 of this now 50-line record. Contributors following these references cannot find the cited contract. Restore the detailed contract in a current-state spec and update the references, or point them to the retained sections.
### Issue 3
.agents/specs/connect/connect-csharp-binding.md:57
The new exact count covers only the core subset. The committed C# binding also exposes the remote adapter, router, responder, loopback objects, callbacks and additional errors. This gives maintainers an incomplete checklist for checking regenerated bindings. Label the count as the core subset and point to the complete inventory in the publish spec.
```suggestion
- The generated surface must match the complete FFI inventory in [`connect-publish-strategy.md`](./connect-publish-strategy.md). The core subset has 8 functions, 3 objects and 2 error enums; the full binding also includes the remote-adapter FFI, loopback helpers, callback interfaces and their errors.
```
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.SummaryMoves specs, decision records and reusable knowledge into
Reviews (1) · Last reviewed commit: "docs(harness): migrate corpus to .agents..." · Reviewed by Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Required checks cannot use workflow-level path filters (a skipped check blocks merge), so each heavy job keeps its check run and short-circuits its run steps when a shared `changes` job reports a docs-only diff. Covers CI, the C/C++ carrier lanes and the xcframework lane; the docs build stays unconditional because it validates documentation changes.
✅ Verdict:
|
| Findings | Count |
|---|---|
| 🔴 must-fix | 0 |
| 🟠 should-fix | 0 |
| 🟡 may-fix | 0 |
| 🔵 nit | 0 |
📋 Review
What this PR does: Adopts the current Morning Star corpus layout for this repository: a tracked .mstarc declares harness_dir=.mstar plus knowledge_dir/specs_dir/adr_dir under .agents/, knowledge moves to .agents/knowledge/ via git mv, and specs/ADRs are split into .agents/specs/<class>/<topic>.md (current state) and .agents/adr/implemented/<class>/yyyy-mm-dd-topic.md (one decision with alternatives and consequences). Roughly twenty mixed documents were either moved whole or split into a spec plus a decision record, with every tracked .mstar/specs|knowledge reference rewritten across root docs, docs/, schemas/, packages/crates, tooling and code comments, and the catalog rows and docs:llms output regenerated. The PR claims no wire, schema, package or code-behavior change — documentation corpus and path configuration only.
Findings
none
Revalidated findings
Reassessed 14/15 prior finding(s) this round · 0 invalid-output · 1 omitted · 0 over cap · 15 recheckable · context coverage: truncated
| finding | disposition | evidence | thread |
|---|---|---|---|
| Binding READMEs cite §3.2/§3.3/§3.4/§3.5 of an ADR that has no numbered sections | addressed (verified-fix) | current-code | - |
| Docs-only PRs fail both required C++ carrier lanes: artifact upload is ungated while its staging step is gated | unverifiable (context-incomplete) | - | - |
| New changes job pins actions/checkout by mutable tag in a workflow that pins every other action by SHA | addressed (verified-fix) | current-code | - |
| kotlin-connect-smoke fails on docs-only PRs: unconditional JUnit upload with if-no-files-found: error over a now-gated test step | unverifiable (context-incomplete) | - | - |
| C# binding READMEs still label the spec page a "Decision record" although this PR moved the decision into an ADR | addressed (verified-fix) | current-code | - |
| Broken sentence fragment in the ports pattern leaves the normative port list unparseable | addressed (verified-fix) | current-code | - |
RemoteAdapter spec cites a nonexistent section and line in the TS-route ADR (§Helper boundary …, L133) |
addressed (verified-fix) | current-code | - |
| Docs-only PRs fail the required xcframework check at the always() artifact upload | unverifiable (context-incomplete) | - | - |
| "CoreError-returning exports" row names three exports that cannot return CoreError | addressed (verified-fix) | current-code | - |
| New C# binding spec still says Go/Python/Kotlin bindings are "not started", contradicting the same PR's publish strategy and committed binding packages | unverifiable (context-incomplete) | - | - |
Rewritten FFI CoreError-mirror row lists an export that returns CoreInvokeError, and constructors that return no Result |
addressed (verified-fix) | current-code | - |
| Glossary's new navigation-label rows disagree with the shipped EN sidebar and contradict the table's own frozen row | unverifiable (context-incomplete) | - | - |
| New changes job pins no SHA for actions/checkout while every other action in this workflow is SHA-pinned | unverifiable (context-incomplete) | - | - |
| C# binding spec states the opposite of the shipped binding matrix ("Go / Python / Kotlin: not started") | unverifiable (omitted) | - | - |
| connect-identity gate contradicts its own documented invariant, turning a required proof into a green no-op on docs-only PRs | unverifiable (context-incomplete) | - | - |
Linked-issue AC
none — the PR body lists an empty issues array, so no linked-issue acceptance criteria exist to check off.
✅ Verified
- Prior finding: Binding READMEs cited §3.2/§3.3/§3.4/§3.5 of an ADR with no numbered sections — addressed (verified-fix).
- Prior finding: changes job pinned actions/checkout by mutable tag in an otherwise SHA-pinned workflow — addressed (verified-fix).
- Prior finding: C# binding READMEs still called the spec page a "Decision record" after the decision moved to an ADR — addressed (verified-fix).
- Prior finding: broken sentence fragment in the ports pattern left the normative port list unparseable — addressed (verified-fix).
- Prior finding: RemoteAdapter spec cited a nonexistent section and line in the TS-route ADR (§Helper boundary …, L133) — addressed (verified-fix).
- Prior finding: the "CoreError-returning exports" row named three exports that cannot return CoreError — addressed (verified-fix).
- Prior finding: rewritten FFI CoreError-mirror row listed an export returning CoreInvokeError and constructors returning no Result — addressed (verified-fix).
- ❓ Docs-only PRs may still fail both required C++ carrier lanes (artifact upload ungated, staging step gated) — unverifiable, context incomplete.
- ❓ kotlin-connect-smoke may still fail on docs-only PRs (unconditional JUnit upload with if-no-files-found: error over a now-gated test step) — unverifiable, context incomplete.
- ❓ Docs-only PRs may still fail the required xcframework check at the always() artifact upload — unverifiable, context incomplete.
- ❓ New C# binding spec may still claim Go/Python/Kotlin bindings are "not started", contradicting the same PR's publish strategy and committed binding packages — unverifiable, context incomplete.
- ❓ Glossary navigation-label rows may still disagree with the shipped EN sidebar and the table's own frozen row — unverifiable, context incomplete.
- ❓ changes job may still leave actions/checkout unpinned by SHA where every other action in the workflow is SHA-pinned — unverifiable, context incomplete.
- ❓ connect-identity gate may still contradict its documented invariant, turning a required proof into a green no-op on docs-only PRs — unverifiable, context incomplete.
🗑️ Considered & rejected
none — the review settled no candidate concerns as rejected; the ten prior findings it could check resolved to addressed fixes (7) or context-incomplete leads (7 revalidation rows), and no new finding was raised.
🛠️ Plan to fix
Expand fix plan
none — the review closes with zero must-fix/should-fix/may-fix/nit findings, so there is nothing to fix in this PR; the remaining `❓` lines are revalidation leads lacking diff evidence, not open findings.![wood-s-inspector[bot]](https://avatars.githubusercontent.com/in/4803300?s=60&v=4){kind=small}
Audit of all 52 knowledge documents against the current tree found no retireable entries; 20 carried stale facts, corrected in place: - version pins: base64 0.22 -> 0.23, libp2p 0.57.0 -> 0.57.1, canonicalize 3.0.0 -> 5.1.0; - schema counts 23/24/30/32/34 -> the current 114 constant; - renamed symbols and changed feature wiring: lockstep rewrite helper, `remote-adapter = []`, `ffi-smoke-host`, dev-only fixture dependency; - connect wire: role-aware hello signed set, protocol_version 2 per-envelope authentication, canonicalHelloBytes peerNonce, `/noise` and `/remote` subpaths, five golden-vector copies, C#/Kotlin smoke coverage and committed Swift bindings; - docs inventory and zh nav labels matched to the current site; - removed iteration ids and commit hashes from a tracked knowledge page. No file was retired, so nothing was moved to the local archive.
- connect spec: capability denials occur after the inbound counter advances; only sequence and envelope-auth denies leave session state unadvanced. - restore citable references: AGENTS.md, the RemoteAdapter spec and knowledge pages point at the retained ADR §Decision instead of removed section names and line numbers. - C# binding spec: all five binding channels are landed; the FFI count is labelled as the core subset with the complete inventory in the publish spec. - binding READMEs point at the publish-spec channel facts for packaging and at the ADR for the decision, not at the current-state spec. - CI: keep connect-identity ungated; gate the xcframework, native-carrier and JUnit artifact uploads so a docs-only PR cannot fail on missing artifacts; pin the new `changes` checkouts to the workflow SHA.
Knowledge pages that called a current-state spec a "decision record" now link the ADR that holds the decision and label the spec as the current surface. The publish strategy notes that carrier-lane run steps short-circuit on docs-only diffs.
- Restore the subject of the ports pattern sentence so the normative port list reads as one claim. - Limit the FFI CoreError mirror row to exports whose signature actually returns Result<_, CoreError>. - Re-derive the nav/sidebar glossary EN column from the shipped labels and drop the duplicate multi-peer row.
`check_response_correlation` returns `Result<(), CoreInvokeError>`, not `CoreError`; `OutboundSequence::allocate` and `InboundSequence::advance` also use `CoreInvokeError`. The three sequence/nonce constructors are infallible (`-> Arc<Self>`) and carry no error variant.
Summary
Adopts the current Morning Star corpus layout for this repository.
.mstarc(tracked): declaresharness_dir=.mstarfor process state andknowledge_dir/specs_dir/adr_dirunder.agents/..gitignoreno longer ignores.mstarcor the old.mstar/knowledge|specswhitelist..mstar/knowledge/moved to.agents/knowledge/withgit mv(52 documents + index). Content is unchanged apart from link and renamed-record references..agents/specs/<class>/<topic>.md— current state only, fixed skeleton (Scope/Current state/Invariants/Where it lives/Change obligations), indexed by.agents/specs/README.md..agents/adr/implemented/<class>/yyyy-mm-dd-topic.md— one decision with its real alternatives and consequences. Split from the former mixed docs:connect-binding-channels,spoke-connect-ts-route,spoke-cognition-family,spoke-memory-capability,ke-extraction,ke-ownership-disclosuremoved whole;connect-publish-strategy,connect-cpp-binding,connect-csharp-binding,spoke-remote-adapter,spoke-extension-modulesnow have both a current-state spec and a decision record..mstar/specs|knowledgereference rewritten (root docs,docs/,schemas/, packages/crates, tooling, code comments); relative Markdown links verified against the new tree.rootKind=repositoryanddocumentKind=other.Validation
Notes
No wire, schema, package or code behavior changes — documentation corpus and path configuration only.