From 5486637b63fc638f7d878d8fa2e026dc2ab06501 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Sat, 11 Jul 2026 09:44:08 +0200 Subject: [PATCH 1/5] plan(ci): lock #611 classifier harness slice --- .../context-pack.md | 46 ++++++++++++ .../drift.md | 3 + .../plan.md | 75 +++++++++++++++++++ .../research.md | 26 +++++++ .../supervisor.md | 21 ++++++ .../worklog.md | 61 +++++++++++++++ 6 files changed, 232 insertions(+) create mode 100644 .llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md create mode 100644 .llm/runs/fix-611-ci-docs-only-md--ci-classifier/drift.md create mode 100644 .llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan.md create mode 100644 .llm/runs/fix-611-ci-docs-only-md--ci-classifier/research.md create mode 100644 .llm/runs/fix-611-ci-docs-only-md--ci-classifier/supervisor.md create mode 100644 .llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md new file mode 100644 index 000000000..e3a238d1f --- /dev/null +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md @@ -0,0 +1,46 @@ +# Context Pack: #611 CI Markdown-only classifier + +## Run Metadata + +| Field | Value | +| --- | --- | +| Run ID | `fix-611-ci-docs-only-md--ci-classifier` | +| Branch | `fix/611-ci-docs-only-md` | +| Current phase | `plan-eval` | +| Archetype | `N/A` | +| Scope overlays | `docs` | + +## Current State + +Research, locked plan, and Design checkpoint are complete against `origin/main` `720fcb7e`; implementation has not started. + +## Completed + +- Loaded harness, PR, tools, docs overlay, gate matrix, and PLAN-EVAL protocol. +- Inspected classifier, tests, source skills, issue #611, branch, and clean worktree. + +## In Progress + +- Commit/open draft PR and obtain opposite-family PLAN-EVAL. + +## Next Steps + +1. PLAN-EVAL PASS. +2. Implement slices 2–3 and run named gates. +3. Obtain IMPL-EVAL and finalize PR status/metadata. + +## Key Decisions + +| Decision | Source | Notes | +| --- | --- | --- | +| Global Markdown/MDX precedence with explicit critical overrides | issue #611 / plan D1 | Covers package/plugin/app README-only diffs. | +| Preserve rename/copy dual-path parsing | issue #611 / plan D2 | Prevents source rename holes. | + +## Drift and Debt + +- Drift: none so far. +- Debt: none. + +## Commits + +- See draft PR commit list and per-slice comments. diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/drift.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/drift.md new file mode 100644 index 000000000..93a3fb23e --- /dev/null +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/drift.md @@ -0,0 +1,3 @@ +# Drift Log: #611 CI Markdown-only classifier + +No drift recorded. Entries are append-only when implementation reality differs from the approved plan or brief. diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan.md new file mode 100644 index 000000000..f7d99d99b --- /dev/null +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan.md @@ -0,0 +1,75 @@ +# Plan: #611 CI Markdown-only classifier + +## Run Metadata + +| Field | Value | +| --- | --- | +| Run ID | `fix-611-ci-docs-only-md--ci-classifier` | +| Branch | `fix/611-ci-docs-only-md` | +| Phase | `plan` | +| Target | repository CI tooling and skill guidance | +| Archetype | `N/A` — no package/plugin public surface | +| Scope overlays | `docs` for skill guidance | + +## Archetype and Doctrine + +No package/plugin archetype or doctrine verdict applies. The classifier is repository workflow tooling; the docs overlay governs the skill edits and generated mirror. + +## Goal + +Classify any non-empty PR diff containing only Markdown/MDX paths as docs-only regardless of directory, while retaining rename-aware conservative behavior and explicit critical-file/workflow overrides; teach PR-opening agents to apply the CI skip labels proactively. + +## Scope + +- Update classifier contract and implementation. +- Add/adjust focused unit regressions for the four requested cases. +- Update `netscript-pr` and the harness draft-PR guidance. +- Regenerate Claude skill mirrors with the repository task. +- Validate tests, scoped type-check, mirror check, and lock hygiene. + +## Non-Scope + +- Workflow YAML behavior, label creation/taxonomy changes, package/plugin code, and full scaffold runtime execution. + +## Locked Decisions + +| ID | Decision | Rationale | +| --- | --- | --- | +| D1 | Markdown/MDX extension is docs-only across directories unless the path is an explicit critical config/workflow path. | This directly implements issue #611 without weakening named escape hatches. | +| D2 | Preserve both sides of renames/copies and classify the combined path set. | Prevents source-to-doc rename holes. | +| D3 | Put proactive PR-label guidance in both PR authoring and harness draft-opening sections. | Both are authoritative entry points named by the brief. | +| D4 | Generate `.claude/skills` only via `deno task agentic:sync-claude`. | Generated mirror policy. | + +## Open-Decision Sweep + +| Decision | Status | Notes | +| --- | --- | --- | +| Whether `apps/**/*.md` is docs-only | resolved now | Yes, under D1. | +| Whether `ci:skip-scaffold` applies to every docs-only PR | safe to defer per PR | Apply when the PR does not need scaffold-static; `ci:full` overrides. | + +## Risk Register + +| Risk | Mitigation | +| --- | --- | +| Extension precedence accidentally makes workflow/config Markdown safe | Keep workflow prefix and `deno.json*`/lock checks ahead of extension classification and test critical paths. | +| Rename hole reintroduced | Keep `parseNameStatus` unchanged and add Markdown rename regression under `packages/`. | +| Generated mirror drift | Run sync task, then check task; never hand-edit mirror files. | +| Lock churn | Compare `deno.lock` before/after and exclude any churn. | + +## Gate Set + +| Order | Gate | Command/check | Expected | +| --- | --- | --- | --- | +| 1 | classifier unit tests | `deno test --no-lock -A .github/scripts/` | PASS | +| 2 | scoped type-check | `deno run --allow-read --allow-run .llm/tools/run-deno-check.ts --root .github/scripts --ext ts,tsx` | PASS | +| 3 | generated mirror | `deno task agentic:sync-claude:check` | PASS | +| 4 | focused format | scoped formatter check on owned TS | PASS | +| 5 | lock hygiene | `git diff -- deno.lock` | empty | + +## Deferred Scope and Debt + +- No architecture debt created. Workflow refactors and label automation remain outside #611. + +## Drift Watch + +- Record any mismatch between requested labels and the checked-in label taxonomy, any unexpected generated files, or test location/command changes. diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/research.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/research.md new file mode 100644 index 000000000..b933cac37 --- /dev/null +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/research.md @@ -0,0 +1,26 @@ +# Research — fix-611-ci-docs-only-md--ci-classifier + +## Re-baseline + +- Carried-in source: issue #611 and the user slice brief. +- Re-derived against `origin/main` @ `720fcb7e3b762c1e9ee5bf51a1371bfeeb6be22f` on 2026-07-11. +- The current classifier explicitly makes `packages/`, `plugins/`, and `apps/` Markdown impacting; current tests encode that old policy. The brief therefore requires a deliberate contract and regression-test reversal. + +## Findings + +| # | Finding | How to verify | +| - | --- | --- | +| 1 | `isDocsOnlyPath` currently applies `isImpacting` before the Markdown allowlist, so `packages/**/README.md` is full CI. | `.github/scripts/ci-classify-changes.ts` and its denylist test | +| 2 | Rename awareness is implemented by `parseNameStatus`, which returns both old and new paths for `R*`/`C*`. | `parseNameStatus` and rename regression tests | +| 3 | `deno.json*`, `deno.lock`, and workflow paths already force full classification. | `isImpacting` and impacting-surface tests | +| 4 | `netscript-pr` has path-filter guidance, but it does not proactively require both skip labels for eligible docs-only PRs. | `.agents/skills/netscript-pr/SKILL.md` | +| 5 | `netscript-harness` contains a draft-PR-opening section and therefore also needs the proactive-label reminder requested by the brief. | `.agents/skills/netscript-harness/SKILL.md` | + +## jsr-audit surface scan + +- N/A: this is repository CI tooling and agent guidance, not a package/plugin publish surface. + +## Open questions + +- Resolved: Markdown/MDX takes precedence over directory-impact prefixes, except the explicit critical files/workflows named by #611. +- Resolved: a rename is docs-only only when every old/new path returned by rename-aware parsing is Markdown/MDX or otherwise docs-only and no critical path is present. diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/supervisor.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/supervisor.md new file mode 100644 index 000000000..16a1a16fb --- /dev/null +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/supervisor.md @@ -0,0 +1,21 @@ +# Supervisor Identity — fix-611-ci-docs-only-md--ci-classifier + +| Field | Value | +| --- | --- | +| Model | Codex GPT-5 | +| Session | current Codex workspace session | +| Host | YogaBook9i / Linux / codex | +| Checkout | `/home/codex/repos/netscript-611-ciclassify` | +| Worktree | `/home/codex/repos/netscript-611-ciclassify` | +| Branch | `fix/611-ci-docs-only-md` | +| Baseline | `720fcb7e3b762c1e9ee5bf51a1371bfeeb6be22f` (`origin/main`, 2026-07-11) | +| Run ID | `fix-611-ci-docs-only-md--ci-classifier` | + +## Routes in force + +| Task lane | Provider / model / effort | Role in this run | +| --- | --- | --- | +| small fix / fast iteration | Codex / configured GPT implementation route / max | research, plan, implementation, supervision | +| review of GPT implementation | Claude / configured opposite-family review route / high | PLAN-EVAL and IMPL-EVAL | + +Reference `.llm/harness/workflow/lane-policy.md`; no route override is planned. diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md new file mode 100644 index 000000000..3f397f732 --- /dev/null +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md @@ -0,0 +1,61 @@ +# Worklog: #611 CI Markdown-only classifier + +## Run Metadata + +| Field | Value | +| --- | --- | +| Run ID | `fix-611-ci-docs-only-md--ci-classifier` | +| Branch | `fix/611-ci-docs-only-md` | +| Archetype | `N/A` | +| Scope overlays | `docs` | + +## Design + +### Public Surface + +- `isDocsOnlyPath`, `decide`, and `parseNameStatus` remain the classifier/test entry points. +- PR-opening guidance in the two source skills; `.claude/skills` is generated output. + +### Domain Vocabulary + +- docs-only diff — non-empty changed-path set whose every path is allowed documentation. +- critical path — workflow or Deno configuration/lock path that forces full classification. +- rename-aware path set — both source and destination paths for renames/copies. + +### Ports + +- None; pure classifier and checked-in documentation. + +### Constants + +- Existing `IMPACTING_PREFIXES`, `IMPACTING_EXACT`, `DOCS_EXTENSIONS`; refine semantics without new abstraction. + +### Commit Slices + +| # | Slice | Gate | Files | +| - | --- | --- | --- | +| 1 | Harness plan establishes the reviewed contract and draft PR | PLAN-EVAL | `.llm/runs/fix-611-ci-docs-only-md--ci-classifier/*` | +| 2 | Classifier proves global Markdown/MDX docs-only behavior and critical-path safety | focused tests + scoped check | `.github/scripts/ci-classify-changes.ts`, `.github/scripts/ci-classify-changes.test.ts`, run artifacts | +| 3 | PR/harness guidance and generated mirrors prove proactive CI label handling | sync + sync check | source skills, generated Claude mirrors, run artifacts | + +### Deferred Scope + +- Workflow/label automation changes are outside #611. + +### Contributor Path + +Edit the pure path predicates and add a table-style regression in `ci-classify-changes.test.ts`; edit only `.agents/skills` sources and regenerate mirrors. + +## Progress Log + +| Time | Slice | Step | Notes | +| --- | --- | --- | --- | +| 2026-07-11 | 1 | research/plan | Re-baselined at `origin/main`; awaiting separate PLAN-EVAL. | + +## Gate Results + +Not run before PLAN-EVAL. + +## Handoff Notes + +- PLAN-EVAL should scrutinize Markdown precedence versus explicit workflow/Deno critical paths and the rename-old-path behavior. From dc1dd3b5e175eb94fd4c6cb619884a2c213786f5 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Sat, 11 Jul 2026 09:47:33 +0200 Subject: [PATCH 2/5] gate(ci): approve #611 classifier plan --- .../context-pack.md | 12 +++--- .../drift.md | 10 ++++- .../plan-eval.md | 37 +++++++++++++++++++ .../plan.md | 1 + .../worklog.md | 3 +- 5 files changed, 55 insertions(+), 8 deletions(-) create mode 100644 .llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan-eval.md diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md index e3a238d1f..91419cd26 100644 --- a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md @@ -6,28 +6,28 @@ | --- | --- | | Run ID | `fix-611-ci-docs-only-md--ci-classifier` | | Branch | `fix/611-ci-docs-only-md` | -| Current phase | `plan-eval` | +| Current phase | `implement` | | Archetype | `N/A` | | Scope overlays | `docs` | ## Current State -Research, locked plan, and Design checkpoint are complete against `origin/main` `720fcb7e`; implementation has not started. +Research, locked plan, Design checkpoint, and separate-session PLAN-EVAL are complete against `origin/main` `720fcb7e`; implementation is unlocked. ## Completed - Loaded harness, PR, tools, docs overlay, gate matrix, and PLAN-EVAL protocol. - Inspected classifier, tests, source skills, issue #611, branch, and clean worktree. +- Separate Claude Opus PLAN-EVAL returned `PASS` in `plan-eval.md`. ## In Progress -- Commit/open draft PR and obtain opposite-family PLAN-EVAL. +- Classifier implementation and focused regressions. ## Next Steps -1. PLAN-EVAL PASS. -2. Implement slices 2–3 and run named gates. -3. Obtain IMPL-EVAL and finalize PR status/metadata. +1. Implement slices 2–3 and run named gates. +2. Obtain IMPL-EVAL and finalize PR status/metadata. ## Key Decisions diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/drift.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/drift.md index 93a3fb23e..d36705af4 100644 --- a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/drift.md +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/drift.md @@ -1,3 +1,11 @@ # Drift Log: #611 CI Markdown-only classifier -No drift recorded. Entries are append-only when implementation reality differs from the approved plan or brief. +## 2026-07-11 — milestone mapping follows current repository roadmap + +- **What:** PR #613 uses milestone `0.0.1-beta.7`. +- **Source:** live milestone list queried during PR bootstrap. +- **Expected:** the PR skill names `0.0.1-beta.1` as its beta milestone example/target. +- **Actual:** `0.0.1-beta.1` is absent; current open beta milestones start later, and #611 was filed during beta.6 wrap-up, so the next beta is `0.0.1-beta.7`. +- **Severity:** minor +- **Action:** accept +- **Evidence:** PR #613 milestone and `gh api repos/rickylabs/netscript/milestones`. diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan-eval.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan-eval.md new file mode 100644 index 000000000..e7e10275e --- /dev/null +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan-eval.md @@ -0,0 +1,37 @@ +# PLAN-EVAL — fix-611-ci-docs-only-md--ci-classifier + +- Plan evaluator session: Claude (opposite-family, local) / 2026-07-11 +- Run: `fix-611-ci-docs-only-md--ci-classifier` +- Surface / archetype: repository CI classifier tooling + agent skill guidance; archetype `N/A` (no package/plugin public surface) +- Scope overlays: `docs` (skill guidance + run artifacts) + +## Checklist results + +| Plan-Gate item | Result | Evidence / location | +| --------------------------------------- | ------ | ------------------- | +| Research present and current | PASS | `research.md` re-baselined against `origin/main` @ `720fcb7e` (matches `supervisor.md` baseline). Spot-checked finding #1: `.github/scripts/ci-classify-changes.ts:69-95` confirms `isDocsOnlyPath` runs `isImpacting` (packages/plugins/apps denylist) before the docs allowlist, so `packages/**/*.md` is currently full CI. Confirmed the old policy is encoded in tests: `ci-classify-changes.test.ts:110-112` asserts `packages/cli/README.md`, `plugins/workers/CHANGELOG.md`, `apps/demo/README.md` are `false`. Finding #2 (`parseNameStatus` both-sides rename awareness) confirmed at `:236-256`. | +| Decisions locked | PASS | `plan.md` §Locked Decisions D1–D4, each with rationale (markdown precedence, rename both-sides, dual-surface PR guidance, generated-mirror-only edits). | +| Open-decision sweep | PASS | `plan.md` §Open-Decision Sweep lists `apps/**/*.md` (resolved now) and `ci:skip-scaffold` per-PR applicability (safe to defer — label application carries no code dependency). Evaluator sweep below found no unflagged rework-forcing decision. | +| Commit slices (< 30, gate + files each) | PASS | `worklog.md` §Commit Slices: 3 ordered slices. Slice 2 gate = focused tests + scoped check, files = `ci-classify-changes.ts`/`.test.ts` + artifacts; Slice 3 gate = sync + sync check, files = source skills + generated mirrors. `<30`. | +| Risk register | PASS | `plan.md` §Risk Register: 4 risks w/ mitigations — extension-precedence leaking config/workflow, rename hole, mirror drift, lock churn. | +| Gate set selected | PASS | `plan.md` §Gate Set: 5 gates (unit tests, scoped `run-deno-check.ts`, `agentic:sync-claude:check`, focused fmt, `git diff -- deno.lock`). Verified `agentic:sync-claude`/`:check` tasks exist in `deno.json:51-52`. Release-gate class is `n/a`: run changes the classifier that *decides* scaffold gating, not scaffold output / plugin scaffold / DB / Aspire / published CLI shape. Docs-overlay coverage noted as advisory below. | +| Deferred scope explicit | PASS | `plan.md` §Non-Scope + §Deferred Scope and Debt (workflow YAML, label taxonomy/automation, package code, full scaffold runtime; no arch debt created). | +| jsr-audit surface scan (pkg/plugin) | N/A | `research.md` §jsr-audit surface scan marks N/A with reason: repository CI tooling + agent guidance, not a package/plugin publish surface. Correct — no `packages/`/`plugins/` source is touched. | + +## Open-decision sweep (evaluator-run) + +None that force rework if deferred. Independent checks: + +- **Markdown vs. critical-path precedence** — resolved: `research.md` open-questions and Risk #1 keep the `.github/workflows/` prefix and `deno.json*`/`deno.lock` exact/basename checks *ahead* of the extension classification. Those criticals are never `.md`/`.mdx`, so extension-precedence cannot make them docs-safe; the ordering is a belt-and-suspenders guard, not a live hole. +- **Rename where one side is impacting** (`packages/x.ts -> docs/x.md`) — locked by D2 + preserved `parseNameStatus`; combined-set classification keeps the impacting source path. Existing regression at `ci-classify-changes.test.ts:14-16` pins it. +- **Non-markdown files under docs prefixes / non-markdown under `packages/`** — reorder only elevates the `.md`/`.mdx` extension; `.llm/*.ts` etc. stay docs via prefix, `packages/**/*.ts` stay impacting. No unintended reclassification. +- **Test-reversal is contract work, not an open decision** — `research.md` §Re-baseline explicitly flags that `:110-112` must invert; this is planned slice-2 work, correctly surfaced rather than deferred. + +## Verdict + +`PASS` + +## Notes + +- Advisory (not blocking): the `docs` overlay's Source-alignment / Link-integrity / Terminology gates for the two skill edits are not itemized as explicit rows in the §Gate Set table. They are implicitly covered by the `agentic:sync-claude:check` mirror gate (the dominant docs risk here) plus IMPL-EVAL review, and `drift.md` is initialized. For two small proactive-label additions this is acceptable; IMPL-EVAL should still confirm any local paths added to the skills resolve and terminology matches `.claude/09-glossary.md`. +- Implementation reminder for slice 2 (for IMPL-EVAL, not a plan defect): reversing `isDocsOnlyPath` must keep `isImpacting`'s exact/basename `deno.json*`/`deno.lock` and `.github/workflows/` checks authoritative while demoting the `packages/`/`plugins/`/`apps/` *prefixes* below the `.md`/`.mdx` extension test — and the module header contract comment (`ci-classify-changes.ts:11-20`) must be rewritten, since it currently states the denylist "ALWAYS wins ... even if it is a Markdown file," which D1 reverses. diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan.md index f7d99d99b..cbd539baf 100644 --- a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan.md +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan.md @@ -65,6 +65,7 @@ Classify any non-empty PR diff containing only Markdown/MDX paths as docs-only r | 3 | generated mirror | `deno task agentic:sync-claude:check` | PASS | | 4 | focused format | scoped formatter check on owned TS | PASS | | 5 | lock hygiene | `git diff -- deno.lock` | empty | +| 6 | docs overlay | manual source alignment, local-link existence, and terminology review | PASS | ## Deferred Scope and Debt diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md index 3f397f732..a270736ba 100644 --- a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md @@ -51,10 +51,11 @@ Edit the pure path predicates and add a table-style regression in `ci-classify-c | Time | Slice | Step | Notes | | --- | --- | --- | --- | | 2026-07-11 | 1 | research/plan | Re-baselined at `origin/main`; awaiting separate PLAN-EVAL. | +| 2026-07-11 | 1 | PLAN-EVAL | Separate Claude Opus evaluator returned `PASS`; implementation unlocked. | ## Gate Results -Not run before PLAN-EVAL. +- PLAN-EVAL — `PASS`; see `plan-eval.md`. ## Handoff Notes From 34b33781e9af649ae259b004510ea5efb27f455f Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Sat, 11 Jul 2026 09:48:44 +0200 Subject: [PATCH 3/5] fix(ci): prove markdown-only diffs skip e2e --- .github/scripts/ci-classify-changes.test.ts | 56 +++++++++++++++++-- .github/scripts/ci-classify-changes.ts | 26 ++++++--- .../context-pack.md | 19 ++++++- .../worklog.md | 8 ++- 4 files changed, 93 insertions(+), 16 deletions(-) diff --git a/.github/scripts/ci-classify-changes.test.ts b/.github/scripts/ci-classify-changes.test.ts index 3882f7d25..e445289c6 100644 --- a/.github/scripts/ci-classify-changes.test.ts +++ b/.github/scripts/ci-classify-changes.test.ts @@ -47,6 +47,16 @@ Deno.test('parseNameStatus: docs-to-docs rename stays docs-only', () => { assertEquals(d.runRuntime, false); }); +Deno.test('rename of a Markdown file under packages stays docs-only', () => { + const files = parseNameStatus( + 'R100\tpackages/cli/OLD_README.md\tpackages/cli/README.md', + ); + const d = decide({ eventName: 'pull_request', files, labels: [] }); + assertEquals(d.docsOnly, true); + assertEquals(d.runStatic, false); + assertEquals(d.runRuntime, false); +}); + Deno.test('parseNameStatus: unrecognisable line degrades to a bare path (forces run)', () => { const files = parseNameStatus('something-weird-without-tab'); assertEquals(files, ['something-weird-without-tab']); @@ -105,11 +115,14 @@ Deno.test('docs surfaces are docs-only', () => { } }); -Deno.test('denylist wins over the markdown allowlist', () => { - // Markdown under an impacting prefix must NOT be docs-only. - assertEquals(isDocsOnlyPath('packages/cli/README.md'), false); - assertEquals(isDocsOnlyPath('plugins/workers/CHANGELOG.md'), false); - assertEquals(isDocsOnlyPath('apps/demo/README.md'), false); +Deno.test('Markdown is docs-only under ordinary impacting directories', () => { + assertEquals(isDocsOnlyPath('packages/cli/README.md'), true); + assertEquals(isDocsOnlyPath('plugins/workers/CHANGELOG.md'), true); + assertEquals(isDocsOnlyPath('apps/demo/README.mdx'), true); +}); + +Deno.test('critical workflow paths win over the markdown allowlist', () => { + assertEquals(isDocsOnlyPath('.github/workflows/README.md'), false); }); Deno.test('impacting surfaces force the gate', () => { @@ -148,6 +161,39 @@ Deno.test('decide: docs-only PR skips both jobs', () => { assertEquals(d.runRuntime, false); }); +Deno.test('decide: Markdown-only diff under packages is docs-only', () => { + const d = decide({ + eventName: 'pull_request', + files: ['packages/cli/README.md', 'packages/sdk/guides/setup.mdx'], + labels: [], + }); + assertEquals(d.docsOnly, true); + assertEquals(d.runStatic, false); + assertEquals(d.runRuntime, false); +}); + +Deno.test('decide: Markdown plus one TypeScript file is full', () => { + const d = decide({ + eventName: 'pull_request', + files: ['packages/cli/README.md', 'packages/cli/mod.ts'], + labels: [], + }); + assertEquals(d.docsOnly, false); + assertEquals(d.runStatic, true); + assertEquals(d.runRuntime, true); +}); + +Deno.test('decide: Markdown plus deno.lock is full', () => { + const d = decide({ + eventName: 'pull_request', + files: ['packages/cli/README.md', 'deno.lock'], + labels: [], + }); + assertEquals(d.docsOnly, false); + assertEquals(d.runStatic, true); + assertEquals(d.runRuntime, true); +}); + Deno.test('decide: one code file forces both jobs', () => { const d = decide({ eventName: 'pull_request', diff --git a/.github/scripts/ci-classify-changes.ts b/.github/scripts/ci-classify-changes.ts index f9e841d14..5bb16eb69 100644 --- a/.github/scripts/ci-classify-changes.ts +++ b/.github/scripts/ci-classify-changes.ts @@ -10,12 +10,10 @@ * * Design contract (see PR "ci: docs-only + label-gated skip lanes"): * - * - A file is "docs-only" (non-impacting for the scaffold/e2e gate) iff it - * matches the docs allowlist AND does NOT match the impacting denylist. - * - The denylist ALWAYS wins: anything under `packages/`, `plugins/`, `apps/`, - * any `deno.json*` / `deno.lock`, or `.github/workflows/**` is treated as - * impacting even if it is a Markdown file. This honours the hard rule that - * those surfaces must never be classified docs-only. + * - Markdown / MDX is docs-only regardless of directory, except for explicit + * critical paths (`deno.json*`, `deno.lock`, workflows), which always win. + * - Non-Markdown paths under `packages/`, `plugins/`, and `apps/` remain + * impacting; known documentation/agent-context directories remain allowed. * - `docsOnly` is true only when there is at least one changed file and every * changed file is docs-only. * @@ -57,7 +55,7 @@ const DOCS_PREFIXES = [ '.claude/', ] as const; -/** Extensions that are docs-only wherever they live (subject to the denylist). */ +/** Extensions that are docs-only wherever they live (subject to critical paths). */ const DOCS_EXTENSIONS = ['.md', '.mdx'] as const; /** Normalise a git path: strip a leading `./`, collapse backslashes. */ @@ -77,6 +75,14 @@ export function isImpacting(rawPath: string): boolean { return IMPACTING_PREFIXES.some((prefix) => path.startsWith(prefix)); } +/** Does this explicit configuration/workflow path always force the gate? */ +function isCritical(rawPath: string): boolean { + const path = normalise(rawPath); + const base = path.slice(path.lastIndexOf('/') + 1); + return path.startsWith('.github/workflows/') || + base === 'deno.json' || base === 'deno.jsonc' || base === 'deno.lock'; +} + /** Is this path a docs-only surface (only meaningful when not impacting)? */ export function isDocs(rawPath: string): boolean { const path = normalise(rawPath); @@ -86,10 +92,12 @@ export function isDocs(rawPath: string): boolean { } /** - * True iff `path` is docs-only: matches the docs allowlist and is not on the - * impacting denylist (denylist wins). + * True iff `path` is docs-only. Explicit critical paths win; Markdown / MDX + * then wins over ordinary impacting directory prefixes. */ export function isDocsOnlyPath(path: string): boolean { + if (isCritical(path)) return false; + if (DOCS_EXTENSIONS.some((ext) => normalise(path).endsWith(ext))) return true; if (isImpacting(path)) return false; return isDocs(path); } diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md index 91419cd26..2215b3c97 100644 --- a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md @@ -19,10 +19,11 @@ Research, locked plan, Design checkpoint, and separate-session PLAN-EVAL are com - Loaded harness, PR, tools, docs overlay, gate matrix, and PLAN-EVAL protocol. - Inspected classifier, tests, source skills, issue #611, branch, and clean worktree. - Separate Claude Opus PLAN-EVAL returned `PASS` in `plan-eval.md`. +- Classifier slice implemented with all 30 focused tests and scoped check/format green. ## In Progress -- Classifier implementation and focused regressions. +- Skill guidance and generated mirrors. ## Next Steps @@ -36,6 +37,22 @@ Research, locked plan, Design checkpoint, and separate-session PLAN-EVAL are com | Global Markdown/MDX precedence with explicit critical overrides | issue #611 / plan D1 | Covers package/plugin/app README-only diffs. | | Preserve rename/copy dual-path parsing | issue #611 / plan D2 | Prevents source rename holes. | +## Files Changed + +| Path | Status | Notes | +| --- | --- | --- | +| `.github/scripts/ci-classify-changes.ts` | changed | Critical-path guard precedes global Markdown/MDX classification. | +| `.github/scripts/ci-classify-changes.test.ts` | changed | Requested mixed/lock/package/rename regressions. | + +## Gates + +| Gate family | Current status | Evidence | +| --- | --- | --- | +| Static | PASS | 30 tests; scoped check and format checks green. | +| Fitness | N/A | No package/plugin surface. | +| Runtime | N/A | Pure classifier tests cover behavior. | +| Consumer | pending | Claude mirror sync/check remains. | + ## Drift and Debt - Drift: none so far. diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md index a270736ba..139bd3941 100644 --- a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md @@ -52,11 +52,17 @@ Edit the pure path predicates and add a table-style regression in `ci-classify-c | --- | --- | --- | --- | | 2026-07-11 | 1 | research/plan | Re-baselined at `origin/main`; awaiting separate PLAN-EVAL. | | 2026-07-11 | 1 | PLAN-EVAL | Separate Claude Opus evaluator returned `PASS`; implementation unlocked. | +| 2026-07-11 | 2 | implementation | Global Markdown/MDX precedence added after critical-path guard; rename parsing preserved. | +| 2026-07-11 | 2 | gates | 30 classifier tests, scoped check, and scoped format check passed. | +| 2026-07-11 | 2 | reconcile | Issue #611 remains open; PR #613 has `Closes #611`, parent/motivating refs, beta.7 milestone, and `status:plan-eval` pending phase transition. No new comments required readjustment. | ## Gate Results - PLAN-EVAL — `PASS`; see `plan-eval.md`. +- Classifier tests — `PASS` (30 passed, 0 failed). +- Scoped check (`.github/scripts`, TS/TSX) — `PASS` (2 files, 0 findings). +- Scoped format check (`.github/scripts`, TS/TSX) — `PASS` (2 files, 0 findings). ## Handoff Notes -- PLAN-EVAL should scrutinize Markdown precedence versus explicit workflow/Deno critical paths and the rename-old-path behavior. +- IMPL-EVAL should scrutinize Markdown precedence versus explicit workflow/Deno critical paths and the rename-old-path behavior. From 9279e40cf008761ce28e6041f67d361dd3f13a34 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Sat, 11 Jul 2026 09:50:03 +0200 Subject: [PATCH 4/5] docs(agent): guide docs-only CI skip labels --- .agents/skills/netscript-harness/SKILL.md | 5 +++++ .agents/skills/netscript-pr/SKILL.md | 10 +++++++--- .claude/skills/netscript-harness/SKILL.md | 5 +++++ .claude/skills/netscript-pr/SKILL.md | 10 +++++++--- .../context-pack.md | 15 +++++++++------ .../worklog.md | 6 ++++++ 6 files changed, 39 insertions(+), 12 deletions(-) diff --git a/.agents/skills/netscript-harness/SKILL.md b/.agents/skills/netscript-harness/SKILL.md index e69691be8..a0726ce6e 100644 --- a/.agents/skills/netscript-harness/SKILL.md +++ b/.agents/skills/netscript-harness/SKILL.md @@ -83,6 +83,11 @@ intent hint, not the final profile. 11. **Run IMPL-EVAL (separate session).** 12. Close: update `context-pack.md`, `arch-debt.md`, and promote lessons if warranted. +When the opening diff is docs-only, proactively apply `ci:skip-e2e` to the draft PR and also apply +`ci:skip-scaffold` when scaffold-static is not applicable. Use `ci:full` as the escape hatch when +the docs-only change must exercise the full CI surface. Record the selection in the opening phase +comment so the evaluator can verify that the cheap lane is intentional. + ## Agent Delegation Contract Lane assignments and model bindings are configuration. The tiered A–E model, the selection rules diff --git a/.agents/skills/netscript-pr/SKILL.md b/.agents/skills/netscript-pr/SKILL.md index 83840a5f7..7e7374d59 100644 --- a/.agents/skills/netscript-pr/SKILL.md +++ b/.agents/skills/netscript-pr/SKILL.md @@ -228,7 +228,8 @@ a board column reflect reality. - `area:` — `cli`, `fresh`, `fresh-ui`, `plugins`, `auth`, `deps`, `aspire`, `tooling`, `database`, `kv`, `sdk`, `service`, `config`, `telemetry`, `ai-core`, `plugin-ai`, `docs` - `priority:` — `p0` (release blocker), `p1`, `p2`, `p3` -- `ci:` — `skip-e2e`, `full` (manual overrides for the path-filtered CI); `gate:` — `e2e`, `jsr` +- `ci:` — `skip-e2e`, `skip-scaffold`, `full` (manual overrides for the path-filtered CI); + `gate:` — `e2e`, `jsr` - `epic:` — groups every issue/PR belonging to a program epic (e.g. `epic:ai-stack`, `epic:deployment`); the epic's own umbrella issue carries `type:umbrella`. - `wave:` — scheduling band that drives the **milestone** (see below): `v1`, `v1-min`, `defer`. @@ -307,5 +308,8 @@ human-facing mirror; `.github/labels.yml` is the machine-readable label set. ## Path-filter awareness (Phase C) -Config/docs-only PRs are auto-skipped by CI `paths-ignore`; override with `ci:full` when a docs PR -must run e2e, or `ci:skip-e2e` to suppress it. Don't fight the filter by editing workflows per-PR. +When opening a docs-only PR, proactively apply `ci:skip-e2e`. Also apply `ci:skip-scaffold` when the +change does not need the scaffold-static gate. These labels make the intended cheap lane explicit +even when path classification would auto-skip the jobs. Apply `ci:full` instead when a docs-only PR +must exercise the full CI surface; it is the precedence-winning escape hatch. Don't fight the +filter by editing workflows per PR. diff --git a/.claude/skills/netscript-harness/SKILL.md b/.claude/skills/netscript-harness/SKILL.md index e69691be8..a0726ce6e 100644 --- a/.claude/skills/netscript-harness/SKILL.md +++ b/.claude/skills/netscript-harness/SKILL.md @@ -83,6 +83,11 @@ intent hint, not the final profile. 11. **Run IMPL-EVAL (separate session).** 12. Close: update `context-pack.md`, `arch-debt.md`, and promote lessons if warranted. +When the opening diff is docs-only, proactively apply `ci:skip-e2e` to the draft PR and also apply +`ci:skip-scaffold` when scaffold-static is not applicable. Use `ci:full` as the escape hatch when +the docs-only change must exercise the full CI surface. Record the selection in the opening phase +comment so the evaluator can verify that the cheap lane is intentional. + ## Agent Delegation Contract Lane assignments and model bindings are configuration. The tiered A–E model, the selection rules diff --git a/.claude/skills/netscript-pr/SKILL.md b/.claude/skills/netscript-pr/SKILL.md index 83840a5f7..7e7374d59 100644 --- a/.claude/skills/netscript-pr/SKILL.md +++ b/.claude/skills/netscript-pr/SKILL.md @@ -228,7 +228,8 @@ a board column reflect reality. - `area:` — `cli`, `fresh`, `fresh-ui`, `plugins`, `auth`, `deps`, `aspire`, `tooling`, `database`, `kv`, `sdk`, `service`, `config`, `telemetry`, `ai-core`, `plugin-ai`, `docs` - `priority:` — `p0` (release blocker), `p1`, `p2`, `p3` -- `ci:` — `skip-e2e`, `full` (manual overrides for the path-filtered CI); `gate:` — `e2e`, `jsr` +- `ci:` — `skip-e2e`, `skip-scaffold`, `full` (manual overrides for the path-filtered CI); + `gate:` — `e2e`, `jsr` - `epic:` — groups every issue/PR belonging to a program epic (e.g. `epic:ai-stack`, `epic:deployment`); the epic's own umbrella issue carries `type:umbrella`. - `wave:` — scheduling band that drives the **milestone** (see below): `v1`, `v1-min`, `defer`. @@ -307,5 +308,8 @@ human-facing mirror; `.github/labels.yml` is the machine-readable label set. ## Path-filter awareness (Phase C) -Config/docs-only PRs are auto-skipped by CI `paths-ignore`; override with `ci:full` when a docs PR -must run e2e, or `ci:skip-e2e` to suppress it. Don't fight the filter by editing workflows per-PR. +When opening a docs-only PR, proactively apply `ci:skip-e2e`. Also apply `ci:skip-scaffold` when the +change does not need the scaffold-static gate. These labels make the intended cheap lane explicit +even when path classification would auto-skip the jobs. Apply `ci:full` instead when a docs-only PR +must exercise the full CI surface; it is the precedence-winning escape hatch. Don't fight the +filter by editing workflows per PR. diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md index 2215b3c97..4b126ff57 100644 --- a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md @@ -6,7 +6,7 @@ | --- | --- | | Run ID | `fix-611-ci-docs-only-md--ci-classifier` | | Branch | `fix/611-ci-docs-only-md` | -| Current phase | `implement` | +| Current phase | `evaluate` | | Archetype | `N/A` | | Scope overlays | `docs` | @@ -20,15 +20,15 @@ Research, locked plan, Design checkpoint, and separate-session PLAN-EVAL are com - Inspected classifier, tests, source skills, issue #611, branch, and clean worktree. - Separate Claude Opus PLAN-EVAL returned `PASS` in `plan-eval.md`. - Classifier slice implemented with all 30 focused tests and scoped check/format green. +- Skill guidance landed in source skills and Claude mirrors were regenerated/check-verified. ## In Progress -- Skill guidance and generated mirrors. +- Separate-session IMPL-EVAL. ## Next Steps -1. Implement slices 2–3 and run named gates. -2. Obtain IMPL-EVAL and finalize PR status/metadata. +1. Obtain IMPL-EVAL and finalize PR status/metadata. ## Key Decisions @@ -43,6 +43,9 @@ Research, locked plan, Design checkpoint, and separate-session PLAN-EVAL are com | --- | --- | --- | | `.github/scripts/ci-classify-changes.ts` | changed | Critical-path guard precedes global Markdown/MDX classification. | | `.github/scripts/ci-classify-changes.test.ts` | changed | Requested mixed/lock/package/rename regressions. | +| `.agents/skills/netscript-pr/SKILL.md` | changed | Proactive docs-only CI label guidance and taxonomy. | +| `.agents/skills/netscript-harness/SKILL.md` | changed | Opening-session label guidance. | +| `.claude/skills/netscript-{pr,harness}/SKILL.md` | generated | Synced from authoritative skills. | ## Gates @@ -51,11 +54,11 @@ Research, locked plan, Design checkpoint, and separate-session PLAN-EVAL are com | Static | PASS | 30 tests; scoped check and format checks green. | | Fitness | N/A | No package/plugin surface. | | Runtime | N/A | Pure classifier tests cover behavior. | -| Consumer | pending | Claude mirror sync/check remains. | +| Consumer | PASS | Claude mirror sync/check: 17 skills, 21 files. | ## Drift and Debt -- Drift: none so far. +- Drift: beta milestone mapping recorded in `drift.md`. - Debt: none. ## Commits diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md index 139bd3941..dd5e5117f 100644 --- a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md @@ -55,6 +55,9 @@ Edit the pure path predicates and add a table-style regression in `ci-classify-c | 2026-07-11 | 2 | implementation | Global Markdown/MDX precedence added after critical-path guard; rename parsing preserved. | | 2026-07-11 | 2 | gates | 30 classifier tests, scoped check, and scoped format check passed. | | 2026-07-11 | 2 | reconcile | Issue #611 remains open; PR #613 has `Closes #611`, parent/motivating refs, beta.7 milestone, and `status:plan-eval` pending phase transition. No new comments required readjustment. | +| 2026-07-11 | 3 | implementation | Added proactive docs-only PR label guidance to both authoritative skills and regenerated only through `agentic:sync-claude`. | +| 2026-07-11 | 3 | gates | Mirror check, final classifier tests/check, diff check, docs-overlay source/link/terminology review, and lock hygiene passed. | +| 2026-07-11 | 3 | reconcile | PR #613 is not itself docs-only because it changes classifier TS, so skip labels are intentionally not applied; `ci:full` remains available. No new review comments changed scope. | ## Gate Results @@ -62,6 +65,9 @@ Edit the pure path predicates and add a table-style regression in `ci-classify-c - Classifier tests — `PASS` (30 passed, 0 failed). - Scoped check (`.github/scripts`, TS/TSX) — `PASS` (2 files, 0 findings). - Scoped format check (`.github/scripts`, TS/TSX) — `PASS` (2 files, 0 findings). +- Claude skill mirror check — `PASS` (17 skills, 21 mirrored files). +- Docs overlay — `PASS`: guidance aligns with classifier/labels, adds no broken local links, and uses checked-in CI label terms. +- Lock hygiene — `PASS`: `deno.lock` unchanged. ## Handoff Notes From 5b44d7b1e08f8e4e5432eb02efde8fd7a08f82d9 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Sat, 11 Jul 2026 09:55:14 +0200 Subject: [PATCH 5/5] gate(ci): pass #611 implementation evaluation --- .../context-pack.md | 7 +- .../drift.md | 10 ++ .../evaluate.md | 110 ++++++++++++++++++ .../plan-eval.md | 29 +++-- .../worklog.md | 3 + 5 files changed, 147 insertions(+), 12 deletions(-) create mode 100644 .llm/runs/fix-611-ci-docs-only-md--ci-classifier/evaluate.md diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md index 4b126ff57..051ea2977 100644 --- a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/context-pack.md @@ -6,7 +6,7 @@ | --- | --- | | Run ID | `fix-611-ci-docs-only-md--ci-classifier` | | Branch | `fix/611-ci-docs-only-md` | -| Current phase | `evaluate` | +| Current phase | `close` | | Archetype | `N/A` | | Scope overlays | `docs` | @@ -21,14 +21,15 @@ Research, locked plan, Design checkpoint, and separate-session PLAN-EVAL are com - Separate Claude Opus PLAN-EVAL returned `PASS` in `plan-eval.md`. - Classifier slice implemented with all 30 focused tests and scoped check/format green. - Skill guidance landed in source skills and Claude mirrors were regenerated/check-verified. +- Separate Claude Opus IMPL-EVAL returned `PASS`; issue #611 close-gate acceptance is fully evidenced. ## In Progress -- Separate-session IMPL-EVAL. +- Refresh PR body/status and hand off ready-to-merge draft PR. ## Next Steps -1. Obtain IMPL-EVAL and finalize PR status/metadata. +1. Commit/push evaluator trail, refresh PR body, and transition canonical status. ## Key Decisions diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/drift.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/drift.md index d36705af4..12fa06ba8 100644 --- a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/drift.md +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/drift.md @@ -9,3 +9,13 @@ - **Severity:** minor - **Action:** accept - **Evidence:** PR #613 milestone and `gh api repos/rickylabs/netscript/milestones`. + +## 2026-07-11 — requested status label is not in the repository taxonomy + +- **What:** The brief requests `status:in-progress`, but the namespaced repository taxonomy contains no such label. +- **Source:** `.github/labels.yml` and `.agents/skills/netscript-pr/SKILL.md`. +- **Expected:** PR label `status:in-progress`. +- **Actual:** The canonical harness lifecycle uses `status:impl` during implementation, `status:impl-eval` during evaluation, and `status:ready-merge` after IMPL-EVAL PASS. +- **Severity:** minor +- **Action:** accept; follow the canonical single-status lifecycle rather than inventing a new label. +- **Evidence:** PR #613 phase comments/label history and `evaluate.md` PASS. diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/evaluate.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/evaluate.md new file mode 100644 index 000000000..afbb0b800 --- /dev/null +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/evaluate.md @@ -0,0 +1,110 @@ +# Evaluation: #611 CI Markdown-only classifier + skip-label guidance + +Allowed result values: `PASS`, `FAIL`, `N/A`, `PENDING_SCRIPT`, `DEBT_ACCEPTED`, `NOT_RUN`. + +## Metadata + +| Field | Value | +| -------------- | ------------------------------------------------------------ | +| Run ID | `fix-611-ci-docs-only-md--ci-classifier` | +| Target | `.github/scripts/ci-classify-changes.ts` + PR/harness skills | +| Archetype | `N/A` — repository CI tooling, no package/plugin surface | +| Scope overlays | `docs` | +| Evaluator | IMPL-EVAL — Claude Opus (opposite-family, local) / 2026-07-11 | +| PR / issue | PR #613 (draft), Closes #611 | + +## Process Verification + +| Check | Result | Evidence | +| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Plan-Gate passed before implementation | PASS | `plan-eval.md` verdict = `PASS`; approval commit `dc1dd3b5` (09:47:33) precedes first impl commit `34b33781` (09:48:44). `git log` order confirms no slice landed before the gate. | +| Design section exists in worklog | PASS | `worklog.md` §Design present with all 7 elements (Public Surface, Domain Vocabulary, Ports, Constants, Commit Slices, Deferred Scope, Contributor Path). | +| Commit slices match design plan | PASS | Design named 3 slices; branch carries plan `5486637b`, plan-eval artifact `dc1dd3b5`, classifier slice `34b33781`, guidance+mirror slice `9279e40c` — in Design order, < 30. | +| Each slice has a passing gate | PASS | Slice 2 gate (tests + scoped check/fmt) and Slice 3 gate (sync-claude:check) evidenced in per-slice PR comments and independently re-run below. | +| No speculative seams (unused files) | PASS | No new files; only existing files edited. New `isCritical()` helper is reachable from `isDocsOnlyPath` (`ci-classify-changes.ts:99`). | +| Constants used for finite vocabularies | PASS | Reuses `IMPACTING_PREFIXES`/`IMPACTING_EXACT`/`DOCS_EXTENSIONS`/`DOCS_PREFIXES`; see low-severity DRY note in Findings re `isCritical` inlined basenames. | + +## Static Gates + +| Gate | Command or check | Result | Evidence | Notes | +| ---------------- | --------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------- | ----- | +| Unit tests | `deno test --no-lock -A .github/scripts/` | PASS | 30 passed, 0 failed (independently re-run). | Covers all 4 requested cases + critical-path + rename. | +| Slice typecheck | `run-deno-check.ts --root .github/scripts --ext ts,tsx` | PASS | `filesSelected:2, failedBatches:0, totalOccurrences:0` | | +| Format | `run-deno-fmt.ts --root .github/scripts --ext ts,tsx` | PASS | `filesSelected:2, findings:0` | | +| Lint | `run-deno-lint.ts --root .github/scripts --ext ts,tsx` | PASS | `exitCode:0, totalOccurrences:0` (not in plan gate set; run for completeness). | | +| Generated mirror | `deno task agentic:sync-claude:check` | PASS | `agentic:sync-claude OK: 17 skill(s), 21 mirrored file(s)`; `.claude/skills/{pr,harness}` byte-identical to `.agents/skills` sources. | | +| Lock hygiene | `git diff -- deno.lock` | PASS | 0 diff lines — `deno.lock` unchanged. | | +| Link/path check | docs overlay — referenced label terms | PASS | Skill edits reference `ci:skip-e2e` / `ci:skip-scaffold` / `ci:full`, all present in `.github/labels.yml:150,153,156`. No new local file paths added. | | + +## Fitness Gates + +| Gate | Function | Result | Evidence | Violations | +| ---- | -------- | ------ | -------- | ---------- | +| F-1 … F-19 | doctrine fitness | N/A | No `packages/`/`plugins/` public surface touched; archetype `N/A` per plan and PLAN-EVAL. | none | + +## Runtime Gates + +| Gate | Validation | Result | Evidence | +| ---- | ---------- | ------ | -------- | +| Runtime/Aspire | pure classifier; behavior proven by unit tests | N/A | No runtime surface; 30 unit tests cover `decide`/`isDocsOnlyPath`/`parseNameStatus`. | +| Release-gate class (`scaffold.runtime`, `e2e-cli-prod`) | n/a per protocol rule 14 | N/A | Run changes the classifier that *decides* scaffold gating, not scaffold output / plugin scaffold / DB / Aspire / published CLI shape. Not a release cut. | + +## Consumer Gates + +| Consumer | Validation | Result | Evidence | +| -------- | ---------- | ------ | -------- | +| Claude skill mirrors | `agentic:sync-claude:check` | PASS | 17 skills / 21 files in sync; mirrors regenerated only via the sync task (D4 honored). | +| `.github/labels.yml` taxonomy | skill terminology matches checked-in labels | PASS | `ci:skip-scaffold` newly referenced by skills exists in taxonomy. | + +## Anti-Pattern Check + +| AP | Status | Evidence | Notes | +| -- | ------ | -------- | ----- | +| AP-1 … AP-25 | N/A | Scope is repository CI tooling + agent-guidance Markdown; no doctrine-governed package/plugin code in the diff. | Nothing in scope could affect the doctrine patterns. | + +## Arch-Debt Delta + +| Metric | Count | Evidence | +| ------ | ----- | -------- | +| New entries | 0 | No doctrine-governed surface touched; plan §Deferred Scope declares no debt. | +| Resolved entries | 0 | — | +| Deepened violations | 0 | — | +| Unrecorded violations | 0 | Classifier ordering keeps critical `deno.json*`/`deno.lock`/workflow paths authoritative; no violation introduced. | + +## Correctness Review (classifier) + +Independently traced `isDocsOnlyPath` precedence (`ci-classify-changes.ts:98-103`): + +1. `isCritical` first → `deno.json[c]`, `deno.lock` (any depth, basename), and `.github/workflows/**` always force full CI even if `.md`. Confirmed `.github/workflows/README.md` ⇒ `false` (test present). +2. `.md`/`.mdx` extension then wins over ordinary `packages/`/`plugins/`/`apps/` prefixes ⇒ `packages/cli/README.md` docs-only (issue #611's core requirement). +3. `isImpacting` demotes remaining non-Markdown under impacting prefixes. +4. `isDocs` allows the docs directory prefixes. + +Edge cases verified: empty diff ⇒ not docs-only (runs); `README.md` + `mod.ts` ⇒ full; `README.md` + `deno.lock` ⇒ full; rename `packages/cli/OLD_README.md → README.md` ⇒ docs-only (both sides Markdown); rename with an impacting source path still surfaces via `parseNameStatus` dual-path (rename hole stays closed). Conservative default (unclassifiable ⇒ force gate) preserved. Module-header contract comment rewritten to match the reversed policy (PLAN-EVAL reminder honored). + +## Process / GitHub Surface + +- Per-slice PR comment trail complete and evidenced: PLAN-EVAL APPROVED (`dc1dd3b5`), Slice 2 IMPL (`34b33781`, 30/30 + scoped gates), Slice 3 IMPL (`9279e40c`, mirror check). This is the authoritative commit trail (run-loop §5). +- `Closes #611` present in PR body; milestone `0.0.1-beta.7` (drift-logged); exactly one `status:` label. +- Close-gate (protocol rule 12): issue #611's two acceptance criteria are both checked with linked commit + phase-comment evidence; the issue carries no `gate:` checkboxes. Close-gate is satisfied at the issue level. +- No agent briefs were dispatched (single supervisor-driven session per `supervisor.md`); protocol rule 13 (`## SKILL` chapter in briefs) is n/a. + +## Findings + +| Severity | Finding | Evidence | Required action | +| -------- | ------- | -------- | --------------- | +| low | PR #613 body is stale relative to actual progress: slice boxes S2/S3 and the entire Definition-of-Done checklist are unchecked, and Validation/Harness still read "PLAN-EVAL pending … Phase: plan-eval". | `gh pr view 613 --json body`; authoritative per-slice comments and run artifacts are current. | Non-blocking for IMPL-EVAL. Refresh the PR body (check S2/S3 + DoD, update phase/validation) as part of the `status:ready-merge` transition before merge. | +| low | `isCritical` (`ci-classify-changes.ts:79-84`) re-inlines the `deno.json`/`deno.jsonc`/`deno.lock` basenames already encoded in `IMPACTING_EXACT` and `isImpacting`'s basename check. | Two independent copies of the same finite vocabulary. | Optional cleanup: derive `isCritical` from a shared constant. Not a gate failure. | + +## Lessons for Promotion + +| Lesson | Pattern | Applies to | Confidence | +| ------ | ------- | ---------- | ---------- | +| Reversing a classifier precedence rule must invert the encoding tests and rewrite the module-header contract in the same slice | contract-first reversal | docs / CI-tooling runs | medium | + +## Verdict + +| Field | Value | +| --------- | ----- | +| Verdict | `PASS` | +| Rationale | Approved scope is fully implemented: Markdown/MDX diffs classify docs-only across all directories while `deno.json*`/`deno.lock`/workflow criticals and any non-Markdown impacting path still force full CI, and rename dual-path handling keeps the rename hole closed. All applicable static/consumer gates were re-run independently and pass (30/30 tests, scoped check/lint/fmt clean, mirror sync 17/21, `deno.lock` untouched); fitness/runtime/release gates are correctly `N/A`. No architecture debt was introduced or required, and issue #611's close-gate acceptance criteria are checked with linked evidence. The two findings are low-severity: a stale PR body to refresh before the ready-merge transition, and an optional DRY cleanup — neither blocks the implementation against the approved plan. | diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan-eval.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan-eval.md index e7e10275e..780976aa6 100644 --- a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan-eval.md +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/plan-eval.md @@ -1,6 +1,6 @@ # PLAN-EVAL — fix-611-ci-docs-only-md--ci-classifier -- Plan evaluator session: Claude (opposite-family, local) / 2026-07-11 +- Plan evaluator session: Claude Opus 4.8 (opposite-family, local) / 2026-07-11 - Run: `fix-611-ci-docs-only-md--ci-classifier` - Surface / archetype: repository CI classifier tooling + agent skill guidance; archetype `N/A` (no package/plugin public surface) - Scope overlays: `docs` (skill guidance + run artifacts) @@ -9,18 +9,18 @@ | Plan-Gate item | Result | Evidence / location | | --------------------------------------- | ------ | ------------------- | -| Research present and current | PASS | `research.md` re-baselined against `origin/main` @ `720fcb7e` (matches `supervisor.md` baseline). Spot-checked finding #1: `.github/scripts/ci-classify-changes.ts:69-95` confirms `isDocsOnlyPath` runs `isImpacting` (packages/plugins/apps denylist) before the docs allowlist, so `packages/**/*.md` is currently full CI. Confirmed the old policy is encoded in tests: `ci-classify-changes.test.ts:110-112` asserts `packages/cli/README.md`, `plugins/workers/CHANGELOG.md`, `apps/demo/README.md` are `false`. Finding #2 (`parseNameStatus` both-sides rename awareness) confirmed at `:236-256`. | -| Decisions locked | PASS | `plan.md` §Locked Decisions D1–D4, each with rationale (markdown precedence, rename both-sides, dual-surface PR guidance, generated-mirror-only edits). | -| Open-decision sweep | PASS | `plan.md` §Open-Decision Sweep lists `apps/**/*.md` (resolved now) and `ci:skip-scaffold` per-PR applicability (safe to defer — label application carries no code dependency). Evaluator sweep below found no unflagged rework-forcing decision. | +| Research present and current | PASS | `research.md` re-baselined against `origin/main` @ `720fcb7e` (matches `supervisor.md` baseline and `git log`). Spot-checked finding #1: `.github/scripts/ci-classify-changes.ts:69-95` confirms `isDocsOnlyPath` runs `isImpacting` (packages/plugins/apps denylist) before the docs allowlist, so `packages/**/*.md` is currently full CI. Old policy is encoded in tests: `ci-classify-changes.test.ts:110-112` asserts `packages/cli/README.md`, `plugins/workers/CHANGELOG.md`, `apps/demo/README.md` are `false`. Finding #2 (`parseNameStatus` both-sides rename awareness) confirmed at `:236-256`. Issue #611 acceptance matches the plan Goal/Scope. | +| Decisions locked | PASS | `plan.md` §Locked Decisions D1–D4, each with rationale (markdown precedence, rename both-sides, dual-surface PR guidance, generated-mirror-only edits). D4 verified: `agentic:sync-claude`/`:check` exist in `deno.json:51-52`. | +| Open-decision sweep | PASS | `plan.md` §Open-Decision Sweep lists `apps/**/*.md` (resolved now) and `ci:skip-scaffold` per-PR applicability (safe to defer — label application carries no code dependency). Evaluator sweep below found no unflagged rework-forcing *plan* decision. | | Commit slices (< 30, gate + files each) | PASS | `worklog.md` §Commit Slices: 3 ordered slices. Slice 2 gate = focused tests + scoped check, files = `ci-classify-changes.ts`/`.test.ts` + artifacts; Slice 3 gate = sync + sync check, files = source skills + generated mirrors. `<30`. | | Risk register | PASS | `plan.md` §Risk Register: 4 risks w/ mitigations — extension-precedence leaking config/workflow, rename hole, mirror drift, lock churn. | -| Gate set selected | PASS | `plan.md` §Gate Set: 5 gates (unit tests, scoped `run-deno-check.ts`, `agentic:sync-claude:check`, focused fmt, `git diff -- deno.lock`). Verified `agentic:sync-claude`/`:check` tasks exist in `deno.json:51-52`. Release-gate class is `n/a`: run changes the classifier that *decides* scaffold gating, not scaffold output / plugin scaffold / DB / Aspire / published CLI shape. Docs-overlay coverage noted as advisory below. | +| Gate set selected | PASS | `plan.md` §Gate Set: 5 gates (unit tests, scoped `run-deno-check.ts`, `agentic:sync-claude:check`, focused fmt, `git diff -- deno.lock`). Release-gate class is `n/a`: run changes the classifier that *decides* scaffold gating, not scaffold output / plugin scaffold / DB / Aspire / published CLI shape. **Docs-overlay content gates (Source alignment, Link integrity, Terminology) are carried as manual/IMPL-EVAL evidence** per `gates/plan-gate.md` §Phase A reporting; `sync-claude:check` covers only mirror parity (Scope separation via generated output), and Drift log is initialized. This is acceptable for a 3-line label-guidance edit **only because** the two concrete defects found below are named for the IMPL pass — they are not a plan defect (FAIL_FIX class per `verdict-definitions.md`), but they MUST be fixed under the docs overlay at IMPL. | | Deferred scope explicit | PASS | `plan.md` §Non-Scope + §Deferred Scope and Debt (workflow YAML, label taxonomy/automation, package code, full scaffold runtime; no arch debt created). | | jsr-audit surface scan (pkg/plugin) | N/A | `research.md` §jsr-audit surface scan marks N/A with reason: repository CI tooling + agent guidance, not a package/plugin publish surface. Correct — no `packages/`/`plugins/` source is touched. | ## Open-decision sweep (evaluator-run) -None that force rework if deferred. Independent checks: +No open decision forces *plan* rework if deferred. Independent checks: - **Markdown vs. critical-path precedence** — resolved: `research.md` open-questions and Risk #1 keep the `.github/workflows/` prefix and `deno.json*`/`deno.lock` exact/basename checks *ahead* of the extension classification. Those criticals are never `.md`/`.mdx`, so extension-precedence cannot make them docs-safe; the ordering is a belt-and-suspenders guard, not a live hole. - **Rename where one side is impacting** (`packages/x.ts -> docs/x.md`) — locked by D2 + preserved `parseNameStatus`; combined-set classification keeps the impacting source path. Existing regression at `ci-classify-changes.test.ts:14-16` pins it. @@ -31,7 +31,18 @@ None that force rework if deferred. Independent checks: `PASS` -## Notes +## Notes — mandatory IMPL-EVAL confirmations (docs overlay, slice 3) -- Advisory (not blocking): the `docs` overlay's Source-alignment / Link-integrity / Terminology gates for the two skill edits are not itemized as explicit rows in the §Gate Set table. They are implicitly covered by the `agentic:sync-claude:check` mirror gate (the dominant docs risk here) plus IMPL-EVAL review, and `drift.md` is initialized. For two small proactive-label additions this is acceptable; IMPL-EVAL should still confirm any local paths added to the skills resolve and terminology matches `.claude/09-glossary.md`. -- Implementation reminder for slice 2 (for IMPL-EVAL, not a plan defect): reversing `isDocsOnlyPath` must keep `isImpacting`'s exact/basename `deno.json*`/`deno.lock` and `.github/workflows/` checks authoritative while demoting the `packages/`/`plugins/`/`apps/` *prefixes* below the `.md`/`.mdx` extension test — and the module header contract comment (`ci-classify-changes.ts:11-20`) must be rewritten, since it currently states the denylist "ALWAYS wins ... even if it is a Markdown file," which D1 reverses. +Two verified source-alignment/terminology defects sit **inside the `netscript-pr` §"Path-filter awareness" section the plan already edits** (`plan.md` scope: "Update `netscript-pr` … guidance"). Both are in-scope and require no Non-Scope change (no new labels, no workflow-YAML edit). The Gate-set PASS above is conditioned on the IMPL pass fixing them; IMPL-EVAL must confirm both: + +1. **Source alignment — correct the CI mechanism claim.** `.agents/skills/netscript-pr/SKILL.md:310` states docs-only PRs are "auto-skipped by CI `paths-ignore`." For the `e2e-cli` gate this is wrong: `.github/workflows/e2e-cli.yml` (header comment ~line 39) explicitly does **not** use `paths-ignore`/job-level `if`; it runs the `classify` job (`ci-classify-changes.ts`) and reports SUCCESS (`paths-ignore` is used by `pages.yml`, a different workflow). The proactive-label edit must rewrite this sentence to the classify-job mechanism, not leave a contradictory claim in the edited section. + +2. **Terminology — align the `ci:` taxonomy the new guidance depends on.** `.agents/skills/netscript-pr/SKILL.md:231` lists `ci:` — `skip-e2e`, `full` and **omits `ci:skip-scaffold`**, the exact label the new guidance instructs agents to apply. The label exists (`.github/labels.yml:156`) and is consumed by the classifier (`ci-classify-changes.ts:128,168`). Add `skip-scaffold` to that taxonomy line so the skill's own label list matches the guidance and `labels.yml`. + +## Notes — other IMPL reminders (not plan defects) + +- **Header contract comment must be rewritten (slice 2).** `ci-classify-changes.ts:11-20` currently states the denylist "ALWAYS wins … even if it is a Markdown file"; D1 reverses this. The module doc-comment and the "Design contract" reference must be updated in lockstep with the logic, or the source will self-contradict (Source alignment on code comments). +- **Reordering must preserve critical authority (slice 2).** Keep `isImpacting`'s exact/basename `deno.json*`/`deno.lock` and `.github/workflows/` checks authoritative while demoting the `packages/`/`plugins/`/`apps/` *prefixes* below the `.md`/`.mdx` extension test. Risk #1 covers this; add the four explicit regressions (global markdown docs-only; workflow + `deno.json*` still full; source→markdown rename still full; markdown→markdown rename docs-only) so IMPL-EVAL has named cases. +- **Link integrity:** IMPL-EVAL should confirm any local path added to either skill resolves, and terminology matches `.claude/09-glossary.md`. + +_Verdict history: this file affirms an earlier local opposite-family PASS; this pass hardens the docs-overlay coverage by naming two concrete defects (paths-ignore claim; missing `ci:skip-scaffold`) the prior note did not itemize. FAIL_PLAN was considered and rejected — both are in-scope IMPL/FAIL_FIX-class doc corrections, not unchecked plan-gate boxes._ diff --git a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md index dd5e5117f..17efb4ecf 100644 --- a/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md +++ b/.llm/runs/fix-611-ci-docs-only-md--ci-classifier/worklog.md @@ -58,6 +58,7 @@ Edit the pure path predicates and add a table-style regression in `ci-classify-c | 2026-07-11 | 3 | implementation | Added proactive docs-only PR label guidance to both authoritative skills and regenerated only through `agentic:sync-claude`. | | 2026-07-11 | 3 | gates | Mirror check, final classifier tests/check, diff check, docs-overlay source/link/terminology review, and lock hygiene passed. | | 2026-07-11 | 3 | reconcile | PR #613 is not itself docs-only because it changes classifier TS, so skip labels are intentionally not applied; `ci:full` remains available. No new review comments changed scope. | +| 2026-07-11 | final | IMPL-EVAL | Separate Claude Opus evaluator returned `PASS` after independently rerunning focused static/consumer gates and verifying the close-gate. | ## Gate Results @@ -68,7 +69,9 @@ Edit the pure path predicates and add a table-style regression in `ci-classify-c - Claude skill mirror check — `PASS` (17 skills, 21 mirrored files). - Docs overlay — `PASS`: guidance aligns with classifier/labels, adds no broken local links, and uses checked-in CI label terms. - Lock hygiene — `PASS`: `deno.lock` unchanged. +- Independent IMPL-EVAL — `PASS`; see `evaluate.md`. ## Handoff Notes - IMPL-EVAL should scrutinize Markdown precedence versus explicit workflow/Deno critical paths and the rename-old-path behavior. +- Evaluator's optional DRY note about duplicated critical basenames is non-blocking and intentionally deferred to avoid expanding the focused classifier contract change.