Skip to content

Wave 0b·A — Plan-Gate reinforcement (Plan & Design — READY FOR REVIEW) #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rickylabs merged 12 commits into from
Jun 5, 2026
Merged

Wave 0b·A — Plan-Gate reinforcement (Plan & Design — READY FOR REVIEW) #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
b8d9c9a
plan(wave0b): Plan & Design artifacts for harness reinforcement
rickylabs Jun 5, 2026
e54a74c
feat(harness): rewrite run-loop.md to 8-phase model with Plan-Gate
rickylabs Jun 5, 2026
ab7eb38
feat(harness): add Plan-Gate definition and checklist
rickylabs Jun 5, 2026
2ecdcd0
feat(harness): add PLAN-EVAL protocol and FAIL_PLAN verdict
rickylabs Jun 5, 2026
51df61d
feat(harness): add plan-eval and research templates
rickylabs Jun 5, 2026
3ddf79a
feat(harness): update activation and supervisor for Plan-Gate
rickylabs Jun 5, 2026
6a797bc
feat(harness): update SKILL and IMPL-EVAL protocol for dual evaluator…
rickylabs Jun 5, 2026
f2d818b
feat(harness): add lesson and update indices to 8-phase model
rickylabs Jun 5, 2026
7fcf3e3
style(harness): deno fmt on all changed markdown
rickylabs Jun 5, 2026
3f33c44
docs(wave0b): record validation results and updated context pack
rickylabs Jun 5, 2026
8d6bade
eval(wave0b): IMPL-EVAL verdict PASS for harness reinforcement
rickylabs Jun 5, 2026
a3ca872
fix(harness): address review findings F1-F5
rickylabs Jun 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 63 additions & 54 deletions .agents/skills/netscript-harness/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@ description: >

# NetScript Harness v2 — Orchestration Skill

This skill coordinates harness-mode runs. The authoritative harness docs live
under `.llm/harness/`; this skill tells you what to load and in what order.
This skill coordinates harness-mode runs. The authoritative harness docs live under `.llm/harness/`;
this skill tells you what to load and in what order.

## 1. Activation

The harness activates on any prompt containing `use harness` or an equivalent
request for a harnessed run.
The harness activates on any prompt containing `use harness` or an equivalent request for a
harnessed run.

On activation, read:

Expand All @@ -25,32 +25,32 @@ On activation, read:
4. `.llm/harness/archetypes/README.md`
5. selected `ARCHETYPE-*` profile and any `SCOPE-*` overlays
6. `.llm/harness/gates/archetype-gate-matrix.md`
7. `.llm/harness/gates/plan-gate.md` and `.llm/harness/evaluator/plan-protocol.md`

For package/plugin work, also use `.claude/skills/netscript-doctrine/SKILL.md`.

For a **supervisor run** (two or more capability-scoped phase groups), also read
`.llm/harness/workflow/supervisor.md` and `.llm/harness/workflow/escalation.md`,
and track the groups in `phase-registry.md`.
`.llm/harness/workflow/supervisor.md` and `.llm/harness/workflow/escalation.md`, and track the
groups in `phase-registry.md`.

## 2. From Prompt Profile to v2 Profile

The user may still write `profile: package`, `profile: docs`, or similar. In v2
that field is an intent hint, not the final profile.
The user may still write `profile: package`, `profile: docs`, or similar. In v2 that field is an
intent hint, not the final profile.

| User hint | v2 selection |
|-----------|--------------|
| `package` | identify `ARCHETYPE-1` through `ARCHETYPE-6` |
| `plugin` | normally `ARCHETYPE-5`, unless sibling packages also change |
| `frontend` | affected archetype(s) plus `SCOPE-frontend.md` |
| `service` | affected archetype(s) plus `SCOPE-service.md` |
| `docs` or `knowledge-base` | `SCOPE-docs.md` plus any described archetypes |
| User hint | v2 selection |
| -------------------------- | ----------------------------------------------------------- |
| `package` | identify `ARCHETYPE-1` through `ARCHETYPE-6` |
| `plugin` | normally `ARCHETYPE-5`, unless sibling packages also change |
| `frontend` | affected archetype(s) plus `SCOPE-frontend.md` |
| `service` | affected archetype(s) plus `SCOPE-service.md` |
| `docs` or `knowledge-base` | `SCOPE-docs.md` plus any described archetypes |

If no package/plugin is touched, an overlay-only run is valid.

## 3. Run ID

`<run-id>` is the current branch name with `/` replaced by `-`, followed by
`--<suffix>`.
`<run-id>` is the current branch name with `/` replaced by `-`, followed by `--<suffix>`.

Example:

Expand All @@ -60,28 +60,29 @@ feat/frontend-rfc-implementation -> feat-frontend-rfc-implementation--package-kv

## 4. Run Artifacts

Run artifacts live under `.llm/tmp/run/<run-id>/` and use templates from
`.llm/harness/templates/`.

| File | Purpose |
|------|---------|
| `plan.md` | approved scope, archetype, gates, debt implications |
| `implement.md` | generator prompt when needed |
| `worklog.md` | implementation evidence and gate results |
| `evaluate.md` | separate evaluator verdict |
| `context-pack.md` | resumable summary |
| `drift.md` | append-only drift log |
| `commits.md` | append-only commit list |
Run artifacts live under `.llm/tmp/run/<run-id>/` and use templates from `.llm/harness/templates/`.

| File | Purpose |
| ------------------- | -------------------------------------------------------------- |
| `research.md` | deep findings, re-baseline of carried-in plans |
| `plan.md` | approved scope, archetype, gates, debt implications |
| `implement.md` | generator prompt when needed |
| `worklog.md` | implementation evidence and gate results |
| `plan-eval.md` | PLAN-EVAL verdict (separate session, before implementation) |
| `evaluate.md` | IMPL-EVAL verdict (separate session, after implementation) |
| `context-pack.md` | resumable summary |
| `drift.md` | append-only drift log |
| `commits.md` | append-only commit list |
| `phase-registry.md` | supervisor runs only: phase-group map + live status (template) |

Append `commits.md` immediately after every commit. Supervisor runs additionally
keep `phase-registry.md`, `final-pr-handoff.md`, and an `escalations/` folder;
brief each group agent with `templates/agent-briefing.md`.
Append `commits.md` immediately after every commit. Supervisor runs additionally keep
`phase-registry.md`, `final-pr-handoff.md`, and an `escalations/` folder; brief each group agent
with `templates/agent-briefing.md`.

## 5. `.llm/tmp` Path Caveat

Some search/index tools may skip or lag on `.llm/tmp/`. Verify run paths with a
direct filesystem listing when needed:
Some search/index tools may skip or lag on `.llm/tmp/`. Verify run paths with a direct filesystem
listing when needed:

```powershell
dir /s /b ".llm\tmp\run\<id>" 2>&1
Expand All @@ -99,14 +100,22 @@ When external docs or examples matter:

## 7. Evaluator Separation

The evaluator must be a separate session.
There are **two** separate-session evaluator passes.

- Generator writes `worklog.md`, `context-pack.md`, `drift.md`, and
`commits.md`.
- Evaluator reads `.llm/harness/evaluator/protocol.md`, the plan, worklog,
context pack, drift, commits, selected archetype, overlays, and gate docs.
- Evaluator writes `evaluate.md` with `PASS`, `FAIL_FIX`, `FAIL_RESCOPE`, or
`FAIL_DEBT`.
**PLAN-EVAL** (before implementation):

- Reads `evaluator/plan-protocol.md` + `gates/plan-gate.md`.
- Reads `research.md`, `plan.md`, and the `## Design` section.
- Writes `plan-eval.md`.
- Emits `PASS` or `FAIL_PLAN`.
- Two `FAIL_PLAN` cycles, then escalate.

**IMPL-EVAL** (final pass, after implementation):

- Generator writes `worklog.md`, `context-pack.md`, `drift.md`, and `commits.md`.
- Evaluator reads `.llm/harness/evaluator/protocol.md`, the plan, worklog, context pack, drift,
commits, selected archetype, overlays, and gate docs.
- Evaluator writes `evaluate.md` with `PASS`, `FAIL_FIX`, `FAIL_RESCOPE`, or `FAIL_DEBT`.
- Eval loop limit is two failures before escalation.

## 8. Commit Tracking
Expand All @@ -126,22 +135,21 @@ Commit log format:

## 9. Rescoping

Rescope when the real work is materially larger than the approved plan or when
the selected archetype is wrong. Confirm with the user before expanding scope.
Rescope when the real work is materially larger than the approved plan or when the selected
archetype is wrong. Confirm with the user before expanding scope.

Record rescope evidence in `drift.md` with severity `significant` or
`architectural`.
Record rescope evidence in `drift.md` with severity `significant` or `architectural`.

## 10. Where Lessons Belong

| Content type | Destination |
|--------------|-------------|
| Generic run mechanics | `.llm/harness/workflow/` |
| Archetype-specific gates or false-done states | `.llm/harness/archetypes/` |
| Stable repeated cross-run lessons | `.llm/harness/lessons/` |
| Package/plugin doctrine navigation | `.claude/skills/netscript-doctrine/` |
| Deep domain expertise | a focused skill |
| Deferred doctrine violations | `.llm/harness/debt/arch-debt.md` |
| Content type | Destination |
| --------------------------------------------- | ------------------------------------ |
| Generic run mechanics | `.llm/harness/workflow/` |
| Archetype-specific gates or false-done states | `.llm/harness/archetypes/` |
| Stable repeated cross-run lessons | `.llm/harness/lessons/` |
| Package/plugin doctrine navigation | `.claude/skills/netscript-doctrine/` |
| Deep domain expertise | a focused skill |
| Deferred doctrine violations | `.llm/harness/debt/arch-debt.md` |

## Quick Decision Tree

Expand All @@ -152,7 +160,8 @@ User says "use harness"
-> package/plugin? select ARCHETYPE-* and load netscript-doctrine
-> frontend/service/docs? apply SCOPE-* overlay
-> two or more phase groups? read workflow/supervisor.md + escalation.md, keep phase-registry.md
-> read gate matrix
-> read gate matrix + plan-gate.md
-> plan committed? run PLAN-EVAL (separate session); no slice before PASS
-> update run artifacts while working
-> commit tracking required? append commits.md after every commit
-> discovered violation not fixed? update arch-debt.md
Expand Down
97 changes: 56 additions & 41 deletions .llm/harness/DOCTRINE-REF.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,49 +1,64 @@
# Doctrine Reference

Harness v2 is derived from the NetScript Architecture Doctrine. The doctrine is
the source of truth for `packages/` and `plugins/`; the harness is the run-time
operating model that makes agents apply it.

## Primary Files

