From 4846d5fe9da69ce34d286f31603500128e8c0c6f Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 7 Sep 2026 13:00:50 +0900 Subject: [PATCH 1/9] docs(agents): preserve maintenance evidence lessons Co-Authored-By: Codex Signed-off-by: Seongho Bae --- AGENTS.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index d1a287a1..a4be1cee 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,23 @@ # AGENTS.md +## Package manager + +- Use the checked-in pnpm version and lock: `pnpm install --frozen-lockfile`, `pnpm typecheck`, `pnpm coverage`, `pnpm build`, `pnpm verify:package`. +- Keep browser dependencies under their separate `tests/browser` lock; do not substitute another Playwright version during evidence collection. + +## Commit attribution + +- Preserve normal signed-off history and include accurate `Co-Authored-By` attribution for the assisting agent. Never invent a human reviewer or another agent's contribution. + +## Maintainer field notes + +- Update this file when completed work establishes a reusable repository-specific lesson. Keep rules concise; link detailed experiments from the existing owner PR and canonical documentation graph. Do not accumulate transient SHAs, run IDs, test counts, credentials, or scheduler snapshots here. +- Freeze source, dependency locks and commit identity during each acceptance acquisition. Record the exact head, packed artifact digest, command, configuration and terminal result; a new head needs new applicable evidence even when archive bytes match. +- Preserve failed attempts and distinguish focused diagnostics from full acceptance. A command after a failed `&&` stage did not run. Recover an expired process handle from logs without inventing an exit code. Under host contention, serialize this maintainer's heavy builds/tests; do not stop other owners' jobs or relax fixtures, deadlines or thresholds. +- Inspect the actual packed editor in its host composition, not only isolated controls. Open screenshots directly across the affected widths, browser engines and editable/read-only/forced-color states; check clipping, focus and document preservation. Geometry assertions alone do not establish visual, touch, IME, translation or full accessibility acceptance. +- Route a shared defect to its existing source owner before changing callers. Keep inherited stack repairs and previous evidence; do not duplicate a toolbar, clipboard, autosave or browser-teardown fix in another lane. +- Follow [release acceptance](https://github.com/ContextualWisdomLab/inkspan/issues/118) and the exact protected release workflow before automatic publication. Registered keys do not satisfy release gates. Inspect secret names and access metadata only; a denied organization-secret listing is not proof of absence. Preserve existing trusted-publishing/provenance policy rather than adding a token fallback, new registry or package solely because a key exists. Verify public artifact digests after publication. + ## Canonical product and architecture authority Protected `main` is Inkspan's implementation authority. Before changing product behavior, public contracts, architecture, security boundaries, tests, release behavior, or integration guidance, start from `docs/README.md` and keep `docs/PRD.md`, `docs/TRD.md`, and `docs/CONTRACTS.md` aligned with the current implementation and accepted ADRs. From 77b761adbb47ad33f78f6bbb04fc72c85f746edd Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 7 Sep 2026 13:22:13 +0900 Subject: [PATCH 2/9] docs(agents): distinguish observed browser request state Co-Authored-By: Codex Signed-off-by: Seongho Bae --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index a4be1cee..489653a8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,6 +16,7 @@ - Preserve failed attempts and distinguish focused diagnostics from full acceptance. A command after a failed `&&` stage did not run. Recover an expired process handle from logs without inventing an exit code. Under host contention, serialize this maintainer's heavy builds/tests; do not stop other owners' jobs or relax fixtures, deadlines or thresholds. - Inspect the actual packed editor in its host composition, not only isolated controls. Open screenshots directly across the affected widths, browser engines and editable/read-only/forced-color states; check clipping, focus and document preservation. Geometry assertions alone do not establish visual, touch, IME, translation or full accessibility acceptance. - Route a shared defect to its existing source owner before changing callers. Keep inherited stack repairs and previous evidence; do not duplicate a toolbar, clipboard, autosave or browser-teardown fix in another lane. +- For intermittent browser teardown failures, capture request-start/finish/failure counts and outstanding requests before closing the page. Zero outstanding public requests does not prove internal network-idle state; do not blame open HMR sockets or remove the external-request guard without causal evidence. - Follow [release acceptance](https://github.com/ContextualWisdomLab/inkspan/issues/118) and the exact protected release workflow before automatic publication. Registered keys do not satisfy release gates. Inspect secret names and access metadata only; a denied organization-secret listing is not proof of absence. Preserve existing trusted-publishing/provenance policy rather than adding a token fallback, new registry or package solely because a key exists. Verify public artifact digests after publication. ## Canonical product and architecture authority From 0c69908a6fd4d8584b37e377f24b2a5d5e221f9d Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 7 Sep 2026 13:40:16 +0900 Subject: [PATCH 3/9] docs(agents): verify browser dependency provenance Co-Authored-By: Codex Signed-off-by: Seongho Bae --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 489653a8..1d8e026b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,7 @@ - Inspect the actual packed editor in its host composition, not only isolated controls. Open screenshots directly across the affected widths, browser engines and editable/read-only/forced-color states; check clipping, focus and document preservation. Geometry assertions alone do not establish visual, touch, IME, translation or full accessibility acceptance. - Route a shared defect to its existing source owner before changing callers. Keep inherited stack repairs and previous evidence; do not duplicate a toolbar, clipboard, autosave or browser-teardown fix in another lane. - For intermittent browser teardown failures, capture request-start/finish/failure counts and outstanding requests before closing the page. Zero outstanding public requests does not prove internal network-idle state; do not blame open HMR sockets or remove the external-request guard without causal evidence. +- Before attributing browser failures to a modified installation, compare the pinned installed module with the exact registry artifact and upstream tag. Keep private state probes diagnostic-only; a reproduced state transition does not prove the original failing event sequence. - Follow [release acceptance](https://github.com/ContextualWisdomLab/inkspan/issues/118) and the exact protected release workflow before automatic publication. Registered keys do not satisfy release gates. Inspect secret names and access metadata only; a denied organization-secret listing is not proof of absence. Preserve existing trusted-publishing/provenance policy rather than adding a token fallback, new registry or package solely because a key exists. Verify public artifact digests after publication. ## Canonical product and architecture authority From f5288e44e9be5b3d17303824900d763db508b501 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 7 Sep 2026 14:39:52 +0900 Subject: [PATCH 4/9] docs(agents): preserve root-scoped scratch ignore boundary Co-Authored-By: Codex Signed-off-by: Seongho Bae --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 1d8e026b..1c4c9abd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,6 +16,7 @@ - Preserve failed attempts and distinguish focused diagnostics from full acceptance. A command after a failed `&&` stage did not run. Recover an expired process handle from logs without inventing an exit code. Under host contention, serialize this maintainer's heavy builds/tests; do not stop other owners' jobs or relax fixtures, deadlines or thresholds. - Inspect the actual packed editor in its host composition, not only isolated controls. Open screenshots directly across the affected widths, browser engines and editable/read-only/forced-color states; check clipping, focus and document preservation. Geometry assertions alone do not establish visual, touch, IME, translation or full accessibility acceptance. - Route a shared defect to its existing source owner before changing callers. Keep inherited stack repairs and previous evidence; do not duplicate a toolbar, clipboard, autosave or browser-teardown fix in another lane. +- Scope external agent scratch-registry ignores to the checkout root; verify both root exclusion and nested source/fixture visibility with `git check-ignore --no-index` before claiming the ignore boundary is correct. - For intermittent browser teardown failures, capture request-start/finish/failure counts and outstanding requests before closing the page. Zero outstanding public requests does not prove internal network-idle state; do not blame open HMR sockets or remove the external-request guard without causal evidence. - Before attributing browser failures to a modified installation, compare the pinned installed module with the exact registry artifact and upstream tag. Keep private state probes diagnostic-only; a reproduced state transition does not prove the original failing event sequence. - Follow [release acceptance](https://github.com/ContextualWisdomLab/inkspan/issues/118) and the exact protected release workflow before automatic publication. Registered keys do not satisfy release gates. Inspect secret names and access metadata only; a denied organization-secret listing is not proof of absence. Preserve existing trusted-publishing/provenance policy rather than adding a token fallback, new registry or package solely because a key exists. Verify public artifact digests after publication. From 5ee2d79ca289c8d4022f38c4249b77d86487619a Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 8 Sep 2026 09:10:23 +0900 Subject: [PATCH 5/9] docs(agents): distinguish mounted UI visual evidence Co-Authored-By: Codex Signed-off-by: Seongho Bae --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 1c4c9abd..d2637746 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,6 +19,7 @@ - Scope external agent scratch-registry ignores to the checkout root; verify both root exclusion and nested source/fixture visibility with `git check-ignore --no-index` before claiming the ignore boundary is correct. - For intermittent browser teardown failures, capture request-start/finish/failure counts and outstanding requests before closing the page. Zero outstanding public requests does not prove internal network-idle state; do not blame open HMR sockets or remove the external-request guard without causal evidence. - Before attributing browser failures to a modified installation, compare the pinned installed module with the exact registry artifact and upstream tag. Keep private state probes diagnostic-only; a reproduced state transition does not prove the original failing event sequence. +- A generic browser harness that only exposes a sanitizer probe does not mount the editor UI; visual acceptance must use a mounted product entry and retain a failed no-mount probe as diagnostic evidence. - Follow [release acceptance](https://github.com/ContextualWisdomLab/inkspan/issues/118) and the exact protected release workflow before automatic publication. Registered keys do not satisfy release gates. Inspect secret names and access metadata only; a denied organization-secret listing is not proof of absence. Preserve existing trusted-publishing/provenance policy rather than adding a token fallback, new registry or package solely because a key exists. Verify public artifact digests after publication. ## Canonical product and architecture authority From a3d1345ee00f29b21a80a332f362b385dde916fe Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 8 Sep 2026 10:09:09 +0900 Subject: [PATCH 6/9] docs(agents): record browser build timeout evidence --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index d2637746..a0ea6085 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,6 +20,7 @@ - For intermittent browser teardown failures, capture request-start/finish/failure counts and outstanding requests before closing the page. Zero outstanding public requests does not prove internal network-idle state; do not blame open HMR sockets or remove the external-request guard without causal evidence. - Before attributing browser failures to a modified installation, compare the pinned installed module with the exact registry artifact and upstream tag. Keep private state probes diagnostic-only; a reproduced state transition does not prove the original failing event sequence. - A generic browser harness that only exposes a sanitizer probe does not mount the editor UI; visual acceptance must use a mounted product entry and retain a failed no-mount probe as diagnostic evidence. +- The browser harness builds every package subpath before serving; measure the complete pinned build envelope and keep `webServer.timeout` above it, otherwise a server timeout is infrastructure evidence rather than a browser assertion. - Follow [release acceptance](https://github.com/ContextualWisdomLab/inkspan/issues/118) and the exact protected release workflow before automatic publication. Registered keys do not satisfy release gates. Inspect secret names and access metadata only; a denied organization-secret listing is not proof of absence. Preserve existing trusted-publishing/provenance policy rather than adding a token fallback, new registry or package solely because a key exists. Verify public artifact digests after publication. ## Canonical product and architecture authority From 4fb71fe68b23c405ac3eedf4045c303dfb3595ac Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 8 Sep 2026 10:29:56 +0900 Subject: [PATCH 7/9] docs(agents): bind validation to checkout and terminal result Co-Authored-By: Codex Signed-off-by: Seongho Bae --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index a0ea6085..2379b413 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,6 +13,7 @@ - Update this file when completed work establishes a reusable repository-specific lesson. Keep rules concise; link detailed experiments from the existing owner PR and canonical documentation graph. Do not accumulate transient SHAs, run IDs, test counts, credentials, or scheduler snapshots here. - Freeze source, dependency locks and commit identity during each acceptance acquisition. Record the exact head, packed artifact digest, command, configuration and terminal result; a new head needs new applicable evidence even when archive bytes match. +- Creating a worktree does not change the command's working directory. Set `workdir` to the target checkout for every install/test/build, verify HEAD there, and wait for its terminal exit code before publishing a pass; retain wrong-directory runs only as diagnostics. - Preserve failed attempts and distinguish focused diagnostics from full acceptance. A command after a failed `&&` stage did not run. Recover an expired process handle from logs without inventing an exit code. Under host contention, serialize this maintainer's heavy builds/tests; do not stop other owners' jobs or relax fixtures, deadlines or thresholds. - Inspect the actual packed editor in its host composition, not only isolated controls. Open screenshots directly across the affected widths, browser engines and editable/read-only/forced-color states; check clipping, focus and document preservation. Geometry assertions alone do not establish visual, touch, IME, translation or full accessibility acceptance. - Route a shared defect to its existing source owner before changing callers. Keep inherited stack repairs and previous evidence; do not duplicate a toolbar, clipboard, autosave or browser-teardown fix in another lane. From 8ed0643134bfd7de0a32650727ca5b35cd702a85 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 8 Sep 2026 10:38:13 +0900 Subject: [PATCH 8/9] docs(agents): correct startup timing evidence rule Co-Authored-By: Codex Signed-off-by: Seongho Bae --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 2379b413..cbc6b873 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,7 +21,7 @@ - For intermittent browser teardown failures, capture request-start/finish/failure counts and outstanding requests before closing the page. Zero outstanding public requests does not prove internal network-idle state; do not blame open HMR sockets or remove the external-request guard without causal evidence. - Before attributing browser failures to a modified installation, compare the pinned installed module with the exact registry artifact and upstream tag. Keep private state probes diagnostic-only; a reproduced state transition does not prove the original failing event sequence. - A generic browser harness that only exposes a sanitizer probe does not mount the editor UI; visual acceptance must use a mounted product entry and retain a failed no-mount probe as diagnostic evidence. -- The browser harness builds every package subpath before serving; measure the complete pinned build envelope and keep `webServer.timeout` above it, otherwise a server timeout is infrastructure evidence rather than a browser assertion. +- Browser startup includes package builds. A watchdog expiry provides only a lower bound on startup time; trace build and readiness separately, and retain a timeout change only after the complete browser acquisition verifies its effect. - Follow [release acceptance](https://github.com/ContextualWisdomLab/inkspan/issues/118) and the exact protected release workflow before automatic publication. Registered keys do not satisfy release gates. Inspect secret names and access metadata only; a denied organization-secret listing is not proof of absence. Preserve existing trusted-publishing/provenance policy rather than adding a token fallback, new registry or package solely because a key exists. Verify public artifact digests after publication. ## Canonical product and architecture authority From 64975a386513ec08422cdf4c5e406f3a5d911008 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 8 Sep 2026 12:18:16 +0900 Subject: [PATCH 9/9] docs(agents): isolate browser acquisition from editor failures Co-Authored-By: Codex Signed-off-by: Seongho Bae --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index cbc6b873..45901a45 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,7 @@ - Before attributing browser failures to a modified installation, compare the pinned installed module with the exact registry artifact and upstream tag. Keep private state probes diagnostic-only; a reproduced state transition does not prove the original failing event sequence. - A generic browser harness that only exposes a sanitizer probe does not mount the editor UI; visual acceptance must use a mounted product entry and retain a failed no-mount probe as diagnostic evidence. - Browser startup includes package builds. A watchdog expiry provides only a lower bound on startup time; trace build and readiness separately, and retain a timeout change only after the complete browser acquisition verifies its effect. +- If browser tests time out before navigation completes, measure blank-page acquisition without Inkspan before changing editor logic. Separate fixture, navigation, assertion and teardown timing; post-timeout snapshots are not passing evidence. Compare trace modes without relaxing network isolation, and account for shared-host load and cache differences. - Follow [release acceptance](https://github.com/ContextualWisdomLab/inkspan/issues/118) and the exact protected release workflow before automatic publication. Registered keys do not satisfy release gates. Inspect secret names and access metadata only; a denied organization-secret listing is not proof of absence. Preserve existing trusted-publishing/provenance policy rather than adding a token fallback, new registry or package solely because a key exists. Verify public artifact digests after publication. ## Canonical product and architecture authority