"Workflow/skill wiring for visual deliverables - task folder scaffolding + template@1 citations in authoring contracts"
TASK-SKILL-120: Deliverable scaffolding wiring
§1 - Description
The authoring path catches up with the new layout and the templates module, so every future deliverable is born in the right shape.
Normative clauses:
/create-tasksstep flow MUST scaffold each new task as<module>/<STEM>/spec.md(+assets/on first asset) and write the audit as<STEM>/audit.md; all path examples in the command doc updated.task-authorMUST document the folder layout in its artefact section (spec.md naming, sibling audit, relative asset references) and namemodules/templates/contracts/TEMPLATE.mdas the presentation contract its output is rendered through (informative pointer - authoring stays markdown).task-auditMUST resolve<STEM>/audit.mdas the report path for folder-layout tasks while keeping.audit.mdsibling resolution for any legacy flat file it is pointed at (transition note, one release).- The ship workflow doc's artefact-path examples and the backlog-state-update evidence citations MUST use the folder paths;
install.shMUST scaffolddocs/tasks/ready for folder-layout tasks (no flat-file example remains in scaffolded docs). - Asset discipline MUST be stated where authors read it (author SKILL.md + command doc): assets live in the task's own
assets/, referenced relatively; no cross-task asset reaches into another task's folder.
§2 - Why this design
Contracts drive agents; if the contracts still describe flat files, every new task fights the migration. One doc-wiring task right after the layout task keeps the fleet coherent.
§4 - Acceptance criteria
- Command scaffolds folders (§1 #1) - command doc contains the folder grammar and no flat-file instruction (grep).
- Author/audit contracts updated (§1 #2, #3) - artefact sections name spec.md/audit.md + the TEMPLATE.md pointer; legacy transition note present in the audit skill.
- Ship + init coherent (§1 #4) - workflow doc examples use folder paths; install.sh-scaffolded docs carry none of the old grammar.
- Asset discipline stated (§1 #5) - both author-facing docs carry the own-assets rule (grep).
§5 - Verification
Doc assertions (grep-level, executable in scripts/tests/test_task_layout.sh t07-t10 extension): command grammar, contract sections, workflow examples, asset rule. (AC 1-4.)
§3 - Contract
Scaffold grammar: docs/tasks/<module>/<STEM>/spec.md; audit: <STEM>/audit.md; assets: <STEM>/assets/<file> referenced as assets/<file>.
§6 - Implementation skeleton
Four doc edits + install.sh template sweep; the t07-t10 asserts ride the TASK-DOCS-004 suite.
§7 - Dependencies
TASK-DOCS-004 (layout must exist first). Informative link to TASK-TPL-001's contract.
§8 - Example payloads
Author scaffold: mkdir -p docs/tasks/ten/TASK-TEN-301-rls-sweep && $EDITOR .../spec.md
§9 - Open questions
None blocking. Whether OTHER deliverable classes (SOW, PRD...) also become folders is decided per-contract later; TEMPLATE.md already renders them.
§10 - Failure modes inventory
- Agent follows stale cached contract - trigger tests unchanged, but contract text is what ships in the payload; next /install update refreshes fleets.
- Legacy flat task appears post-migration (old branch merge) - audit skill's transition note covers reading it; regen warns loudly (TASK-DOCS-004 #4) making it visible.
- Asset reach-across - stated rule + review; renderer resolves only own-folder assets (TASK-DOCS-005 fails missing assets loudly).
- init scaffolds diverge from repo docs - t09 greps the scaffolded output too.
- Plugin copy drift - payload rebuild vendors the edited docs; version-sync gate carries them.
§11 - Implementation notes
Keep the transition note dated; one release later it drops (same sunset pattern as backlog-state-update @1).
End of TASK-SKILL-120.
Audit
TASK-SKILL-120 audit
§1 - Verdict summary
Audited for contract coherence (no doc left describing the dead layout) and transition safety (legacy read path kept one release). TRACE closes: #1->AC1, #2/#3->AC2, #4->AC3, #5->AC4 -> t07-t10 extension asserts.
§2 - Findings (resolved during authoring)
ISS-001 audit skill hard-cutting .audit.md would break pointed-at legacy files - resolved: dual resolution + dated sunset (§1 #3).
§3 - Resolution
Score = 10/10.
End of TASK-SKILL-120 audit.
§4 - Ship record (2026-07-12, batch mode)
- Implemented: command doc folder-scaffolding section, author SKILL.md layout + TEMPLATE.md pointer, audit SKILL.md dual resolution + dated transition window, ship workflow audit-path grammar, install.sh next-steps example. t07-t10 asserts riding test_task_layout.sh (10/10 total).
- HITL: operator standing batch verdict recorded.
Verdict unchanged: PASS, Score = 10/10.