| File | Use |
|------|-----|
| `.llm/research/architecture-doctrine-docs-v2/doctrine/01-thesis-and-axioms.md` | Thesis and A1-A14 |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/02-public-surface.md` | Public exports, `mod.ts`, README and JSR surface |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/03-base-and-derived-classes.md` | Stub-only bases, inheritance limits |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/04-modules-and-helpers.md` | Helpers, adapters, Web Platform and `@std/*` first |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/05-folder-structure.md` | Role vocabulary, layering, file shape |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/06-archetypes.md` | Six package archetypes and selection order |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/07-composition-and-extension.md` | Composition roots, constructor injection, extension axes |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/08-runtime-state-failure.md` | Stateful runtime, supervision, cancellation, failure |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/09-anti-patterns-and-fitness-functions.md` | AP-1..AP-20 and F-1..F-15 |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/10-codebase-verdict-and-handoff.md` | Current verdict per package and debt seed |
Harness v2 is derived from the NetScript Architecture Doctrine. The doctrine is the source of truth
for `packages/` and `plugins/`; the harness is the run-time operating model that makes agents apply
it.

## Harness Files

| File | Use |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `.llm/harness/workflow/activation.md` | Bootstrap reading list and mandatory artifacts |
| `.llm/harness/workflow/run-loop.md` | 8-phase run loop (Bootstrap → Research → Plan & Design → Plan-Gate → Implement → Gate → Evaluate → Close) |
| `.llm/harness/workflow/supervisor.md` | Multi-group supervisor runs |
| `.llm/harness/gates/archetype-gate-matrix.md` | Required gates per archetype |
| `.llm/harness/gates/plan-gate.md` | Plan-Gate checklist (PLAN-EVAL) |
| `.llm/harness/evaluator/plan-protocol.md` | PLAN-EVAL operating instructions |
| `.llm/harness/evaluator/protocol.md` | IMPL-EVAL operating instructions |
| `.llm/harness/evaluator/verdict-definitions.md` | Verdict meanings (`PASS`, `FAIL_PLAN`, `FAIL_FIX`, `FAIL_RESCOPE`, `FAIL_DEBT`) |
| `.llm/harness/templates/plan-eval.md` | PLAN-EVAL verdict template |
| `.llm/harness/templates/research.md` | Research artifact template |
| `.llm/harness/lessons/plan-gate-design-as-gate.md` | Lesson: Design must be a gate |

## Doctrine Primary Files

| File | Use |
| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/01-thesis-and-axioms.md` | Thesis and A1-A14 |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/02-public-surface.md` | Public exports, `mod.ts`, README and JSR surface |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/03-base-and-derived-classes.md` | Stub-only bases, inheritance limits |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/04-modules-and-helpers.md` | Helpers, adapters, Web Platform and `@std/*` first |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/05-folder-structure.md` | Role vocabulary, layering, file shape |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/06-archetypes.md` | Six package archetypes and selection order |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/07-composition-and-extension.md` | Composition roots, constructor injection, extension axes |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/08-runtime-state-failure.md` | Stateful runtime, supervision, cancellation, failure |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/09-anti-patterns-and-fitness-functions.md` | AP-1..AP-20 and F-1..F-15 |
| `.llm/research/architecture-doctrine-docs-v2/doctrine/10-codebase-verdict-and-handoff.md` | Current verdict per package and debt seed |

## Axiom Digest

This digest is a navigation aid only. Read the doctrine file before making or
evaluating a package/plugin change.

| Axiom | Navigation summary |
|-------|--------------------|
| A1 | Public types are designed before implementation. |
| A2 | Published boundaries optimize for one concern, not hidden convenience. |
| A3 | The 80 percent case is one chained call; advanced cases unfold one method deeper. |
| A4 | Base classes are stub-only contracts; concrete classes delegate. |
| A5 | Composition over inheritance by default. |
| A6 | Helpers require a real justification. |
| A7 | Web Platform and `@std/*` come before local substitutes. |
| A8 | Folders and files each name one concern. |
| A9 | The six archetypes determine the minimum viable package shape. |
| A10 | Composition root over container; constructor injection by default. |
| A11 | Extension axes are named before abstraction. |
| A12 | Durable workflows are state machines. |
| A13 | Crash boundaries are explicit. |
| A14 | Tests, static gates, JSR gates, and fitness functions preserve the doctrine. |
This digest is a navigation aid only. Read the doctrine file before making or evaluating a
package/plugin change.

| Axiom | Navigation summary |
| ----- | --------------------------------------------------------------------------------- |
| A1 | Public types are designed before implementation. |
| A2 | Published boundaries optimize for one concern, not hidden convenience. |
| A3 | The 80 percent case is one chained call; advanced cases unfold one method deeper. |
| A4 | Base classes are stub-only contracts; concrete classes delegate. |
| A5 | Composition over inheritance by default. |
| A6 | Helpers require a real justification. |
| A7 | Web Platform and `@std/*` come before local substitutes. |
| A8 | Folders and files each name one concern. |
| A9 | The six archetypes determine the minimum viable package shape. |
| A10 | Composition root over container; constructor injection by default. |
| A11 | Extension axes are named before abstraction. |
| A12 | Durable workflows are state machines. |
| A13 | Crash boundaries are explicit. |
| A14 | Tests, static gates, JSR gates, and fitness functions preserve the doctrine. |

## Scope Boundary

The doctrine governs `packages/` and `plugins/`. Harness runs can also touch
apps, services, background workers, and infrastructure; those use the relevant
scope overlay and normal validation gates unless they modify a package/plugin
surface.
The doctrine governs `packages/` and `plugins/`. Harness runs can also touch apps, services,
background workers, and infrastructure; those use the relevant scope overlay and normal validation
gates unless they modify a package/plugin surface.
Loading