Skip to content

feat: add optional tasks-axi groundwork - #55

Merged
kunchenguid merged 3 commits into
mainfrom
fm/fm-taxi-adopt-s4
Jun 23, 2026
Merged

kunchenguid merged 3 commits into
mainfrom
fm/fm-taxi-adopt-s4

Conversation

@kunchenguid

Copy link
Copy Markdown
Owner

Intent

Land ONLY the inert, no-op groundwork for adopting the published tasks-axi CLI in firstmate's backlog management; explicitly DEFER routing any backlog mutations through tasks-axi.

Background and decision: an earlier wider version of this change also instructed firstmate to perform backlog mutations via tasks-axi verbs. Review correctly flagged (and I empirically confirmed) that tasks-axi v0.1.0 is NOT format-compatible with firstmate's backlog: (a) In-flight lines use '- [ ] - ...' (firstmate docs AND the bin/fm-backlog-handoff.sh awk matcher), but tasks-axi only reads/writes '- - ...', so existing in-flight items are invisible to tasks-axi (NOT_FOUND) and tasks-axi-written items are unmatched by the helper; (b) firstmate's 'blocked-by: - ' form is not parsed by tasks-axi, which swallows it into the title and reports the item as ready, risking premature dispatch of blocked work. The captain reviewed these findings and chose to ship only the inert pieces now and defer mutation-adoption until a tasks-axi release parses firstmate's format.

What this change deliberately does:

  • fm-bootstrap.sh: detect tasks-axi on PATH as an OPTIONAL capability that prints a single 'TASKS_AXI: available' fact line. It is intentionally NOT in the required TOOLS list, so it can never be a 'MISSING:' line and never prompts an install; absent => prints nothing (strict no-op via a single '&&' short-circuit). Header comment documents it as optional, never required.
  • Add a tracked .tasks.toml at repo root pinning the markdown backend to data/backlog.md (archive data/done-archive.md, done_keep 10). data/ is gitignored but .tasks.toml at root is tracked and intentionally applies to every firstmate home (main + secondmates), which all use data/backlog.md. This file is INERT right now - nothing is instructed to run tasks-axi mutations.
  • AGENTS.md (CLAUDE.md is a symlink to it): section 3 gains a 'TASKS_AXI: available' handling bullet that records the capability silently and EXPLICITLY states firstmate does NOT route mutations through tasks-axi yet (deferred), so it keeps hand-editing data/backlog.md exactly as today; section 10 keeps its existing backlog format spec block byte-intact and gains ONE deferred-adoption note sentence. There is intentionally NO instruction anywhere to use tasks-axi for mutations.

Deliberately OUT of scope (do not flag as omissions): no tasks-axi verb adoption (intentionally removed per the captain's decision); no migration or reformatting of backlog content; no change to the backlog FORMAT or section structure; no auto-install or making tasks-axi required. The net behavior change when tasks-axi is absent is zero, and when present is only the inert detection line plus a tracked config file that nothing yet consumes.

What Changed

  • Adds inert tasks-axi groundwork by tracking .tasks.toml for the existing data/backlog.md markdown backend.
  • Updates bootstrap to report TASKS_AXI: available only when the optional CLI is present, without making it a required dependency or prompting install.
  • Documents, captain, that backlog mutations remain hand-edited for now and that tasks-axi mutation adoption is deferred until format compatibility is resolved.

Risk Assessment

✅ Low: Captain, the change is narrow, documented as inert, and the prior PATH-leak test risk has been addressed without adding new material runtime risk.

Testing

Captain, I ran the targeted bootstrap test, manually exercised the end-user bootstrap command with tasks-axi absent and present, verified the required-tool list and deferred-adoption docs, captured the CLI transcript as evidence, and confirmed the worktree stayed clean.

Evidence: Optional tasks-axi bootstrap transcript

Manual bootstrap evidence shows no output when tasks-axi is absent, TASKS_AXI: available when present, and .tasks.toml points at data/backlog.md.

Manual bootstrap evidence for optional tasks-axi detection

Case 1: all required tools available, tasks-axi absent
$ PATH=<fake required tools> FM_HOME=<empty firstmate home> ./bin/fm-bootstrap.sh
<no output>

Case 2: same environment, tasks-axi present on PATH
$ PATH=<fake required tools plus tasks-axi> FM_HOME=<empty firstmate home> ./bin/fm-bootstrap.sh
TASKS_AXI: available

Tracked tasks-axi config
$ sed -n '1,80p' .tasks.toml
backend = "markdown"

[markdown]
path = "data/backlog.md"
archive = "data/done-archive.md"
done_keep = 10

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed ✅
  • 🚨 bin/fm-bootstrap.sh:104 - Line 104 now emits TASKS_AXI: available whenever tasks-axi is anywhere on PATH, but tests/fm-bootstrap.test.sh prepends its fake toolchain while preserving the real PATH and still asserts empty bootstrap output for the all-good case. Captain, on machines with tasks-axi installed, that test will fail even though the feature is behaving as intended; shim/hide tasks-axi in the test or allow the optional capability line.

🔧 Fix: Captain, isolate optional tasks-axi bootstrap tests
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

  • bash tests/fm-bootstrap.test.sh
  • Controlled-PATH manual check: PATH=&lt;fake required tools&gt; FM_HOME=&lt;empty firstmate home&gt; ./bin/fm-bootstrap.sh with tasks-axi absent produced no output.
  • Controlled-PATH manual check: PATH=&lt;fake required tools plus tasks-axi&gt; FM_HOME=&lt;empty firstmate home&gt; ./bin/fm-bootstrap.sh produced exactly TASKS_AXI: available.
  • awk &#39;/^TOOLS=/{print; exit}&#39; bin/fm-bootstrap.sh plus targeted rg checks verified tasks-axi is not required and AGENTS.md says mutation adoption is deferred.
  • git status --short verified testing left no transient worktree files.
✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

…ion deferred)

