Skip to content

add /ctx-task-out — close the spec→implement gap in the canonical chain#126

Merged
josealekhine merged 3 commits into
mainfrom
feat/ctx-task-out
Jul 4, 2026
Merged

add /ctx-task-out — close the spec→implement gap in the canonical chain#126
josealekhine merged 3 commits into
mainfrom
feat/ctx-task-out

Conversation

@josealekhine

Copy link
Copy Markdown
Member
add /ctx-task-out: close the spec→implement gap (+ Claude 5 context-window fix)

Summary

The design-to-implementation chain had an unowned artifact: /ctx-plan
disclaims implementation planning, /ctx-spec commits the what/why at
spec altitude, and /ctx-implement opens with "use when you have a
plan document" — which nothing in the chain produced. This PR adds the
missing fourth step:

/ctx-brainstorm → /ctx-plan → /ctx-spec → /ctx-task-out → /ctx-implement
    (vague)     (contested)  (committed)   (decomposed)     (execution)

/ctx-task-out decomposes a committed spec into a per-milestone plan
at specs/plans/<milestone>.md — data model, contracts, invariant test
matrix, and commit-sized tasks with falsifiable acceptance criteria.
Its signature move matches the rest of the chain: it refuses to run
ahead of its inputs (blocking-TBD gate, rolling-wave gate, milestone
boundaries owned by the spec) rather than degrading. The plan is the
execution ledger; TASKS.md carries epic-level anchors only.

Also included: a fix for Claude 5 family context-window detection —
claude-fable-5 sessions fell to the 200k default and the
check-context-size hook warned "104% full" on a 79%-free 1M session.

Commits

  1. 7c1eb0e3 — add /ctx-task-out (Spec: specs/ctx-task-out.md)
    • New skill, claude + copilot-cli parity (generated via
      hack/sync-copilot-skills.sh), registered in the permissions
      allowlist and ctx init workflow tips
    • 5-step chain across skills, playbook templates, and docs
    • /ctx-spec: tasking handoff in interactive and --brief flows
    • /ctx-implement: names specs/plans/<milestone>.md as canonical
      input, redirects bare multi-milestone specs, refuses
      Status: Blocked plans, owns plan checkbox updates
    • Project template specs-README lifecycle gains the task-out step
    • Docs: skills reference (including the previously missing
      /ctx-plan section and its dead anchor), common-workflows,
      integrations, three recipes
  2. 500c4a07 — fix context window detection
    (Spec: specs/model-context-window-fable.md)
    • ModelContextWindow maps the always-1M families: fable,
      mythos, sonnet-5 (alongside existing opus and [1m])
    • sonnet-4-6 deliberately unchanged (Claude Code gates its 1M
      behind the [1m] opt-in — see spec Non-Goals and DECISIONS.md)
  3. f37fd9fe — chore: refresh go.work.sum
    (Spec: specs/meta/chores.md)

Design notes for reviewers

The skill went through two external review rounds before landing.
Load-bearing pieces to scrutinize, in the order the work order's
Review section prescribes:

  1. Gate behavior — blocking-TBD refusal, rolling-wave refusal,
    Status: Blocked reachable only via amendment (fresh runs refuse
    and write nothing)
  2. Authority discipline — decompose, don't redesign the bet;
    invariants come from the spec (unstated invariant = spec gap, mark
    TBD, never mint); TBD resolutions live in the spec or DECISIONS.md,
    the plan only points at them
  3. Execution ledger — plan owns task/DoD checkboxes,
    /ctx-implement updates them, rolling-wave gate reads DoD only
  4. Amendment mode — obsolete-and-append, ids never reused,
    acceptance criteria never edited in place once a task starts
  5. Chain-text consistency — grep for 4-step remnants returns none

Verification

  • Full gate green pre- and post-commit: build, go vet, gofmt,
    lint-drift, style/version/why/copilot-sync checks, go test ./...
    zero failures (golangci-lint runs in CI; not installed locally)
  • gitnexus detect_changes: 66 symbols across 21 files, 0 affected
    execution flows, risk LOW
  • Window fix verified by table test (fable/mythos/sonnet-5 → 1M;
    sonnet-4-6 → 200k pinned)
  • Blocking-TBD gate verified read-only against zhc/os
    specs/v1-substrate.md (D-001 open → refusal fires by construction)

Not in this PR / follow-ups

  • site/ regeneration (make site) — generated output, rebuilt
    separately
  • Reinstall (make build && sudo make install) so the live hook
    stops misreporting and the plugin picks up the skill
  • First real /ctx-task-out run: zhc/os v1-substrate.md m0a
    (expected: D-001 refusal; then the plan after D-001 resolves)
  • docs/reference/skills.md drift sweep: 7 skills still
    undocumented (ctx-architecture-enrich, ctx-code-review,
    ctx-config, ctx-dream, ctx-explain, ctx-refactor,
    ctx-serendipity) plus a stale ctx-prompt row
  • allow.txt / write.yaml omit /ctx-plan itself (pre-existing)

…hain

The design-to-implementation chain had an unowned artifact:
/ctx-plan disclaims implementation planning, /ctx-spec commits the
what/why at spec altitude, and /ctx-implement opens with "use when
you have a plan document" that nothing in the chain produced.
/ctx-task-out decomposes a committed spec into a per-milestone plan
at specs/plans/<milestone>.md - data model, contracts, invariant
test matrix, and commit-sized tasks with falsifiable acceptance
criteria - and enforces refusal gates instead of degrading:
blocking-TBD, rolling-wave, and milestone boundaries owned by the
spec. The plan is the execution ledger; TASKS.md carries epic
anchors only.

Changes:
- new skill (claude + copilot-cli parity), registered in the
  permissions allowlist and init workflow tips
- chain diagrams updated to 5 steps across skills, playbook
  templates, and docs
- /ctx-spec gains the tasking handoff in interactive and --brief
  flows; /ctx-implement names the plan artifact, redirects bare
  multi-milestone specs, refuses Status: Blocked plans, and owns
  plan checkbox updates
- project template specs-README lifecycle gains the task-out step
- docs: skills reference (including the missing /ctx-plan section
  and its dead anchor), common-workflows, integrations, recipes

Spec: specs/ctx-task-out.md
Signed-off-by: Jose Alekhinne <jose@ctx.ist>
ModelContextWindow recognized 1M windows only via the [1m] suffix
or the opus substring, so claude-fable-5 sessions fell through to
the 200k default and every consumer of EffectiveContextWindow -
the check-context-size hook, heartbeat, nudges, provenance -
computed against the wrong window (a 21%-used 1M session warned
"104% full"). Map the always-1M families: fable, mythos, and
sonnet-5 (1M as standard per the current model catalog; earlier
Sonnets keep the [1m] opt-in path, deliberately unchanged).

Spec: specs/model-context-window-fable.md
Signed-off-by: Jose Alekhinne <jose@ctx.ist>
Lockfile hash additions picked up by the Go toolchain; no
dependency changes in go.mod/go.work.

Spec: specs/meta/chores.md
Signed-off-by: Jose Alekhinne <jose@ctx.ist>
@josealekhine josealekhine self-assigned this Jul 4, 2026
@josealekhine josealekhine requested a review from bilersan as a code owner July 4, 2026 02:34
@josealekhine josealekhine merged commit 4a14ef9 into main Jul 4, 2026
17 checks passed
@josealekhine josealekhine deleted the feat/ctx-task-out branch July 4, 2026 03:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant