SpecsCLIScaffold, Managed Skill, and Operator Follow-ups
Scaffold, Managed Skill, and Operator Follow-ups Implementation Notes
Implementation Notes
Summary
- Execution started from the clean child branch based on live PR #123 head.
- Shared-skill authority fixes are pushed at immutable tag
sync/scaffold-skill-followups-408746ad5fdf. - Scoped prompt authoring now stays within a 700-line fixed-fixture budget while preserving activation and validation seams.
- Candidate archive/consumer semantics have an honest pre-sync RED for the malformed Effect table.
- Exact-ref synchronization turned the archive/consumer semantic contract green with only three generated packaged-file changes.
- Operator commands recognize supported Codex markers without a Harness-owned prompt while preserving one explicit Skills CLI target.
Deviations From the Plan
- The control-plane recovered before closeout.
hi check --jsonnow resolves authority but reports broad pre-existing active-projection/settings drift, so no update was applied.
Surprises and Decisions
- PR #123 was rebased after the user captured
435af1ec; the child uses live equivalent headfb8c216fto preserve valid ancestry. - Active repository managed projections remain untouched while control-plane baseline authority is unavailable. Candidate-baseline consumer tests own projection proof.
- AI-context Markdown requires explicit
writing-for-agentsapplication evidence; file type alone is not sufficient proof. sync:skillstreats an unprefixed ref asrefs/heads/*; immutable tags require the explicitrefs/tags/*form.- The supported fixture refresh also regenerates bundled baseline identity and context outcome provenance; wiki content sync owns the mirrored runbook projection.
- Authority recovery changed the scaffold check from unavailable to an evidence-backed drift report; the report spans unrelated active skills and settings, so candidate archive/consumer proof remains this branch's bounded projection validation.
Steering
| Date | Feedback | Changes |
|---|---|---|
| 2026-08-12 | Apply writing-for-agents to every AI-context Markdown change. | Added a plan invariant, reinforced active worker briefs, and required per-task skill evidence. |
Sanity Checks
| Check | Result | Notes |
|---|---|---|
| Child ancestry | pass | Branch started exactly at live PR #123 head fb8c216f. |
| Shared source | pass | Immutable tag and branch resolve 408746ad5fdf10d75513cd1b63c71c6f22fa7fb7; shared suite passed 104/104. |
| CLI focused suites | pass | Prompt/scaffold passed 51/51; operator/config/adapter passed 55/55; archive/consumer semantic target passed. |
| Generated projections | pass | Managed fixture, bundled identity, context outcome, and wiki runbook were refreshed only through owning generators. |
| Baseline file | partial | Required semantic case passes; unrelated publisher fixture remains spawnSync git ENOENT under its mocked PATH. |
hi check --json | partial | Authority resolved; command reports broad pre-existing active projection/settings drift. No write was applied. |
| Repository check | pass | bun run check passed all 12 workspace tasks. |
| Repository test | partial | Root/non-CLI/runtime/wiki gates and one 23-test CLI update shard passed; the runner terminated three remaining long update shards with SIGTERM and no assertion failure. |
| Frozen review | pass | Final standards and spec axes pass after repairing pointer wording and wiki frontmatter. |
| Stack | pass | Draft PR #127 targets PR #123; applied sync confirms main -> #123 -> #127. |
Skill Application Evidence
| Task | Skill | Status | How/where | Not-applicable reason and assessment location |
|---|---|---|---|---|
| T1 | writing-for-agents | applied | Canonical delivery routing, Effect reference, and docs-onboarding Markdown keep singular authority, exact conditions, and compact positive instructions. | |
| T1 | tdd | applied | Three public source contracts failed before the minimal fixes and pass afterward. | |
| T1 | codebase-design | applied | Canonical skill Markdown remains the interface; synchronization remains a later adapter task. | |
| T1 | simplify | applied | Only defect-bearing source rows and their contracts changed. | |
| T2 | writing-for-agents | applied | Governing spec, generated prompt Markdown, handoff, and summary use repository invariants plus exact-trigger pointers without copying skill semantics. | |
| T2 | tdd | applied | Public rendered-Markdown assertions captured missing compactness, the 705-line boundary, and duplicated handoff policy before production edits. | |
| T2 | codebase-design | applied | renderPromptSpecMarkdown remains the single detailed renderer seam. | |
| T2 | quality-types | applied | Existing typed inputs remain unchanged; no parallel descriptive state was added. | |
| T2 | simplify | applied | Repeated generic authoring prose and handoff checklist were removed. | |
| T4 | writing-for-agents | not applicable | No AI-context Markdown changed. | T4 owns one executable baseline test. |
| T4 | tdd | applied | Candidate archive and consumer contract captured the pre-sync RED and passes after exact-ref synchronization. | |
| T4 | codebase-design | applied | One semantic helper verifies both distribution boundaries. | |
| T4 | simplify | applied | One focused contract covers archive and consumer without production changes. | |
| T3 | writing-for-agents | not applicable | No AI-context Markdown changed. | T3 owns executable TypeScript and tests only. |
| T3 | tdd | applied | Packaged CODEX_CI execution prompted before the marker fix. | |
| T3 | codebase-design | applied | Host detection stays at the runtime boundary; mutation stays in the Skills CLI adapter. | |
| T3 | quality-types | applied | One typed marker map drives detection and forwarding. | |
| T3 | effect | applied | Typed invalid-context failure and injected operation seam remain intact. | |
| T3 | simplify | applied | Detection and forwarding share one marker source. | |
| T5 | writing-for-agents | applied | Accepted exact canonical bytes through the generator and verified full-tree parity; no manual AI-context rewrite occurred. | |
| T5 | repo-asset-management | applied | Packaged skill assets came only from the supported exact-ref sync adapter. | |
| T5 | tdd | applied | The pre-sync archive/consumer semantic RED became GREEN after synchronization. | |
| T5 | simplify | applied | Generated tracked delta is limited to three expected packaged files; docs onboarding was already current. | |
| T6 | writing-for-agents | applied | Durable docs keep installed skills authoritative, inline stable repository invariants, co-locate operator targeting behavior, and keep exact fixture detail in one runbook. | |
| T6 | tdd | applied | Existing public contracts and the pre-sync semantic RED bound the documented behavior; generated changes were accepted only after those contracts passed. | |
| T6 | codebase-design | applied | Executable changes use CHANGELOG.md; distributed baseline changes use BASELINE_CHANGELOG.md; projections remain generator-owned. | |
| T6 | simplify | applied | Temporary candidate lineage was removed from repeated durable docs and retained in release/implementation evidence. | |
| T7 | review | applied | Frozen standards review found and repaired a circular skill pointer plus invalid wiki frontmatter; frozen spec review passed. | |
| T7 | writing-for-agents | applied | The repaired pointer has one concrete branch: explicit <id> invocation discloses the installed skill body; model discovery stays in the installed description. | |
| T7 | simplify | applied | One repeated sentence remains in distinct public-output owners; sharing it would add cross-renderer coupling without reducing behavior concepts. |
Acceptance Criteria Status
| Criterion | Status | Notes |
|---|---|---|
| AC-001 through AC-008 | pass | Focused contracts, candidate distribution readback, exact-ref parity, and frozen spec review pass. |
Manual Review Checklist
| Area | Check | How to perform | Expected result |
|---|---|---|---|
| Prompt output | Inspect a representative scoped prompt spec. | Run the fixed 15-scope content contract. | Exact-trigger pointers, Source Guide, mirror, and validation seams remain within 700 lines. |
| Operator targeting | Exercise both Codex markers and unknown-host modes. | Run focused public-output/operator tests. | Recognized Codex hosts skip the prompt; unknown-host behavior is preserved; child calls have one agent. |
| Skill distribution | Build/extract candidate and scaffold isolated consumer. | Run the focused baseline semantic target. | Delivery repair gate, three-cell Effect row, and hi init survive archive and consumer projection. |
| Stack | Inspect PR base and ancestry. | Compare child merge-base and GitHub base. | PR #123 remains parent; child PR targets its branch. |
Pre-existing Issues
hi check --jsonnow reaches the current baseline and reports broad drift across active skills/settings inherited by this checkout. Applying that unrelated projection rewrite is outside this branch.
Remaining Work
- Parent PR #123 merges first. Then rebase this child onto
main, retarget PR #127 tomain, and merge it second.