Ship only the inert pieces of tasks-axi adoption:
- fm-bootstrap.sh detects tasks-axi on PATH as an OPTIONAL capability
  (prints 'TASKS_AXI: available'); never a MISSING line, never an install
  prompt, strictly silent when absent.
- Tracked .tasks.toml at repo root pins the markdown backend to
  data/backlog.md (done_keep=10) for every firstmate home.
- AGENTS.md records the capability silently and explicitly DEFERS routing
  backlog mutations through tasks-axi: firstmate keeps hand-editing
  data/backlog.md byte-for-byte as today.

Adoption is deferred because tasks-axi v0.1.0 does not parse firstmate's
backlog format: In-flight lines (- [ ] <id>, also matched by
fm-backlog-handoff.sh) and blocked-by-with-reason lines are invisible or
mis-parsed, which would drop in-flight tasks and prematurely dispatch
blocked work. The backlog format spec and section structure are unchanged.
@kunchenguid
kunchenguid merged commit 7651a3c into main Jun 23, 2026
4 checks passed
@kunchenguid
kunchenguid deleted the fm/fm-taxi-adopt-s4 branch June 23, 2026 19:25
augustomklee added a commit to augustomklee/firstmate that referenced this pull request Jun 24, 2026
Port upstream batch 3: optional tasks-axi backlog support (kunchenguid#55 + kunchenguid#60)
leo1oel added a commit to leo1oel/nemo that referenced this pull request Jun 25, 2026
Port upstream tasks-axi support (kunchenguid#55/kunchenguid#60) adapted to the herdr/Claude-only
fork: provisioning lives in the dotfiles update-tools.sh axi loop (this fork
has no fm-bootstrap), and a compatible tasks-axi is optional everywhere.

- .tasks.toml: pin the tasks-axi markdown backend to data/backlog.md
  (done_keep=10, archive data/done-archive.md)
- bin/fm-tasks-axi-lib.sh: shared 0.1.1+ compatibility probe
- bin/fm-teardown.sh: route the post-teardown reminder through tasks-axi
  done/ready when compatible, else the hand-edit fallback; the secondmate
  retirement path keeps its data/secondmates.md hint
- AGENTS.md sections 2/3/7/10, README, CONTRIBUTING: document the verb
  mapping and present-or-absent fallback; add .tasks.toml to tracked material
- tests/fm-teardown.test.sh: compatible-tasks-axi reminder test
vipentti pushed a commit to vipentti/firstmate that referenced this pull request Aug 5, 2026
* feat: detect tasks-axi capability and pin .tasks.toml (mutation-adoption deferred)

Ship only the inert pieces of tasks-axi adoption:
- fm-bootstrap.sh detects tasks-axi on PATH as an OPTIONAL capability
  (prints 'TASKS_AXI: available'); never a MISSING line, never an install
  prompt, strictly silent when absent.
- Tracked .tasks.toml at repo root pins the markdown backend to
  data/backlog.md (done_keep=10) for every firstmate home.
- AGENTS.md records the capability silently and explicitly DEFERS routing
  backlog mutations through tasks-axi: firstmate keeps hand-editing
  data/backlog.md byte-for-byte as today.

Adoption is deferred because tasks-axi v0.1.0 does not parse firstmate's
backlog format: In-flight lines (- [ ] <id>, also matched by
fm-backlog-handoff.sh) and blocked-by-with-reason lines are invisible or
mis-parsed, which would drop in-flight tasks and prematurely dispatch
blocked work. The backlog format spec and section structure are unchanged.

* no-mistakes(review): Captain, isolate optional tasks-axi bootstrap tests

* no-mistakes(document): Sync tasks-axi documentation
pranaypratyush pushed a commit to pranaypratyush/firstmate that referenced this pull request Aug 25, 2026
…kunchenguid#55)

* fix: make no-mistakes docs gate risk-based

* no-mistakes(document): document risk-based gate's new Markdown CI jobs

* no-mistakes: apply CI fixes

* Revert "no-mistakes: apply CI fixes"

This reverts commit 9d21f63.
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