Skip to content
23 changes: 16 additions & 7 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,8 @@ Plugin `bin/` PATH injection is Bash-tool only, not hook commands. All hook `com

As of [spec 016-scaffold-mode](specs/016-scaffold-mode/spec.md) (slices
016-01 + 016-02 + 016-03 all DONE; 016-04 deferred), `scaffold-init` copies the
runtime machinery (`skills/`, `agents/`, `hooks/scripts/`) into the
runtime machinery (`skills/`, `agents/`, `hooks/scripts/`, and — since
[slice 095-01](specs/095-scaffold-template-copy/spec.md) — `templates/`) into the
user's `.claude/` directory under `jig-` prefixed names
(`.claude/skills/jig-<name>/`, `.claude/agents/jig-<name>.md`,
`.claude/hooks/scripts/jig-*.sh`), and generate/merge
Expand Down Expand Up @@ -287,12 +288,20 @@ registration, and hook protocol translation.
host-neutral `HostRenderer` interface plus concrete renderers for Claude
(`ClaudeScaffoldRenderer`) and Codex (`CodexScaffoldRenderer`). Claude
scaffold mode writes `AGENTS.md`, `CLAUDE.md`, `.claude/skills/`,
`.claude/agents/`, `.claude/hooks/scripts/`, and `.claude/settings.json`.
Codex scaffold mode writes `AGENTS.md`, `.codex/skills/`,
`.codex/agents/*.toml`, `.codex/hooks/scripts/`, `.codex/templates/`, and
`.codex/hooks.json` without producing Claude-only files. The templates copy
is runtime support for scaffolded helpers whose source fallback resolves
template paths relative to the materialized jig runtime. Codex also installs
`.claude/agents/`, `.claude/hooks/scripts/`, `.claude/templates/`, and
`.claude/settings.json`. Codex scaffold mode writes `AGENTS.md`,
`.codex/skills/`, `.codex/agents/*.toml`, `.codex/hooks/scripts/`,
`.codex/templates/`, and `.codex/hooks.json` without producing Claude-only
files. **Both** scaffold hosts copy `templates/`: it is runtime support for
scaffolded helpers whose source fallback resolves template paths relative to
the materialized jig runtime (`parents[2]/templates/` — `decisions.py`,
`adr.py`, `migrate.py seed-decisions`, `workflow.py`'s slice-template render,
and `memory.py`'s people.md bootstrap all read it there). Codex
has copied templates since its adapter shipped, because its rewrite table
redirects `${CLAUDE_PLUGIN_ROOT}/templates/` into `.codex/templates/`; the
Claude side gained the copy in [slice 095-01](specs/095-scaffold-template-copy/spec.md)
([ADR-0038](decisions/adr-0038-claude-scaffold-template-copy.md)), which is
what makes record-seeding work in a scaffolded project with no plugin root. Codex also installs
non-discoverable unprefixed helper aliases under `.codex/skills/<name>/`
without `SKILL.md`; these preserve existing peer-helper imports such as
`skills/scaffold-init/scaffold.py` without registering duplicate skills.
Expand Down
43 changes: 43 additions & 0 deletions docs/bugs/012-decisions-no-template-backfill.md
Original file line number Diff line number Diff line change
Expand Up @@ -312,6 +312,49 @@ Run: `python3 skills/memory-sync/test_decisions.py` (30 OK) ·
Recorded in [docs/memory/learnings.md](../memory/learnings.md) — "Bug 012: an
init-time-only seed is a permanent gap for every existing project".

## Amendments

Per [ADR-0010](../decisions/adr-0010-amendment-scope-records-vs-live-prose.md):
this record is closed (`status: DONE`), so its prose above is preserved as written
and corrections are appended here, dated.

### 2026-07-16 — `## Remaining risk` is closed

**Closed by [slice 095-01](../specs/095-scaffold-template-copy/slice-01-claude-scaffold-templates.md)
/ [ADR-0038](../decisions/adr-0038-claude-scaffold-template-copy.md).** The design
call this record deferred to the maintainer — should `copy-machinery` ship
`templates/`, or should record helpers embed their templates? — came back as
**option (a)**: `copy_machinery` now copies `templates/` into `.claude/templates/`,
mirroring `_copy_codex_templates`. The copied helpers' `parents[2]/templates/`
fallback therefore resolves, with no change to any helper's template
*resolution* (several helpers' comments and error messages — including this
bug's — were re-premised; that is prose, not behaviour).

What that changes in the record above:

- **`## Remaining risk` no longer describes reality.** The captured probe
(`env -u CLAUDE_PLUGIN_ROOT … decisions.py add-lightweight` →
`error: lightweight-decisions template not found`) now exits 0 and seeds the
record home. Read that section as the state at the time of this fix.
- **`## Fix class`'s "Honest scope" qualifier is spent.** `fix_class:
structural_fix` was qualified as structural for **plugin-mode** installs
because the scaffold-mode variant stayed open. With 095-01 landed it holds for
all four install modes; the frontmatter field is unchanged and now unqualified.
- **The "inherited, not invented" bullet is discharged.** `adr.py`'s identical
gap closed with the same copy — it needed no mitigation of its own, which was
the argument for fixing the family rather than this helper.
- **The mitigation survives, re-premised.** The remedy-naming failure this bug
shipped is now the **broken-install** guard (a copy predating 095-01, a partial
tree, a `CLAUDE_PLUGIN_ROOT` aimed at a non-jig root). `UnreachableTemplateTests`
was re-premised rather than deleted, and the message gained
`migrate copy-machinery` as the remedy that repairs the install instead of
working around it.

Still open, deliberately: whether a `migrate copy-machinery` re-run is the
sanctioned backfill for projects scaffolded *before* 095-01, and whether `migrate
report` should flag the gap. Spec 095 declared it out of scope; asked on
[#109](https://github.com/ramboz/jig/issues/109).

## Main recheck

- 2026-07-16 - `origin/main@91427b4` -> reproduces: Detached worktree at origin/main@91427b4. Mode 1 (no LD file): 'add-lightweight --title probe --decision probe' -> exit 1, 'error: no docs/decisions/lightweight-decisions.md — scaffold the lightweight-decisions home first'. Mode 2 (hand-rolled LD table): same command -> exit 1, 'error: docs/decisions/lightweight-decisions.md is missing its `## Entries` heading — cannot place the entry', file left untouched. migrate.py on main offers only {report,rename-decisions,split-slices,copy-machinery,adopt-layout} — no seed op. All three confirmed.
1 change: 1 addition & 0 deletions docs/decisions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@
- [ADR-0035: Active Plan-mode driving for the plan phase (extends ADR-0027)](adr-0035-active-plan-mode-driving.md) — [ADR-0027](adr-0027-host-native-phase-modes.md) adopted **mode-aware, not mode-dependent**: host planning/implementation modes are *advisory* affordances, never lifecycle state or gate inputs. (2026-07-06, Proposed)
- [ADR-0036: Immutable Release Identity](adr-0036-immutable-release-identity.md) — Jig publishes semantic versions and release tags, but its root Claude marketplace currently fetches `hosts/claude` from the repository default branch without a `ref` or `sha`. (2026-07-14, Accepted)
- [ADR-0037: Bug-fix repository closure evidence](adr-0037-bug-fix-repository-closure-evidence.md) — The bug lifecycle proves diagnose-before-fix, fresh-main reproduction, and a red-to-green regression test. (2026-07-15, Proposed)
- [ADR-0038: Claude scaffold mode copies templates/](adr-0038-claude-scaffold-template-copy.md) — jig's record helpers seed their files from the shipped `templates/` tree: `decisions.py` creates `docs/decisions/lightweight-decisions.md` (bug 012), and `adr.py new` renders `adr-0000-template.md`. (2026-07-16, Accepted)

## Lightweight decisions

Expand Down
Loading
Loading