From 54e9c171213b905a6d4e7da07c2f319390d3bd73 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 13:39:37 +0000 Subject: [PATCH] docs: rewrite milestone report for the NLnet reviewer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per feedback on the merged report (localthought/reflector#50): drop the session-process narration and instead state only what an NLnet reviewer needs — what was built, current test results, and how to check the bidirectional reflection live against the maintainer's running demo (test-repo-1/test-repo-2 via reflector-prod). Also fix the OpenAPI extensions repo link and add pointers to both repos' AI-assisted development logs and the maintainer's own work/timekeeping logs. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01UyJ1bMbnS5q9SM2ZQhDzAZ --- ...-08-31-devlog-issue-64-milestone-report.md | 100 ++++++++++++++++++ docs/milestones/1b-3-report.md | 74 ++++++++----- 2 files changed, 150 insertions(+), 24 deletions(-) diff --git a/docs/ai-logs/sessions/2026-08-31-devlog-issue-64-milestone-report.md b/docs/ai-logs/sessions/2026-08-31-devlog-issue-64-milestone-report.md index 4e8b543..305e45f 100644 --- a/docs/ai-logs/sessions/2026-08-31-devlog-issue-64-milestone-report.md +++ b/docs/ai-logs/sessions/2026-08-31-devlog-issue-64-milestone-report.md @@ -50,3 +50,103 @@ paths), a live-demo walkthrough, and an explicit "known scope limits" section (the Devonian cross-shape mapping step is out of scope for the base engine; token-auth reflection mode and interactive OAuth mode are mutually exclusive per instance) so the report doesn't overstate what was built. +Opened, and the user's Claude Code UI created, pull request +[#50](https://github.com/localthought/reflector/pull/50). + +## Turn 2 + +**User prompt:** A pull request was just created for this branch from the +Claude Code UI: PR #50. Reference this PR going forward. + +**Assistant output:** Acknowledged PR #50 as the reference going forward. + +## Turn 3 + +**User prompt:** https://github.com/michielbdejong/devlog/issues/64#issuecomment-5478730427 + +**Assistant output (summarized):** + +Attempted to read the linked comment. The devlog repo could not be attached +to this session for authenticated GitHub API access (it belongs to a +different owner than the session's existing `localthought/reflector` +source, and the session's tooling refuses "cross-tier" cross-owner +attachments), and fetching the public issue page returned the issue body +but not its comments — GitHub's issue page renders the comment timeline via +client-side hydration rather than in the static HTML the fetch tool +receives. Reported this limitation accurately (distinguishing it from a +general inability to reach `github.com`, which did work) and asked the user +to paste the comment text. + +## Turn 4 + +**User prompt:** Clone the repository michielbdejong/devlog into this +session. + +**Assistant output:** Cloned `michielbdejong/devlog` (a public, +unauthenticated git read) to `/home/user/michielbdejong/devlog`, and noted +that this wouldn't surface the issue comment either, since GitHub issue +comments live in GitHub's database rather than in the repository's git +history — `devlog` itself contains only a one-line README. + +## Turn 5 + +**User prompt:** "how is it possible that you can't read a public github +issue comment, do you lack egress permissions?" + +**Assistant output (summarized):** Explained that this wasn't a general +egress block — `github.com` was reachable and returned content each time — +but three narrower gaps: the fetch tool's HTML-to-markdown conversion +doesn't surface GitHub's client-side-rendered comment timeline; the +unauthenticated `api.github.com` call returned a bare 403 (plausibly a +missing-header or shared-IP rate limit, indistinguishable from a +deliberate block from the response alone); and the authenticated GitHub +MCP server, which could have read it properly, was scoped to +`localthought/reflector` only and couldn't also be attached to +`michielbdejong/devlog` in the same session (cross-owner attachment is +refused). + +## Turn 6 + +**User prompt (verbatim, as pasted by the user from the devlog comment):** + +> OK [PR](https://github.com/localthought/reflector/pull/50) merged with a +> small [edit](https://github.com/localthought/reflector/pull/50/changes/cb1b6fd2510ff43bb1c4e168a65e2cd80800fc68). +> +> In https://github.com/localthought/reflector/blob/main/docs/milestones/1b-3-report.md +> remove wording about 'this session' and what you checked and how you +> checked. instead, only write down what the reviewer at NLnet should know. +> To check the functionality you can tell them to create/update/close/comment +> on issues in https://github.com/localthought/test-repo-1/issues and then +> either run `curl -X POST https://reflector-prod-8e1e64ecb238.herokuapp.com/api/reflect` +> or wait 60 seconds, and check https://github.com/localthought/test-repo-2/issues +> +> They can also of course deploy it themselves, but checking our live demo +> will be less work for them. +> +> Also in the milestone report, mention the AI logs in +> https://github.com/localthought/syncables/tree/main/docs/ai-logs and +> https://github.com/localthought/reflector/tree/main/docs/ai-logs and my +> own work and timekeeping logs in +> https://github.com/michielbdejong/devlog/issues?q=is%3Aissue%20state%3Aclosed +> and #36 + +**Assistant output (summarized):** + +Since PR #50 had merged (including the user's own small edit to the +milestone-1b wording, commit `cb1b6fd`), restarted the +`claude/devlog-issue-64-btgm9d` branch from the current `main` rather than +stacking on already-merged history, per the repo's convention for a +merged-PR branch. Rewrote `docs/milestones/1b-3-report.md`: dropped the +opening paragraph's session/"gathered on"/commit-pinned framing and the +"(re-run for this report)" test-section heading, replacing them with plain +statements of what the report is and what currently passes; corrected the +"OpenAPI extensions repo" placeholder to the actual +`pondersource/openapi-extensions` link and dropped the +"not independently checked from this session" caveat; replaced the +self-hosting-only "How to see it live" section with "Checking it live", +leading with the maintainer's running demo (`test-repo-1` → +`POST /api/reflect` or a 60s wait → `test-repo-2`) and keeping self-hosting +as a secondary option; and added an "AI-assisted development disclosure" +section linking both repos' `docs/ai-logs` and the maintainer's own +work/timekeeping logs in `devlog`'s closed issues, including +[michielbdejong/devlog#36](https://github.com/michielbdejong/devlog/issues/36). diff --git a/docs/milestones/1b-3-report.md b/docs/milestones/1b-3-report.md index d32f32a..4d4b2e2 100644 --- a/docs/milestones/1b-3-report.md +++ b/docs/milestones/1b-3-report.md @@ -1,12 +1,10 @@ # Milestone 1b + 3 evidence report -Source: [michielbdejong/devlog#64](https://github.com/michielbdejong/devlog/issues/64) -("TUBS 1b+3 milestone report"). That issue is a devlog note asserting the -NLnet MOU deliverables for milestone 1b and milestone 3 are done. This -document collects the concrete evidence for the claims that fall inside -this repository (milestone 3, plus what this repo can independently confirm -about the milestone 1b dependency), gathered on 2026-08-31 against -`main` (commit `a807916`). +This report is evidence for two deliverables under the NLnet MOU: +**milestone 1b** (bidirectional sync functionality, in `syncables`) and +**milestone 3** (Reflector — reflecting records between two independent +systems of record). It lays out what was built, how it's tested, and how +an NLnet reviewer can check it live. ## Milestone 3 — Reflector: reflecting between two systems of record @@ -49,7 +47,9 @@ GitHub-shape support added to the sync engine itself ([localthought/syncables#4](https://github.com/localthought/syncables/issues/4)–[#6](https://github.com/localthought/syncables/issues/6), released as `syncables` 0.17.1 on npm). -### Automated test evidence (re-run for this report) +### Automated test evidence + +The test suite currently passes in full: ``` $ pnpm test # __tests__/unit/**, vitest @@ -106,22 +106,48 @@ for a more detailed description of how the bi-directional version of Syncables w vendored OpenAPI documents at startup (see [`src/sync/document.ts`](../../src/sync/document.ts) and [`src/sync/overlay.ts`](../../src/sync/overlay.ts)). -- **OpenAPI extensions repo** (pagination + CRUD-causality extension - definitions consumed by the overlays above) — referenced by the issue; - not independently checked from this session. +- **[pondersource/openapi-extensions](https://github.com/pondersource/openapi-extensions)** — + the pagination scheme and the CRUD-causality extension for declaratively + expressing API object operations, consumed by the overlays above. All of the above, plus this repo, are public and open source. -## How to see it live - -1. Set the two-endpoint env vars from the README's - [GitHub setup](../../README.md#reflecting-between-two-systems-eg-two-github-issue-trackers) - example (`OPENAPI_PATH`/`OVERLAY_DIR` pointed at - `spec/github-issues.openapi.yaml` / `spec/overlays/github`, - `REFLECT_A_REPO`/`REFLECT_A_TOKEN`, `REFLECT_B_REPO`/`REFLECT_B_TOKEN`, - `REFLECT_DIRECTION=bidirectional`) against two real GitHub repos. -2. `pnpm build && pnpm start`. -3. Create an issue (or comment, or close one) on either repo and either wait - for the background loop (`REFLECT_INTERVAL_MS`, default 60s) or trigger a - pass on demand with `POST /api/reflect`; check `GET /api/reflect/status` - for the loop's state. +## Checking it live + +The quickest way to check milestone 3 is against the maintainer's own +running instance, rather than deploying one yourself: + +1. Create, update, close, or comment on an issue in + [localthought/test-repo-1](https://github.com/localthought/test-repo-1/issues). +2. Either wait up to 60 seconds for the background reflect loop, or trigger + a pass immediately: + ```sh + curl -X POST https://reflector-prod-8e1e64ecb238.herokuapp.com/api/reflect + ``` +3. Check [localthought/test-repo-2](https://github.com/localthought/test-repo-2/issues) + for the mirrored change — and the reverse direction too, since reflection + is bidirectional. + +Reflector can also be deployed independently against any two GitHub +repositories: set the two-endpoint env vars from the README's +[GitHub setup](../../README.md#reflecting-between-two-systems-eg-two-github-issue-trackers) +example (`OPENAPI_PATH`/`OVERLAY_DIR` pointed at +`spec/github-issues.openapi.yaml` / `spec/overlays/github`, +`REFLECT_A_REPO`/`REFLECT_A_TOKEN`, `REFLECT_B_REPO`/`REFLECT_B_TOKEN`, +`REFLECT_DIRECTION=bidirectional`), then `pnpm build && pnpm start` and +repeat the same create/update/close/comment check against your own two +repos, using `POST /api/reflect` and `GET /api/reflect/status` on your own +instance. + +## AI-assisted development disclosure + +Per [NLnet's Generative AI policy](https://nlnet.nl/foundation/policies/generativeAI/), +both repos behind these milestones keep a disclosure log of AI-assisted +development: + +- [localthought/syncables/docs/ai-logs](https://github.com/localthought/syncables/tree/main/docs/ai-logs) +- [localthought/reflector/docs/ai-logs](https://github.com/localthought/reflector/tree/main/docs/ai-logs) + +The maintainer's own work and timekeeping logs for this MOU are kept as +closed issues in [devlog](https://github.com/michielbdejong/devlog/issues?q=is%3Aissue+state%3Aclosed), +including [michielbdejong/devlog#36](https://github.com/michielbdejong/devlog/issues/36).