jb/harness-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: record develop workflow implementation plan

Browse Source
This commit is contained in:
jb
2026-09-04 10:47:04 -04:00
parent 06e631504c
commit fbf1a52b64
1 changed files with 132 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/workflow/develop-workflow-record.md
+132 -29
View File
@@ -2,15 +2,15 @@
## Status
- Status: active
- Current phase: discovery
- Next safe action: inspect repository contracts and draft the exact Slice 1-2 implementation plan.
- Status: waiting
- Current phase: plan approval
- Next safe action: obtain explicit approval of the exact implementation plan below. Do not edit production files before approval.
## Request and scope
Implement the accepted plan in [`skill-led-development-workflow-plan.md`](./skill-led-development-workflow-plan.md), beginning with the production-ready skill/record contract and review/recovery integration. Scenario evaluation and the three-change pilot remain follow-on validation because they require fresh interactive sessions and real changes.
Implement the accepted [`skill-led-development-workflow-plan.md`](./skill-led-development-workflow-plan.md) as a production-ready Slice 1 and Slice 2 change: the model-invoked skill, retained record contract, atomic checkpoint helper, reviewer capability, review/recovery integration, managed exposure evidence, ADR, and historical documentation.
Out of scope for this change: a replacement extension, deletion or archival of the old workflow engine, global installation of extensions, pushing, publishing, deployment, and production access.
Scenario evaluation and the three-change pilot remain follow-on validation because they require fresh interactive Pi sessions and independent real changes. Their TODO stays open. Out of scope here: a replacement extension, deletion or archival of the legacy engine, global extension installation, pushing, publishing, deployment, and production access.
## Git identity
@@ -18,52 +18,155 @@ Out of scope for this change: a replacement extension, deletion or archival of t
- Base commit: `27cbe965bbd3dc0ca38814811b4f56519a570957`
- Feature branch: `feature/develop-workflow`
- Worktree: `/srv/data/code/jb-pi/harness-tools/.worktrees/develop-workflow`
- Omitted source change: uncommitted YAML quoting in `skills/document/artifact-presenter/SKILL.md`; user approved omission.
- Initial record commit: `256f001`
- Omitted source change: uncommitted YAML quoting in `skills/document/artifact-presenter/SKILL.md`; the user approved omission on 03SEP2026.
## Acceptance criteria
- Add the model-invoked `develop-workflow` skill, progressive references, record template, atomic checkpoint script, and focused failure-path tests without dependencies.
- Expose the skill through the repository-managed Pi link policy while keeping the old workflow extension unexposed.
- Supersede stale workflow documentation with a concise ADR and explicit historical pointers.
- Align `code-review`, `implement`, `prototype`, artifact presentation, task tracking, reviewer independence, recovery, and local integration contracts.
- Pass focused checkpoint tests, link checks, documentation checks where available, typecheck, and the repository test suite.
- Obtain independent standards and specification approval over a pinned, fingerprinted product diff before local integration.
- Pi discovers `develop-workflow` by default for features and multi-step code changes while its description excludes questions, research-only work, and trivial edits.
- Full-path edits require explicit recorded plan approval; non-trivial UI and just-in-time risk gates fail closed.
- The retained record template and helper preserve valid checkpoints across malformed input, interruption, stale/concurrent updates, and filesystem failures without dependencies.
- Every mutating assignment has exclusive named path ownership, a deadline, before/after Git evidence, and identity-based exclusion from review.
- Reviewers regenerate a pinned binary diff, confirm its SHA-256 digest, have Git-capable read-only tool declarations, and never remediate their own findings.
- Recovery, verification, rebase, local fast-forward integration, metadata-only closure, and cleanup rules are explicit and evidence-bound.
- The skill is included by repository-managed skill discovery while both legacy workflow extension exposure maps remain empty.
- Required legacy documents point to ADR 0006 and remain clearly historical during the pilot; pilot TODOs remain open.
- Focused checkpoint/link tests, typecheck, and the full repository test suite pass.
## Approved implementation plan and gates
- Specification: [`skill-led-development-workflow-plan.md`](./skill-led-development-workflow-plan.md), status Accepted.
- Plan gate: approved by the user on 03SEP2026 with “let's implement”.
- Dirty-source gate: approved on 03SEP2026; proceed while omitting the unrelated source-checkout change.
- UI classification: no product UI change; prototype direction gate does not apply.
- Risk gates: none currently identified. Ask immediately before any newly discovered risky action.
### Gate state
- Source plan: [`skill-led-development-workflow-plan.md`](./skill-led-development-workflow-plan.md), status Accepted.
- Broad direction: approved by the user on 03SEP2026 with “let's implement”.
- Exact production plan: pending explicit approval.
- Dirty-source gate: approved on 03SEP2026; omit the unrelated source-checkout change.
- UI classification: no product UI change, so prototype direction approval does not apply.
- Current risk classification: no dependency, migration, production, security-posture, destructive, or compatibility action is planned. Open a scoped gate if discovery changes this.
### Slice A: checkpoint contract
Owner: `checkpoint-implementer` worker, 15-minute deadline.
Owned paths:
- `skills/develop/develop-workflow/scripts/checkpoint-record.mjs`
- `skills/develop/develop-workflow/tests/checkpoint-record.test.mjs`
Implement a Node 22 ESM helper with an exported injectable API and a strict CLI. Validate one H1 and the ten required H2 sections used by this record. For creation, require an absent destination; for replacement, require the current SHA-256 digest. Acquire a fixed exclusive per-record lock, re-read and hash under that lock, write a unique same-directory mode-0600 temporary file, flush it, close it, atomically rename it, and flush the containing directory. Preserve unrelated stale temporary files for recovery and fail closed on a pre-existing lock. Cleanup only files and locks created by the current invocation without masking the primary failure.
Cover valid create/replace, missing/malformed/duplicate sections, replacement without a digest, stale digest, concurrent writers, interrupted write/flush, rename failure, directory-flush failure, stale temporary artifacts, stale lock, and cleanup behavior that preserves the last valid target byte-for-byte.
### Slice B: skill and retained-record contract
Owner: parent agent, 15-minute implementation checkpoint.
Owned paths:
- `skills/develop/develop-workflow/SKILL.md`
- `skills/develop/develop-workflow/references/evidence-and-recovery.md`
- `skills/develop/develop-workflow/references/git-and-integration.md`
- `skills/develop/develop-workflow/references/review-and-remediation.md`
- `skills/develop/develop-workflow/assets/workflow-record.md`
Write a compact verb-first model-invoked skill. Keep path classification, preflight, phase order, human gates, ownership, and completion criteria in `SKILL.md`; disclose detailed Git/integration, recovery/evidence, and review/remediation rules through branch-specific pointers. The template uses the validated ten-section contract and concise evidence fields. Align direct subagent launch, task tracking, artifact presentation, prototype capture, realistic verification, known callback/cwd defects, print/JSON fail-closed behavior, and parent-owned orchestration without duplicating reference prose.
### Slice C: independent-review capability and contracts
Owner: `reviewer-profile-implementer` worker, 15-minute deadline.
Owned paths:
- `extensions/interactive-subagents/agents/reviewer.md`
- `extensions/interactive-subagents/README.md`
- focused reviewer-profile tests under `extensions/interactive-subagents/test/`
Add a reviewer profile that declares Git-capable `bash` and read tools but no `write`, `edit`, or nested-agent capability. State its read-only, fingerprint-verification, identity-reporting contract. Add focused profile-discovery/tool-declaration coverage. The parent still proves Git status/tree/paths before and after review because shell access can mutate indirectly.
Owner: parent agent, 15-minute implementation checkpoint.
Owned paths:
- `skills/develop/code-review/SKILL.md`
- `skills/design/implement/SKILL.md`
Make a workflow record a first-class specification source without requiring issue-tracker configuration. Pin base and product commits, clean status, tree hash, commit list, exact binary full-index diff command, and SHA-256 digest. Require separate direct reviewers, mutator-identity exclusion, reviewer digest regeneration, before/after mutation checks, non-reviewer remediation, re-verification, and a fresh review. Convert `implement` into a user-only compatibility pointer for bounded assignments and route multi-step implementation through `develop-workflow`; remove self-review and child commit/integration instructions.
### Slice D: exposure, ADR, and historical documentation
Owner: parent agent, 20-minute implementation checkpoint.
Owned paths:
- `package.json`
- `scripts/pi-links.test.mjs`
- `README.md`
- `docs/adr/0006-skill-led-development-workflow-04SEP2026.md`
- workflow-specific notes in ADRs 0001, both 0002 files, 0004, and 0005
- `docs/workflow/README.md`
- `docs/workflow/design.md`
- `docs/workflow/dashboard-mocks.md`
- `docs/workflow/usability-plan.md`
- `extensions/workflow/README.md`
- `docs/nono-dynamic-permissions-plan.md`
- `docs/npm-packages.md`
- `docs/todos.md` only for a progress annotation, if useful
Add ADR 0006 superseding the three custom-engine workflow ADRs while preserving broader package/import decisions in ADRs 0004/0005. Add path-correct historical banners to legacy workflow docs. Mark the extension private, historical, and unrelated to current skill exposure. Replace Nono’s planned legacy workflow-executor integration with the skill’s use of already-approved parent tools and command policies. Keep retirement and pilot TODOs unresolved.
Add `test:develop-workflow` to the full `bun run test` chain. Add a link regression proving the new shared skill is discovered globally while both workflow extension maps remain empty. Update the shared-skill count from 34 to 35; make no manifest exposure entry because discovery is automatic.
### Slice E: verification, review, and integration
Owner: parent agent.
1. Inspect every worker result against before/after branch, HEAD, status, changed paths, and owned paths; reject unexpected commits or paths.
2. Checkpoint the record through the new helper after it exists.
3. Run focused tests after each slice, then `node --test skills/develop/develop-workflow/tests/checkpoint-record.test.mjs`, `node --test scripts/pi-links.test.mjs`, `./scripts/pi-links.mjs check` from the primary checkout where linked-worktree ownership is recognized, `bun run typecheck`, and `bun run test`.
4. Commit focused verified changes. Fetch `origin/main`, rebase when the remote is available, and rerun affected/full checks if the effective tree changes.
5. Pin base, product HEAD, clean status, tree hash, commit list, and `git diff --binary --full-index --find-renames <base>...<product-head> --`; hash those exact bytes with SHA-256 in this record.
6. Launch separate direct standards and specification reviewers using the new reviewer identity. Require matching digest, read-only before/after evidence, and identities distinct from all mutators. Valid findings go to a non-reviewer, followed by verification and fresh review. Escalate after two failed remediation cycles or material scope/architecture change.
7. If local `main` and its checkout remain safe, fast-forward it, add one metadata-only record closure commit, run a cheap sanity check, prove both commits reachable, and remove the worktree/feature branch. The pre-existing dirty source file currently blocks this step; stop for evidence-backed resolution if it remains dirty.
### Rollback
Before integration, abandon only by preserving evidence and obtaining cleanup approval. After integration, revert focused commits rather than rewriting shared history. No force operation, destructive cleanup, push, publish, deployment, or production action is authorized.
## Ownership
The parent agent owns orchestration and this record. Mutating assignment ownership and deadlines will be recorded after discovery and before production edits.
- Parent agent: orchestration, record, skill prose/template/references, review and implement skills, link/package integration, ADR/docs, verification, commits, review brief, integration.
- `checkpoint-implementer`: checkpoint helper and its test only; mutator and reviewer-ineligible.
- `reviewer-profile-implementer`: reviewer profile, README section, and focused profile test only; mutator and reviewer-ineligible.
- Assignment start/stop times, stable child IDs, before/after evidence, and outcomes will be checkpointed before and after each mutating assignment.
## Verification matrix
| Surface | Command | Outcome |
| --- | --- | --- |
| Checkpoint helper | `node --test skills/develop/develop-workflow/tests/checkpoint-record.test.mjs` | Pending |
| Managed links | `node --test scripts/pi-links.test.mjs` and `./scripts/pi-links.mjs check` | Pending |
| Managed-link regression | `node --test scripts/pi-links.test.mjs` | Pending |
| Host exposure | `./scripts/pi-links.mjs check` from the primary checkout after integration | Pending |
| TypeScript | `bun run typecheck` | Pending |
| Full repository | `bun test` | Pending |
| Full repository | `bun run test` | Pending |
| Skill behavior | Fresh-session scenario evaluation and three-change pilot | Deferred and still tracked in `docs/todos.md` |
## Review
- Fixed point: pending final synchronization.
- Specification source: this record and the accepted skill-led workflow plan.
- Mutators: parent agent; additional implementers pending.
- Standards reviewer: pending, must be read-only and independent.
- Specification reviewer: pending, must be read-only and independent.
- Diff fingerprint and findings: pending.
- Review fixed point: pending final synchronization.
- Specification sources: this record and the accepted skill-led workflow plan.
- Mutators: parent agent; `checkpoint-implementer` and `reviewer-profile-implementer` after launch.
- Standards reviewer: pending, must use the new read-only Git-capable profile and be identity-independent.
- Specification reviewer: pending, must use the new read-only Git-capable profile and be identity-independent.
- Product HEAD, tree hash, diff command, SHA-256, findings, remediation cycles, and before/after reviewer state: pending.
## Integration and rollback
Rebase the feature branch onto the latest local/remote `main` when available, rerun verification, independently review the exact diff, then fast-forward local `main`. Roll back before integration by deleting the isolated feature branch only after separate evidence and approval; after integration, revert focused commits rather than rewriting shared history.
Rebase the feature branch onto the latest remote/local `main` when available, reverify, review the exact pinned diff, then fast-forward local `main` only if its checkout is clean and unchanged. Close this record with one metadata-only commit after integration. The current unrelated dirty source change blocks automatic integration until independently resolved. Rollback follows the approved plan above.
## Checkpoints and blockers
- Initial record created before product mutation.
- The source checkout remains dirty with the explicitly omitted artifact-presenter change. Automatic final integration is blocked until the source checkout is clean or the user authorizes an evidence-backed alternative.
- Initial record created and committed at `256f001` before production mutation.
- Three read-only discovery assignments completed without file ownership or mutation.
- Exact plan checkpoint prepared on 04SEP2026.
- Blocker: explicit user approval of this exact plan is required before production edits.
- After approval: record and commit the gate decision, capture Git evidence, then launch the two disjoint mutating assignments and begin the parent-owned skill/docs slice.