Skip to content

Make eltmon/okf the canonical OKF skill; Overdeck vendors a pinned tag #4408

Closed

Description

@eltmon

PRD: https://github.com/eltmon/okf/blob/main/.pan/drafts/okf-v0.2-redesign.md (§6, report id PAN-A)

Depends on: nothing; this can start now
Blocks: OKF-1 (eltmon/okf#1)
Full order: PAN-A #4408 → OKF-1 eltmon/okf#1 → OKF-2 eltmon/okf#2 → (OKF-3 eltmon/okf#3 ‖ OKF-4 eltmon/okf#4 ‖ OKF-5 eltmon/okf#5) → OKF-6 eltmon/okf#6 → (OKF-7 eltmon/okf#7 ‖ OKF-8 eltmon/okf#8) → OKF-9 eltmon/okf#9 (ends with the v0.2.0 tag) → PAN-B #4409 → PAN-C #4410

Transition note (operator decision 2026-09-29). eltmon/okf main now carries .pan/drafts/okf-v0.2-redesign.md (commit 712af54), so its tree no longer matches sync-sources/skills/okf/ and never will again. Work item 0 retires okf-mirror-drift.yml and mirror-okf-skill.sh first, as its own commit, so the drift job cannot fail main on the next push that touches sync-sources/skills/okf/**. Until item 0 lands, do not edit sync-sources/skills/okf/ and do not run the mirror script. The vendor exclude list and the vendor-pin comparison both exclude .pan/.

What OKF-1 needs from this issue: the eltmon/okf items (LICENSE, NOTICE, CI workflow, v0.1.0 tag). The Overdeck-side items (vendor script, pin workflow, sync convergence, doctor warning) can finish in parallel with OKF-1.

Problem

  • sync-sources/skills/okf/ is canonical and is subtree-split to the public eltmon/okf (scripts/mirror-okf-skill.sh, .github/workflows/okf-mirror-drift.yml), so the public repo cannot take fixes.
  • Standalone behaviour is untested.
  • Five copies of the skill exist: the source, the mirror, the installed Claude Code and Codex skill directories (a divergent 2026-09-01 variant not in git), the pan sync staging copy, and per-bundle .okf/scripts.
  • eltmon/okf has no LICENSE.

Design

  • eltmon/okf becomes canonical and is registered as Overdeck project okf with issue_prefix: OKF.
  • Overdeck vendors a tagged tree and CI pins it.
  • pan sync installs the vendored tree everywhere and reports version skew.

Work items
0. First, landable alone: retire the mirror gate. Delete .github/workflows/okf-mirror-drift.yml and scripts/mirror-okf-skill.sh. From the moment this PRD was committed to eltmon/okf (2026-09-29), its tree differs from sync-sources/skills/okf/ permanently, so the drift job would fail the next main push that touches the skill directory, and the mirror script would be rejected as a non-fast-forward. Nobody runs the mirror again. (Workflow-file changes push over SSH; the gh OAuth token lacks workflow scope.)

  1. Operator: pan project add for the eltmon/okf checkout (key okf, prefix OKF, tracker GitHub eltmon/okf). Done 2026-09-29.
  2. eltmon/okf:
    • add LICENSE (MIT) and NOTICE (Apache-2.0 attribution for references/spec.md);
    • add .github/workflows/ci.yml running scripts/selftest.sh for now;
    • tag v0.1.0 at fe73d46 (the last pure-skill commit, byte-identical to overdeck d44e4a9fefe), not at the current tip, which also carries .pan/.
    • This item is work inside eltmon/okf, done by the Overdeck-side agent: expect a cross-repo push.
  3. Overdeck:
    • new scripts/vendor-okf-skill.sh <tag>: fetch the tag tarball, replace sync-sources/skills/okf/ using an explicit exclude list (.github/, .pan/, tests/, CHANGELOG.md, dev tooling), always include LICENSE and NOTICE because the skill is redistributed, and write .okf-skill-version;
    • delete scripts/mirror-okf-skill.sh;
    • replace .github/workflows/okf-mirror-drift.yml with okf-vendor-pin.yml, which compares HEAD:sync-sources/skills/okf against the pinned tag's tree after applying the same exclude list.
  4. src/lib/sync.ts:
    • determine why the 2026-09-01 variant in the installed Claude Code and Codex skill directories survived while the staging copy is current, and make sync converge installed copies to the vendored tree;
    • pan doctor WARNs when an installed okf/.okf-skill-version differs from the vendored one.
  5. Docs: sync-sources/skills/okf/README.md install section; configuration/knowledge.mdx "Where the skill lives".

Acceptance criteria

  • okf-mirror-drift.yml and mirror-okf-skill.sh are gone from main, and no workflow compares against eltmon/okf main.
  • scripts/vendor-okf-skill.sh v0.1.0 produces a tree identical to the tag's filtered tree, with no .github/, .pan/ or tests/ and with LICENSE and NOTICE present. A Vitest test covers the script's arg parsing and the version file.
  • CI fails when a file under sync-sources/skills/okf/ is edited without a re-vendor. Proven by a workflow-dispatch run on a branch with a deliberate edit.
  • After pan sync, diff -r of each installed harness okf skill directory against sync-sources/skills/okf is empty.
  • A unit test covers the doctor skew warning.

Docs: a CLAUDE.md one-liner stating that the OKF skill is edited in eltmon/okf and vendored here, plus the configuration doc.

Activity

  1. eltmon commented on Sep 29, 2026

    @eltmon
    OwnerAuthor

    Work item 0 landed directly on main as abaeeab9647 (2026-09-29): .github/workflows/okf-mirror-drift.yml and scripts/mirror-okf-skill.sh are deleted, so the drift gate can no longer fail main. Skip item 0; start from item 1. The .husky/pre-push comment that mentions the mirror script is now stale; update it as part of this issue.

  2. added
    planningIssue is in planning/discovery phase
    in-progressWork is actively being done
    and removed
    planningIssue is in planning/discovery phase
    in-progressWork is actively being done
    on Sep 29, 2026
  3. eltmon commented on Sep 29, 2026

    @eltmon
    OwnerAuthor

    🤖 Agent completed work:

    No deviations from plan except: D11's live red/green CI checkpoint for okf-vendor-pin (WI-7/pin-workflow) could not run pre-merge — GitHub requires a workflow file to exist on the default branch before workflow_dispatch will trigger it, and no PR existed yet for the pull_request trigger. Followed the PRD's stated fallback: skipped the live proof, reverted the deliberate SKILL.md drift (commits 7307e38 / db96dbb), and documented it (b506e3a). It will run for real once this PR is open (pull_request trigger, scoped to sync-sources/skills/okf/** changes) — please confirm it's green on the PR head before merging.

    All 16 xBRIEF items complete across both repos, with all 49 acceptance criteria individually verified and recorded:

    • eltmon/okf: LICENSE+NOTICE, CI workflow, canonical-repo README install section, tagged and merged v0.1.0 into main (release/v0.1.0 branch, PR Release v0.1.0: LICENSE, NOTICE, CI, install docs okf#10, merge commit 92a21feb).
    • Overdeck: scripts/vendor-okf-skill.sh (vendor + --check modes) with 8 passing Vitest cases plus manual smoke-testing against the real v0.1.0 tag (host CPU contention slowed one vitest run to ~11 min); vendored v0.1.0 into sync-sources/skills/okf/; added the okf-vendor-pin CI workflow; src/lib/vendored-skills.ts; executeSync/planSync and executeAgentSkills/planAgentSkills now converge a locally-edited real copy of a vendored skill instead of reporting it as a conflict (symlinked user checkouts stay untouched); pan sync CLI reports replaced vendored files; pan doctor gained an "OKF Skill Version" check; end-to-end convergence test; docs updated (configuration/knowledge.mdx, CLAUDE.md, .husky/pre-push comment).

    npm run typecheck and npm run lint both pass clean. All touched test files pass.

  4. added
    mergedMerged to main
    verifying-on-mainMerged — awaiting verification on main
    and removed on Sep 29, 2026
  5. eltmon commented on Sep 30, 2026

    @eltmon
    OwnerAuthor

    Closed via close-out ceremony

    Definition of Done
    # Row Status Observed
    1 Review passed ✓ pass PR #4415 reviewDecision: APPROVED
    2 Tests passed ✓ pass PR #4415 checks: all 20 check(s) green
    3 Verification green on the branch ✓ pass verification artifact: passed at 2026-09-29T16:10:47.648Z
    4 Merged to main ✓ pass Pull request #4415 merged at 2026-09-29T16:53:50Z; PR #4415 MERGED at 2026-09-29T16:53:50Z
    5 Post-merge lifecycle ran ✓ pass canonical state: verifying_on_main; no running work/planning agents (stored running, not live: agent-pan-4408, planning-pan-4408)
    6 Verified on main ✓ pass required checks concluded successfully on b836519: test, lint, build (22), reject-planning-paths
    7 Version strings propagated – skip project declares no version_sync; ship step not applicable
    8 Deployed ✓ pass build commit 76fba67 contains merge b836519
    9 Close-out teardown verified ✓ pass workspace removed; feature branch kept (close_out.delete_feature_branch is off); Closed 1 Herdr pane(s); No shadow state found; No legacy planning directory found; No .venv found; Stopped Docker containers; No orphaned processes found; No worker worktrees; Removed git worktree; Pruned 4 agent directories (transcripts and state kept); No strike branch strike/pan-4408 found; Pruned 160 checkpoint ref(s) for agent-pan-4408, planning-pan-4408, strike-pan-4408; No specialist registry entries for PAN-4408

    Gate: passed

  6. added
    closed-outVerified and closed out
    and removed
    mergedMerged to main
    verifying-on-mainMerged — awaiting verification on main
    on Sep 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    closed-outVerified and closed outenhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions