diff --git a/.agents/inbox/2026-10-23-dev-admin-integration.md b/.agents/inbox/2026-10-23-dev-admin-integration.md new file mode 100644 index 00000000..86b6436f --- /dev/null +++ b/.agents/inbox/2026-10-23-dev-admin-integration.md @@ -0,0 +1,42 @@ +# Owner-authorized admin integration still needs independent evidence and post-merge checks + +Date: 2026-10-23. Searched `CLAUDE.md`, the symptom index and the existing +live-ref/transport lesson. Earlier audit notes recorded a non-author approval +blocker. The owner then explicitly authorized leaving `dev` administrator +enforcement disabled permanently, with a high testing bar for agent integration. +This changed the operating authorization; it did not create a non-author review. + +The first integration used the native admin merge for +[PR #157](https://github.com/GraphDone/GraphDone-Core/pull/157); no SSH fallback +was needed. Read-only +verification on 2026-10-23 returned: + +```text +gh pr view 157 --repo GraphDone/GraphDone-Core --json state,headRefOid,mergeCommit,mergedAt +state: MERGED +head: 385e7679fabc60b80cd65cf0a1aa4cdf3d592514 +merge: 9068cd31824991330c6d92196654e53e04e29063 +mergedAt: 2026-10-23T22:22:22Z + +git ls-remote origin refs/heads/dev +9068cd31824991330c6d92196654e53e04e29063 refs/heads/dev +``` + +The merge parents are `8a7de052eb60fe517f45681dc42b5b169d09c660` and the frozen +`385e767` head. Its complete tree `6bf014bcc30eb6e21c0deeae4db9c7d4effeaac2` +equals that validated source. A read-only protection query confirmed +`enforce_admins: false`, configured approval count 1, and force pushes/deletions +disabled. The owner-directed exemption is not an approval record. Post-merge +CI was still running when this lesson was prepared; issue closure remains gated +on its actual result. + +Corrective rule: use the [canonical dev integration playbook](../playbooks/dev-admin-integration.md), +freeze and independently review the diff, preserve failed/passing evidence, +verify source/base/result provenance and complete post-merge checks. Keep the +standing exception scoped to `dev`; do not toggle protection or change identity. +Historical pre-authorization notes remain historical evidence. + +Limits: this authorization does not cover `main`, release or deployment actions, +force pushes, history rewriting, expanded credentials or any other protection +change. The documented docs-only exception requires exhaustive non-document +byte-equivalence proof and independent review; it does not excuse final CI. diff --git a/.agents/issues/INDEX.md b/.agents/issues/INDEX.md index 19aa11f8..4e83a296 100644 --- a/.agents/issues/INDEX.md +++ b/.agents/issues/INDEX.md @@ -9,3 +9,4 @@ | PR `baseRefOid` differs from another PR or the live target branch during merge inventory | [Verify live refs and transport authority before accepting a merge](../inbox/2026-10-23-pr-base-ref-is-not-live-tip.md); compare the actual remote ref and verify the resulting merge head/tree | | `mergePullRequest` refuses a workflow update without OAuth `workflow` scope | [Recorded API refusal and same-account SSH identity check](../inbox/2026-10-23-pr-base-ref-is-not-live-tip.md#a-workflow-scoped-api-refusal-needs-its-own-evidence); authentication alone does not prove write authorization or merge completion | | MCP tool calls succeed but the stdio client reports JSON parse errors from startup, CPU or consistency messages | [Successful MCP calls do not prove a clean stdio protocol](../inbox/2026-10-23-mcp-stdio-diagnostics.md); `packages/mcp-server/tests/neo4j-contract.test.ts` checks real subprocess traffic and stderr diagnostics | +| `dev` has an owner-authorized admin exemption; a review-rule blocker or docs-only change tempts skipping validation | [Dev admin integration playbook](../playbooks/dev-admin-integration.md); [dated authorization and merge evidence](../inbox/2026-10-23-dev-admin-integration.md). Admin authority is not a non-author approval; verify final branch CI before closeout | diff --git a/.agents/playbooks/dev-admin-integration.md b/.agents/playbooks/dev-admin-integration.md new file mode 100644 index 00000000..18201506 --- /dev/null +++ b/.agents/playbooks/dev-admin-integration.md @@ -0,0 +1,75 @@ +# Integrate into dev under the owner's standing admin authorization + +The owner explicitly authorized this policy on **2026-10-23**: leave `dev`'s +administrator enforcement disabled permanently and allow agent-led admin +integration with the validation bar below. This is standing authority for +`dev`, not permission inferred from an admin role. It does not cover `main`, +releases, deployments, identity changes, broader credentials or other protection +changes. Do not re-enable the setting automatically or toggle it per merge. +Later explicit owner instructions supersede this policy. + +## Before integration + +1. Use an isolated worktree and a reviewable PR. Freeze the exact source head + and read the live `dev` ref (`git ls-remote origin refs/heads/dev` or the Git + ref API); PR `baseRefOid` is not proof of the live tip. Record both SHAs and + the complete diff. If either changes, review the resulting composition and + refresh the affected validation before merging. +2. Obtain independent agent review of the exact diff; resolve its findings. + That review is useful evidence, **not a GitHub non-author approval**. The + owner's standing authority permits the admin operation without claiming + that a missing non-author approval was supplied. +3. Pass every applicable merge gate on the intended composition: pinned clean + install, build, types, lint, unit/harness, production audit, and the relevant + browser, disposable-database, runtime/image and installer checks. Runtime, + dependency, workflow or test changes require the full relevant gates. + Inspect actual job/step results; pending, missing, skipped required, flaky or + timeout evidence is not a pass. Keep earlier failures and show the correction + and subsequent evidence; do not make a retry stand in for a fix. +4. Record exact tested revisions, commands, results, review/check links, + remaining limitations and owned-fixture cleanup in the PR. Follow + [TEST_STRATEGY.md](../../docs/quality/TEST_STRATEGY.md). Passing Core gates does + not establish hosted parity or release readiness. + +## Documentation-only reuse + +Runtime results may be reused only after independently reviewing the documents +and proving the complete change set is documentation-only. Record +`git diff --name-status ` and +`git diff --raw --abbrev=40 `; inspect every changed path, +mode and blob against an explicit list of reviewed document paths. All other +tracked content must be byte-identical to the validated revision. A `.md` +extension or a partial path-filtered diff alone is insufficient. Any changed +runtime asset, dependency, workflow, script or test invalidates this exception. +Check links/formatting, retain the provenance proof and independently review +agent instructions as instructions. Final branch CI must still pass. + +## Merge and verify + +Prefer the native PR operation after the checks above: + +```sh +gh pr merge --repo GraphDone/GraphDone-Core --merge --admin --match-head-commit +``` + +Recheck the live base immediately beforehand. If the API credential specifically +refuses a workflow update for missing `workflow` scope, an **already configured, +same-account SSH transport** may perform the already-authorized normal merge. +Record the exact refusal and identity check; authentication alone proves no +write permission. Never use this fallback to defeat a repository policy or +access denial; stop if that is the reason for refusal. Verify the local merge's source/base parents and complete +tree against the reviewed composition, then use an ordinary non-forced push. +A moved base requires renewed composition review, not force. Do not change +accounts, expand scopes, rewrite history or alter protection to make it work. + +Verify the actual remote `dev` commit, ancestry and complete resulting tree; +do not rely only on a command's success or a PR badge. Unexpected parents or +content require renewed review and validation before closeout. Record the resulting +SHA and the administrative operation honestly. Remove only owned temporary +processes, fixtures and credentials while retaining sanitized evidence and +earlier failures. Wait for applicable **post-merge CI on the resulting branch +head** and inspect its results before closing the integration issue. A failure +keeps closeout open and requires a reviewed correction; never erase its evidence. + +Background: [authorization and first verified integration](../inbox/2026-10-23-dev-admin-integration.md), +[live-ref and transport lessons](../inbox/2026-10-23-pr-base-ref-is-not-live-tip.md). diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..ae55fe17 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,23 @@ +# GraphDone-Core agent instructions + +Read [CLAUDE.md](CLAUDE.md) for project and testing conventions. Preserve other +agents' worktrees and use owned disposable fixtures for database/browser work. + +The repository owner's standing authorization dated 2026-10-23 permits +administrative integration into **`dev` only** under the +[admin integration playbook](.agents/playbooks/dev-admin-integration.md). +`dev`'s “enforce rules for administrators” setting is intentionally disabled +permanently; do not automatically restore it or toggle protection for a merge. +Leave every other protection unchanged. Main, releases and deployments are +outside this authorization. + +Prefer a reviewable PR and an exact-head admin merge. Require independent agent +review, the playbook's validation/provenance checks and final branch CI. Admin +authority is not a non-author approval; report which operation actually occurred. +Do not expand credentials, change identity, force-push or rewrite history. + +Search the [symptom index](.agents/issues/INDEX.md) and existing lessons before +adding guidance. Record new incidents in `.agents/inbox/YYYY-MM-DD-.md` +with dated evidence, cause, corrective rule and limits; link the relevant index. +Keep durable procedures in `.agents/playbooks/` and carry notes with the fix +through review. Local notes alone are not published knowledge. diff --git a/CLAUDE.md b/CLAUDE.md index 1003bdc0..c6baae99 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,11 @@ This file provides guidance to Claude Code when working with GraphDone-Core. +Read [AGENTS.md](AGENTS.md) for current integration authority and operational +lessons. Administrative integration into `dev` must follow the +[high-validation-bar playbook](.agents/playbooks/dev-admin-integration.md); +admin merge authority is not a non-author review approval. + ## Project Overview GraphDone is a graph-native management system that reimagines work coordination through dependencies and democratic prioritization rather than hierarchical assignments. Currently in active development (v0.3.1-alpha) with TLS/SSL production readiness. @@ -541,4 +546,4 @@ Use the comprehensive auth system in `tests/lib/auth.ts` for all E2E tests requi "You are building tools that help everyone. Take it seriously, take pride in your work, don't fake tests, we are building open source software which will help people connect with each other and work together." -The future is decentralized, free, and compassionate. This guides all architectural decisions toward democratic coordination rather than hierarchical control. \ No newline at end of file +The future is decentralized, free, and compassionate. This guides all architectural decisions toward democratic coordination rather than hierarchical control. diff --git a/docs/quality/CORE_VALIDATION_2026-10-23.md b/docs/quality/CORE_VALIDATION_2026-10-23.md index 4fe4d8ae..31d5f5f7 100644 --- a/docs/quality/CORE_VALIDATION_2026-10-23.md +++ b/docs/quality/CORE_VALIDATION_2026-10-23.md @@ -1,5 +1,37 @@ # Core merge validation — 2026-10-23 +## Current disposition — 2026-10-23, 22:29 UTC snapshot + +The final frozen PR #157 head +`385e7679fabc60b80cd65cf0a1aa4cdf3d592514` passed public +[CI run 40025965786](https://github.com/GraphDone/GraphDone-Core/actions/runs/40025965786) +and [Comprehensive Test Suite run 40025965837](https://github.com/GraphDone/GraphDone-Core/actions/runs/40025965837). +The independently inspected +[browser artifact 12533273048](https://github.com/GraphDone/GraphDone-Core/actions/runs/40025965786/artifacts/12533273048) +records smoke **6**, new-user **42**, mobile **27** and performance **3** passes; +the separate living-graph suite passed **3**. The completed validation also +records **603 unit passes with 26 explicitly DB-gated skips**, **161 harness +passes** and **9 real disposable-database contract passes**. Required browser +cases did not pass through skips or flaky retries. Earlier failures below remain +part of the record. + +After the owner's explicit standing authorization changed **only `dev` +administrator enforcement**, PR #157 merged through native `--admin` at +`9068cd31824991330c6d92196654e53e04e29063`. Its parents are +`8a7de052eb60fe517f45681dc42b5b169d09c660` and the frozen `385e767` head; +its entire tree `6bf014bcc30eb6e21c0deeae4db9c7d4effeaac2` equals that validated +source. Other protections remain unchanged. This was an owner-authorized +administrative merge, not a non-author approval, deployment or hosted-acceptance +claim. See the [current dev integration policy](../../.agents/playbooks/dev-admin-integration.md). + +Post-merge CI was still running at this snapshot. Final checks on the latest +resulting `dev` head and issue closure are not claimed here; +[issue #156](https://github.com/GraphDone/GraphDone-Core/issues/156) is the +authoritative post-merge/closeout record. The sections below preserve earlier +snapshots: their **PENDING** review/CI wording describes those earlier states, +not a reversal of the confirmed results above. Remaining release limits still +apply. + ## Follow-up: the fresh production audit held final approval The snapshot below remains historical evidence. On the subsequent clean merged