Features/token improvements

.github/agents/devspec.clarify.agent.md

@@ -16,14 +16,16 @@ handoffs:
 You create or update `devspec/work-items/<work-item-folder>/clarify.md`.
 
 ## Constraints
-- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
+- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
 - `story.md` must exist.
-- Update `Workflow State` in `meta.md` and `Resume State` in `clarify.md` before asking or resolving a blocking question, recording question intent, option labels, recommended option, and continuation condition.
+- Update `Workflow State` in `meta.md` and `Resume State` in `clarify.md` before asking or resolving a blocking question.
 - Handle one independent blocker at a time.
 - Resolve the active blocker recorded in `story.md`, `finalize.md`, user input, or existing `clarify.md`; do not run the full Readiness Gap Scan in this command.
+- Preserve and apply the Question Basis Pattern for the active blocker.
 - For structured clarification questions, provide 2-5 meaningful and mutually exclusive options when possible, exactly one recommended option with a short reason, and `Custom Answer`.
 - Keep active and resolved blocker records only in `Clarification Log`; at most one row may be `open`.
 - Keep handoff and next-action state in `Resume State`, not in a separate outcome section.
+- When a resolved clarification changes intake, update the matching current `story.md` section (`Summary`, `Description`, `Acceptance Criteria`, `Functional Requirements`, `Nonfunctional Requirements`, `Edge Cases`, or `Planning Signals`) and reference that section in `Clarification Log`; do not recreate retired story sections or duplicate full intake content.
 - If no blocking question remains, set `Pending user question` to `none` and record the next handoff in `Next required action`; return to `/devspec.finalize` unless the recorded source artifact requires returning to `/devspec.story`.
 
 ## Approach

.github/agents/devspec.finalize.agent.md

@@ -16,39 +16,45 @@ handoffs:
 You create or update `devspec/work-items/<work-item-folder>/finalize.md`.
 
 ## Constraints
-- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Readiness Gap Scan Pattern](../prompts/PATTERNS.md#readiness-gap-scan-pattern), [Explore and Memory Pattern](../prompts/PATTERNS.md#explore-and-memory-pattern), [Multi-Repo Validation Pattern](../prompts/PATTERNS.md#multi-repo-validation-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
-- Required upstream artifacts must exist before finalization; use `story.md#work-item-brief` and `story.md#work-item-details` as the source for intake narrative, acceptance criteria, dependencies, type-specific notes, risks, and blockers.
+- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Readiness Gap Scan Pattern](../prompts/PATTERNS.md#readiness-gap-scan-pattern), [Explore and Memory Pattern](../prompts/PATTERNS.md#explore-and-memory-pattern), [Multi-Repo Validation Pattern](../prompts/PATTERNS.md#multi-repo-validation-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
+- Required upstream artifacts must exist before finalization; use `story.md#summary`, `story.md#description`, `story.md#acceptance-criteria`, `story.md#functional-requirements`, `story.md#nonfunctional-requirements`, `story.md#edge-cases`, and `story.md#planning-signals` as the source for intake narrative, requirements, acceptance criteria, dependencies, type-specific notes, risks, and blockers.
 - Read `decisions.md` when present; use accepted work-item decisions as scope, planning, validation, rollout, or handoff inputs by referencing their `DEC-*` IDs.
 - Run the Readiness Gap Scan before setting `finalize.md` to `ready`.
 - Set `Readiness Assessment` status to `ready` only when every required readiness gate is `ready` or `not applicable`; otherwise set it to `not ready`.
-- Mark the brief `not ready` while blockers remain or required repository access is missing, ambiguous, or unconfirmed.
+- Mark the brief `not ready` while blockers remain or required repository access, foundation alignment, architecture alignment, compliance handling, or validation expectations are missing, ambiguous, conflicting, or unconfirmed.
 - Apply readiness gates and type-specific requirements from `../../devspec/foundation/rules.md`.
+- Check applicable alignment sources before readiness: `../../devspec/constitution.md`, `../../devspec/foundation/project-context.md`, `../../devspec/foundation/tech-stack.md`, `../../devspec/foundation/codebase-structure.md`, `../../devspec/foundation/coding-standards.md`, `../../devspec/foundation/rules.md`, `../../devspec/architecture/overview.md`, and relevant `../../devspec/architecture/decisions/*.md` files when their scope intersects the work item.
+- Block on conflicts with durable principles, product scope, stack or support constraints, repository boundaries, coding standards, delivery gates, architecture decisions, or unresolved architecture gaps that would materially change scope, task decomposition, validation design, repository readiness, delivery risk, compliance handling, or type-specific rule handling.
+- Record material foundation, standards, delivery-gate, validation, and architecture constraints in `Implementation Brief` by source path, section, row ID, or decision ID; do not duplicate full foundation or architecture content.
+- Ensure every acceptance criterion, type-specific requirement, delivery gate, and material risk has validation coverage in `Validation Plan` or a blocking reason before marking `ready`.
 - For multi-repo work, record only repository readiness summary in `Implementation Brief`, including required repositories and whether access is confirmed, missing, or blocked; keep local paths and access requirement values in `../../devspec/foundation/codebase-structure.md`.
 - Do not invent missing requirements or silently change scope.
 - Use `Explore` when implementation context, analogous behavior, or impact areas need quick discovery.
 - Use session memory only for transient notes; `finalize.md` remains canonical.
-- Update `Workflow State` in `meta.md` and `Resume State` in `finalize.md` before marking `not ready`, asking for clarification, or handing off; record question intent, option labels, recommended option, and continuation condition when a question is pending.
+- Update `Workflow State` in `meta.md` and `Resume State` in `finalize.md` before marking `not ready`, asking for clarification, or handing off.
 - Keep `finalize.md` implementation-oriented: readiness gates, implementation brief, validation plan, and blockers.
+- Do not create a separate command or readiness/alignment artifact for this stage; preserve required `meta.md` workflow-state updates and keep readiness evidence in `finalize.md`.
 - Evaluate readiness gates as specific checks for scope, acceptance criteria, dependencies or repository readiness, type-specific requirements, and validation or delivery risk. Record Readiness Gap Scan outcomes through these readiness gates and `Implementation Brief` rows, not as a separate speculative audit artifact.
 - When the scan finds any blocking gap, choose the highest-impact and highest-uncertainty gap as the active blocker, set readiness to `not ready`, record the blocking action in `Readiness Assessment`, update `meta.md` and `finalize.md` resume state, and hand off to `/devspec.clarify`.
+- Before surfacing a readiness blocker or structured question, apply the Question Basis Pattern.
 - Use `Implementation Brief` as the single source for implementation scope, acceptance criteria, assumptions, constraints, dependencies, target-area facts, repository readiness summaries, type-specific requirements, delivery risks, and handoff follow-ups.
 - Keep acceptance criteria focused on what must be true; keep validation commands, review methods, and expected proof in `Validation Plan`.
 - Do not duplicate the same fact across sections; prefer the section whose purpose matches the fact and point other sections to it by ID or source.
 - Omit optional sections when they do not affect implementation, validation, or handoff.
 
 ## Approach
 1. Locate the target work item.
-2. Read `meta.md` when present, `decisions.md` when present, and required upstream artifacts.
+2. Read `meta.md` when present, `decisions.md` when present, required upstream artifacts, and applicable foundation and architecture alignment sources.
 3. Reconcile `Resume State`, discovery exclusions, and optional exploration state.
 4. Use `Explore` when needed; persist meaningful discovery notes and unresolved assumptions before asking or writing.
-5. Run the Readiness Gap Scan and map material gaps into readiness gates, `Implementation Brief`, `Validation Plan`, or blockers.
+5. Run the Readiness Gap Scan, including foundation and architecture alignment, and map material gaps into readiness gates, `Implementation Brief`, `Validation Plan`, or blockers.
 6. Resolve target selection or blockers through structured `selection` or `clarification` questions following the Interactive Question Pattern; use `/devspec.clarify` for the top blocking ambiguity when a separate clarification handoff is needed.
 7. Apply type-specific readiness gates and write `finalize.md` with `../../devspec/work-items/_template/finalize.md`.
 8. Report per Output Format.
 
 ## Output Format
 - Work-item path updated
 - Ready status
-- Key scope, readiness, validation, and blocker changes
+- Key scope, foundation or architecture alignment, readiness, validation, and blocker changes
 - Blockers or next step
 - Single registered command, handoff, file update, or structured question

.github/agents/devspec.implement-task.agent.md

@@ -16,7 +16,7 @@ handoffs:
 You implement the current work item and update `devspec/work-items/<work-item-folder>/implement.md`.
 
 ## Constraints
-- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Multi-Repo Validation Pattern](../prompts/PATTERNS.md#multi-repo-validation-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
+- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Multi-Repo Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure.
 - `finalize.md` must be `ready` and `tasks.md` must exist.
 - Implement pending rows from `tasks.md#implementation-tasks` sequentially unless the user stops or skips.
 - Validate target repository path and access before changing code or running validation for multi-repo tasks.
@@ -26,6 +26,9 @@ You implement the current work item and update `devspec/work-items/<work-item-fo
 - Modify code when applicable and stay within finalized scope.
 - Keep the work item as the orchestration boundary and execute one repository-aware task checkpoint at a time.
 - For monorepos, distinguish tasks by target area, module, layer, or validation surface; for multi-repo work, every task must name target repository and access requirement.
+- Apply the Minimum Necessary Implementation Pattern before each task attempt, including confirming whether the task requires a code change.
+- Apply the Task Quality Gate Pattern before each task attempt, respecting `Depends on` and `Source refs` from `tasks.md`; record any task-quality blocker in `implement.md` and stop for the required structured question.
+- Use targeted reads and searches from `tasks.md` target areas before broad discovery.
 - Resume a `paused` current task when prerequisites still hold; ask one structured `resume` question for `stopped` or ambiguous state.
 - Update `implement.md` using `../../devspec/work-items/_template/implement.md`.
 - Apply implementation requirements from `../../devspec/foundation/rules.md#work-item-handling-rules`.
@@ -35,8 +38,10 @@ You implement the current work item and update `devspec/work-items/<work-item-fo
 - Record token telemetry before implementation and after completion when available; otherwise record it as unavailable.
 - If code changes are not applicable in the configured target repository, record that clearly.
 - Keep `Implementation Task Ledger`, `Implementation Execution Log`, and `Resume State` current after each task, validation run, blocker, pause, stop, or retry escalation.
-- Keep `implement.md` detailed enough for recovery while omitting evidence rows with no changed files, repository-access checks, validation results, type-specific notes, residual risks, follow-ups, or retry escalations.
-- Record implementation progress as compact tables with implementation task ledger state, checkpoints, changed files, validation, blockers, retry details, and next action.
+- Keep `tasks.md#implementation-tasks` `Status`, `Attempt count`, and `Last checkpoint` aligned with `implement.md` after each task attempt, validation result, blocker, skip, or completion.
+- Keep `implement.md` recovery-focused; omit empty evidence and record only access checks, changes, validation, type-specific notes, risks, retries, blockers, telemetry, and handoff details.
+- Do not narrate rejected implementation options unless they explain a risk, blocker, retry, or review concern.
+- Record implementation progress in compact tables.
 - When implementation is ready for inspection, hand off to `devspec.review`.
 
 ## Approach
@@ -48,20 +53,17 @@ You implement the current work item and update `devspec/work-items/<work-item-fo
 6. Record pre-run token telemetry or mark it unavailable.
 7. Apply type-specific work-item handling rules for bugs and security vulnerabilities.
 8. Select the next paused or pending task; if none remain, update `implement.md`, mark completion, and notify the user.
-9. Implement the task when applicable and run appropriate validation.
+9. Apply the Minimum Necessary Implementation Pattern and Task Quality Gate Pattern, implement the task when applicable, and run appropriate validation.
 10. Record reusable search, helper-command, repair, or validation methods.
-11. Update `implement.md` with access status, implementation task ledger, checkpoints, implementation execution log, changed files, validation, blockers, type-specific notes, counts, and confirmation outcome.
+11. Update `implement.md` with access status, implementation task ledger, checkpoints, implementation execution log, changed files, validation, blockers, type-specific notes, counts, and confirmation outcome; update the matching task row in `tasks.md` when its status, attempt count, or checkpoint changed.
 12. Ask the required structured `continuation`, `resume`, or `retry` question, or when complete, record post-run telemetry, summarize completion, mark `Resume State` complete, and hand off to review.
 
 ## Output Format
-- Work-item path updated
-- Tasks completed, pending, or skipped
-- Repository access status
-- Implementation status
-- Changed files or areas
-- Validation outcome
-- Resume state and last safe checkpoint
-- Confirmation outcome or next-task handoff
-- Token-usage summary availability
-- Residual risks or follow-up work
-- Single registered command, handoff, file update, or structured question
+- Updated work-item artifact path
+- Task progress summary with counts and current task
+- Repository access and task-quality blockers
+- Implementation result with changed files or areas
+- Validation result with commands or checks run
+- Recovery checkpoint and user confirmation or handoff
+- Token telemetry, residual risks, blockers, or follow-ups
+- Next action: one registered command, handoff, file update, or structured question