Skip to content
This repository was archived by the owner on Sep 23, 2026. It is now read-only.

docs: rewrite milestone report for the NLnet reviewer #51

Merged
michielbdejong merged 1 commit into from
Aug 31, 2026
Merged

docs: rewrite milestone report for the NLnet reviewer #51

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 100 additions & 0 deletions docs/ai-logs/sessions/2026-08-31-devlog-issue-64-milestone-report.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
74 changes: 50 additions & 24 deletions docs/milestones/1b-3-report.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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).
Loading