querysource 5.1.2__tar.gz → 5.1.4__tar.gz

querysource-5.1.4/.agents/skills/sdd-brainstorm/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: sdd-brainstorm
+description: Explore a feature idea through structured Q&A, codebase research, options, tradeoffs, and a committed SDD brainstorm document.
+---
+
+# SDD Brainstorm
+
+## Full procedure and Codex adaptations
+
+Before executing, read the [full sdd-brainstorm procedure](../../../.claude/commands/sdd-brainstorm.md)
+and the [Codex adaptation contract](../../../docs/sdd/CODEX.md#codex-adaptation-contract).
+Follow the full procedure for details omitted from this summary. The adaptation
+contract and the Codex-specific instructions below override Claude runtime syntax
+and legacy shell examples; retain all workflow gates and evidence requirements.
+
+Use this skill when the user asks to run `sdd-brainstorm`, create a brainstorm,
+or explore a feature idea before writing a formal spec.
+
+Codex invocation: `$sdd-brainstorm <feature-slug> -- <notes>`.
+
+## Purpose
+
+Produce `sdd/proposals/<feature-slug>.brainstorm.md` from an idea. This is an
+exploration artifact, not implementation code and not a spec.
+
+Pipeline:
+
+```text
+$sdd-brainstorm -> review -> $sdd-spec -> $sdd-task -> $sdd-start
+```
+
+## Guardrails
+
+- Do not write implementation code.
+- Use `sdd/templates/brainstorm.md`.
+- Preserve the YAML frontmatter from the template.
+- Always resolve and record `type` and `base_branch`.
+- Always include concrete existing-code references with file paths and line
+  numbers.
+- Verify packages in project dependency files before recommending them.
+- Commit only the brainstorm file unless the user explicitly asks otherwise.
+- Fill frontmatter `projects` (parts of the codebase, vocabulary `KNOWN_PROJECTS` in
+  `scripts/sdd/sdd_meta.py`; unknown values warn) and `tags` (2–6 kebab-case keywords) — FEAT-576.
+
+## Flow Type
+
+Ask these first unless the user already supplied explicit values:
+
+1. Is this `feature` or `hotfix`?
+2. For `feature`, which base branch? Default: `dev`. Use `staging` during a
+   release freeze or a parent feature branch for sub-features. For `hotfix`,
+   base is always `main`.
+
+Defaults when unanswered: `type: feature`, `base_branch: dev`.
+
+Validation:
+
+- `type: hotfix` requires `base_branch: main`.
+- `type: feature` with `base_branch: main` is invalid. Stop and explain that
+  features land on `dev`, `staging`, or a non-main parent feature branch.
+
+## Workflow
+
+1. Parse input:
+   - feature slug in kebab-case
+   - notes after `--`
+   - `intake: <staging-dir>` in the notes (FEAT-577): read its `intake.json` /
+     `synthesis.json`, treat the intake facts as answered, seed Round 1 from
+     the synthesis unknowns.
+   - optional `--type feature|hotfix`
+   - optional `--base-branch <branch>`
+2. Run at least two Q&A rounds:
+   - Round 1: intent, users, expected behavior, integration points, success
+     criteria.
+   - Round 2: gaps, edge cases, failure modes, tradeoffs, assumptions.
+3. Research the codebase:
+   - Run `wikitoolkit query "<focused question>"` before source scans.
+   - Inspect at least one relevant wiki page with `wikitoolkit page <id>` or
+     related entries when available.
+   - Use `rg` for source search.
+   - Read the source files before citing classes, functions, methods, imports,
+     or paths.
+4. Build the Code Context section:
+   - User-provided snippets, preserved verbatim.
+   - Verified imports and signatures with paths and line numbers.
+   - Things searched for that do not exist.
+5. Generate at least three solution options:
+   - name
+   - what it does
+   - pros and cons
+   - effort: Low, Medium, or High
+   - libraries/tools and existing code to reuse
+   - at least one less obvious approach
+6. Recommend one option and explain the tradeoff.
+7. Fill the remaining template sections:
+   - Problem Statement
+   - Constraints & Requirements
+   - Feature Description
+   - Capabilities
+   - Impact & Integration
+   - Open Questions
+   - Parallelism Assessment
+8. Save `sdd/proposals/<feature-slug>.brainstorm.md`.
+9. Commit only that brainstorm file:
+   - preserve unrelated staging; stop before committing if it is outside this run's scope
+   - stage only the brainstorm
+   - verify `git diff --cached --name-only`
+   - commit `sdd: add brainstorm for <feature-slug>`
+
+## Output
+
+Report:
+
+```text
+Brainstorm saved and committed: sdd/proposals/<feature-slug>.brainstorm.md
+Recommended: Option <letter> - <name>
+Effort: <Low|Medium|High>
+Worktree isolation: <per-spec|mixed>
+Open questions: <count>
+Next: $sdd-spec <feature-slug>
+```
+
+## References
+
+- `sdd/templates/brainstorm.md`
+- `sdd/templates/spec.md`
+- `sdd/WORKFLOW.md`

querysource-5.1.4/.agents/skills/sdd-codereview/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: sdd-codereview
+description: Code review a completed SDD task against acceptance criteria, code quality, security, and adversarial cross-checks.
+---
+
+# SDD Code Review
+
+## Full procedure and Codex adaptations
+
+Before executing, read the [full sdd-codereview procedure](../../../.claude/commands/sdd-codereview.md)
+and the [Codex adaptation contract](../../../docs/sdd/CODEX.md#codex-adaptation-contract).
+Follow the full procedure for details omitted from this summary. The adaptation
+contract and the Codex-specific instructions below override Claude runtime syntax
+and legacy shell examples; retain all workflow gates and evidence requirements.
+
+Use this skill when the user asks to review a completed SDD task, run `sdd-codereview`, or perform an adversarial code review on completed task artifacts.
+
+**Mandatory Deferred Findings Table**: Every CONFIRMED 🔴/🟡 finding not fixed in-review MUST be
+attempted with `wikitoolkit ledger open` and listed in the report's Deferred findings table. The
+ledger intentionally resolves to the main checkout. If a sandbox makes it read-only, do not request
+broader filesystem access or create a worktree-local ledger; list the full finding with
+`(NOT filed: shared ledger is read-only)`. Reviews with unfiled confirmed findings and an empty
+Deferred table are invalid.
+
+## Purpose
+
+Reads the task file from `sdd/tasks/completed/`, loads all referenced source files and the parent spec, applies code review criteria (Correctness, Code Quality, Performance, Security, Documentation, Testing), and produces a structured review report.
+
+## Guardrails
+
+- Reads strictly completed tasks from `sdd/tasks/completed/`.
+- Verify the chain of thought and code anchors: check actual files, classes, methods, and line ranges.
+- Treat reviewer second-opinions as advisory: confirm, reject, or escalate each finding.
+- Never report an unverifiable claim as a finding.
+
+## Workflow
+
+## Durable review boundary (FEAT-584)
+Before feature review, settle owned attempts and supervised validations and close execution.
+Unknown activity is a blocker, never evidence of an idle worktree. Persist the checkpoint,
+record actual supported compaction outcome once per checkpoint/context, revalidate and start
+a fresh reviewer. Unsupported contexts continue from checkpoint with an explicit reason.
+Keep review criteria, adversarial checks, full lint, integration validation and ledger gates.
+Changes after checkpoint require new hashes/evidence and invalidate old review coverage.
+For sdd-done, preserve existing verification stamping, approval and push/merge policy;
+do not run task closure again on base_branch and do not clean worktrees with unknown activity.
+
+1. Resolve task:
+   - Accept full path, `TASK-NNN`, or slug.
+   - Match against `sdd/tasks/completed/TASK-*.md`.
+2. Load context:
+   - Read the task markdown file.
+   - Read the referenced spec in `sdd/specs/`.
+   - Read every file in the task's "Files to Create/Modify" section.
+   - Read the Acceptance Criteria and Completion Note.
+3. Review criteria:
+   - **Correctness & Logic**: Acceptance criteria satisfaction, edge cases, error paths.
+   - **Code Quality**: DRY, SOLID, abstraction seams, framework patterns.
+   - **Performance**: N+1 queries, async blocking calls, algorithmic efficiency.
+   - **Security**: Input validation, SQL/injection risks, credentials, auth.
+   - **Documentation**: Docstrings, type annotations, clarity.
+   - **Testing**: Test coverage against criteria, assertions, failure modes.
+4. Adversarial cross-check:
+   - Run external reviewer (`codex exec review`) or spawn a dedicated read-only subagent.
+   - Supply only neutral brief: requirements, diff/commit, question.
+   - Synthesize agreements and disagreements.
+5. Generate report:
+   - Summary, Critical, Major, Minor/Suggestions.
+   - **Deferred Findings table**: Every CONFIRMED 🔴/🟡 finding not fixed in-review MUST be attempted with `wikitoolkit ledger open` and listed in this table. If the shared ledger is read-only, retain the full finding with `(NOT filed: shared ledger is read-only)`.
+   - Acceptance Criteria check table.
+   - Adversarial cross-check disposition table.
+   - Positive highlights.
+6. Optional save:
+   - Save to `sdd/reviews/TASK-<NNN>-review.md` if requested.
+
+## References
+
+- `sdd/tasks/completed/`
+- `sdd/tasks/index/<feature>.json`
+- `sdd/WORKFLOW.md`

querysource-5.1.4/.agents/skills/sdd-done/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: sdd-done
+description: Verify a completed SDD feature worktree, check for merge blockers, snapshot ledger issues, stamp task verification, push or open the PR, optionally sync hotfixes down, and clean the worktree.
+---
+
+# SDD Done
+
+## Full procedure and Codex adaptations
+
+Before executing, read the [full sdd-done procedure](../../../.claude/commands/sdd-done.md)
+and the [Codex adaptation contract](../../../docs/sdd/CODEX.md#codex-adaptation-contract).
+Follow the full procedure for details omitted from this summary. The adaptation
+contract and the Codex-specific instructions below override Claude runtime syntax
+and legacy shell examples; retain all workflow gates and evidence requirements.
+
+Use this skill when the user asks to run `sdd-done`, close a feature, push an
+SDD worktree, open the feature PR, or clean up a completed SDD worktree.
+
+Codex invocation: `$sdd-done FEAT-NNN [--dry-run] [--merge] [--force] [--resolve-jira] [--sync-down]`.
+
+## Purpose
+
+Verify evidence in the feature worktree, check for merge blockers scoped to
+the current feature, snapshot ledger issues on base branch, stamp verification
+on the feature branch, push it, open or describe the PR, and remove the worktree
+when safe.
+
+## Guardrails
+
+- Run from the main repo on the spec's `base_branch`, or from the feature
+  worktree for the PR flow. `--merge` and `--sync-down` require the main repo.
+- Do not modify the spec.
+- Do not mark tasks done unless there is evidence in the worktree.
+- Always show a verification report before writing closeout state.
+- Hotfixes never merge directly to `main`.
+- Hotfixes never push directly to `main`.
+- For hotfixes, print a manual `gh pr create --base main` command instead of
+  creating or merging the PR automatically.
+- Use `--sync-down` only after the hotfix PR has merged to `main`.
+- Use `--sync-dev` only as a deprecated alias for `--sync-down`.
+- Merge gate checks apply only to `--merge` flag, not PR flow.
+- Ledger snapshots use throwaway worktrees and never modify active worktrees.
+- Hotfixes skip ledger snapshots.
+- Bounded retry for rejected pushes (max 3 attempts).
+
+## Workflow
+
+## Durable review boundary (FEAT-584)
+Before feature review, settle owned attempts and supervised validations and close execution.
+Unknown activity is a blocker, never evidence of an idle worktree. Persist the checkpoint,
+record actual supported compaction outcome once per checkpoint/context, revalidate and start
+a fresh reviewer. Unsupported contexts continue from checkpoint with an explicit reason.
+Keep review criteria, adversarial checks, full lint, integration validation and ledger gates.
+Changes after checkpoint require new hashes/evidence and invalidate old review coverage.
+For sdd-done, preserve existing verification stamping, approval and push/merge policy;
+do not run task closure again on base_branch and do not clean worktrees with unknown activity.
+
+1. Resolve feature:
+   - scan `sdd/tasks/index/*.json`, excluding `_orphans.json`
+   - match `feature_id`, numeric suffix, exact feature slug, or slug substring
+   - read `feature`, `feature_id`, `spec`, `type`, and `base_branch`
+2. Verify branch and location:
+   - resolve `MAIN_ROOT` from the absolute `git-common-dir` parent and
+     `WORKTREES_DIR` as `<MAIN_ROOT>/.claude/worktrees`
+   - compare absolute `git-dir` and `git-common-dir` to detect `IN_WORKTREE`
+   - in the main checkout, current branch must equal `base_branch`
+   - in a linked worktree, verify it is the selected feature's worktree;
+     refuse `--merge` and `--sync-down` (including `--sync-dev`)
+   - address primary-checkout paths through `MAIN_ROOT` / `WORKTREES_DIR`;
+     never change to the primary checkout to bypass worktree restrictions
+3. Locate worktree:
+   - prefer `git worktree list` match for `feat-<FEAT-ID>` or hotfix branch
+   - if missing, check remote/local branches and report next steps
+4. Gather evidence per task:
+   - commits matching task ID or slug in the worktree
+   - files listed in each task's "Files to Create / Modify" table exist in the
+     worktree
+   - do not rerun the whole test suite here; tests should have run during task
+     execution
+4.5. Full lint pass, once per feature:
+   - resolve changed Python files with `git diff --name-only --diff-filter=ACMR
+     origin/<base_branch>...HEAD -- '*.py'` from the feature worktree
+   - `--dry-run`: run only `ruff check` and report; never fix or commit
+   - otherwise run Ruff fixes and the configured Black formatter on those
+     files, inspect the diff, commit only those paths, then run full `ruff check`
+   - keep fixes behavior-neutral; when behavior changes, run the feature-tier
+     selector from `scripts.sdd.select_tests` with this feature's task files
+     before committing; refresh checkpoint/review evidence after any change
+   - report unfixable findings under Lint residual; residual `E9`, `F63`, `F7`
+     or `F82` errors block normal closeout and enter the issues/confirmation path
+5. Classify:
+   - `VERIFIED`: commit found and files exist
+   - `PARTIAL`: commit found but files are missing
+   - `NO EVIDENCE`: neither commits nor files support completion
+6. Present verification report:
+   - worktree
+   - branch
+   - commit count
+   - task count by status
+   - task-by-task evidence
+   - lint residuals and any missing review evidence
+7. Respect flags:
+   - `--dry-run`: stop after the report
+   - `--force`: allow forced closeout with partial/no evidence noted
+   - otherwise ask before closing if any task is not verified
+8. Stamp verification in the worktree branch (closing any task the lane left open):
+   - require staging to contain only this feature's owned changes before the
+     close step stages its moves; never reset unrelated staging
+   - verified is not closed: for each task being closed whose file is still in
+     `sdd/tasks/active/` or whose index status is not `done`/`done-with-issues`
+     (lanes such as `/sdd-fix` commit code without closing), run
+     `scripts/sdd/close_task.sh <TASK-ID> <feature-slug> <verification>` inside
+     the worktree — never on `base_branch` (FEAT-414), then set its status to
+     `done-with-issues` when verification is `partial`/`forced`; leave tasks
+     the lane already closed untouched, and skip (with a warning) any id not in
+     the index
+   - set each task `verification` to `verified`, `partial`, or `forced` in
+     `sdd/tasks/index/<feature>.json` inside the worktree
+   - set feature `completed_at` only when all tasks are done
+   - run `scripts/sdd/heal_orphans.sh <feature-slug>` inside the worktree
+     (PR flow and `--merge` alike)
+   - stage only the index and this feature's task files, verify cached names
+   - commit `sdd: close tasks for FEAT-NNN - <feature-slug>`
+9. Push feature branch:
+   - `git -C <worktree> push origin <branch>`
+10. Check merge blockers (feature flows only):
+    - If `--merge` flag is set and not a hotfix, run `wikitoolkit ledger blockers <FEAT-ID>`
+    - The command prints plain-text blocker lines (never JSON) and exits non-zero
+      exactly when blockers exist — gate on the **exit code**, not on parsing its output
+    - If blockers found and not `--force`, refuse merge and list the blockers
+      (`wikitoolkit ledger acknowledge <ISSUE-ID> --reason "..." --actor human:<name>`
+      is how a human resolves one)
+    - If `--force`, warn but proceed with merge
+
+11. Snapshot ledger issues (feature flows only):
+    - For features (not hotfixes), `git fetch origin <BASE_BRANCH>` then create a
+      throwaway detached worktree at `origin/<BASE_BRANCH>` (`git worktree add --detach`)
+    - Run `wikitoolkit ledger export` there; only when its output contains `(changed)`:
+      `git add sdd/ledger/issues.jsonl`, commit `sdd: ledger snapshot for <FEAT-ID>`,
+      and `git push origin HEAD:<BASE_BRANCH>`
+    - On a rejected push, fetch and create a fresh throwaway worktree at the
+      updated remote base, re-export, commit and retry — up to 3 attempts,
+      then warn and continue without failing `$sdd-done`
+    - Remove only clean, owned, idle throwaway worktrees without force; report
+      any retained worktree requiring recovery instead of deleting its changes
+    - Skip the snapshot entirely for hotfixes
+
+12. Integrate:
+    - If `base_branch == main`, refuse automatic merge or PR creation. Print
+      the manual hotfix PR command:
+      `gh pr create --base main --head <branch> --title "<title>" --body "<verification summary>"`.
+    - If feature and no `--merge`, run `gh pr create --base <base_branch> --head <branch>`.
+    - If `gh` is missing or not authenticated, print the manual command.
+    - If feature and `--merge`, merge into `base_branch`, run
+      `scripts/sdd/heal_orphans.sh <feature-slug>`, commit any staged orphan
+      cleanup, and push `base_branch`.
+13. Hotfix sync-down:
+    - only with `--sync-down` or deprecated `--sync-dev`
+    - verify feature branch is ancestor of `origin/main`
+    - merge into `staging`, abort cleanly on conflict
+    - merge into `dev`, abort cleanly on conflict
+    - leave user on `main`
+14. Resolve Jira if requested:
+    - find Jira key in spec or proposal metadata
+    - prefer Jira MCP tools if available
+    - fallback to configured Jira environment variables
+    - transition to Done, Resolved, Ready for UAT, Complete, or Close
+    - report missing credentials or missing transitions without failing closeout
+15. Cleanup:
+    - remove the worktree only after successful push/PR or merge path
+    - if running inside it, leave the feature worktree for an allowed directory
+      before removing it; if host restrictions prevent this, report cleanup pending
+    - if uncommitted changes exist in the worktree, ask before force removal
+    - prune stale metadata if the worktree was already removed
+    - delete local feature branch only when safe and merged/pushed
+
+## Output
+
+Report:
+
+```text
+FEAT-NNN - <title>: <closed>/<total> tasks closed
+Branch pushed: <branch>
+PR opened: <url> or manual command printed
+Worktree removed: .claude/worktrees/<name>
+Jira: <key> -> Done, when requested and successful
+```
+
+## References
+
+- `sdd/tasks/index/<feature>.json`
+- `sdd/tasks/active/`
+- `sdd/tasks/completed/`
+- `scripts/sdd/sdd_meta.py`
+- `scripts/sdd/heal_orphans.sh`
+- `sdd/WORKFLOW.md`

querysource-5.1.4/.agents/skills/sdd-explain/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: sdd-explain
+description: Explain how a subsystem, component, or symbol works in the current project, grounded in the real codebase with architecture maps or deep traces.
+---
+
+# SDD Explain
+
+## Full procedure and Codex adaptations
+
+Before executing, read the [full sdd-explain procedure](../../../.claude/commands/sdd-explain.md)
+and the [Codex adaptation contract](../../../docs/sdd/CODEX.md#codex-adaptation-contract).
+Follow the full procedure for details omitted from this summary. The adaptation
+contract and the Codex-specific instructions below override Claude runtime syntax
+and legacy shell examples; retain all workflow gates and evidence requirements.
+
+Use this skill when the user asks to explain how a subsystem, component, or symbol works in the project, onboarding architecture explanations, or deep code traces.
+
+Invocation: `sdd-explain [--deep] <subsystem | component | symbol | question>`.
+
+## Purpose
+
+Provide code-grounded explanations of how the repository actually works right now. Produces Subsystem Maps (architecture/onboarding) by default, or Implementation Traces with `--deep`.
+
+## Guardrails
+
+- **Read before explaining**: Never describe an import path, class, method, registry, or decorator without locating and reading it first.
+- **Cite with grep anchors**: Reference symbols by name and file path, not brittle line numbers.
+- **State evidence**: Explicitly state which files and symbols were read.
+- **No unsolicited fixes/code**: This skill explains; it does not refactor or modify code.
+
+## Workflow
+
+1. Parse arguments:
+   - Check for `--deep` (or `-d`) flag for Implementation Trace mode.
+   - Extract target subsystem, component, or symbol.
+2. Locate code:
+   - Use `find_by_name`, `grep_search`, or `rg` to find real symbols and files.
+   - Read the source files.
+3. Subsystem Map Mode (default):
+   - Locate: package entry points and anchor symbols.
+   - What it is: single responsibility and system role.
+   - The cast: concrete ABCs, registries, mixins, managers.
+   - Data & control flow: end-to-end request lifecycle and boundaries.
+   - Conventions & invariants: architectural constraints and why they exist.
+   - Where to look next: key files and adjacent subsystems.
+4. Implementation Trace Mode (`--deep`):
+   - Target resolution: exact symbols and files resolved.
+   - Execution trace: call-by-call walk through async boundaries, decorators, dispatches.
+   - Contracts & types: Pydantic models, protocol signatures, validation rules.
+   - Edge cases & failure modes: error handling, fallbacks, timeouts.
+   - Coupling map: dependencies and callers.
+   - Gotchas: non-obvious behaviors and historical pitfalls.
+
+## References
+
+- `AGENTS.md`
+- `.agent/CONTEXT.md`
+- `sdd/WORKFLOW.md`

querysource-5.1.4/.agents/skills/sdd-fix/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: sdd-fix
+description: Drain the SDD work ledger — plan-fix, claim, route to the Fast or SDD lane, close by evidence, release the rest.
+---
+
+# SDD Fix
+
+Drain the SDD work ledger: plan a severity-ordered, file-grouped batch with
+`wikitoolkit ledger plan-fix --json`, claim the selected issues, route each group to the
+Fast lane (branch → PR) or the SDD lane (spec → tasks → worktree), close by evidence and
+release the rest. The twins never re-implement ordering, grouping or lane rules — the plan is
+the contract (`planner_version` is checked before use).
+
+**Read-only ledger**: the ledger resolves to the main checkout. If a sandbox makes it read-only,
+report `shared ledger is read-only`, do not request broader filesystem access, do not create a
+worktree-local ledger, and exit non-zero WITHOUT claiming anything.
+
+## Usage
+$sdd-fix                          # interactive picker, severity-ordered
+$sdd-fix <issue-id>               # non-interactive: that issue's whole group
+$sdd-fix --top N                  # non-interactive: first N groups
+$sdd-fix ... --kind K --severity S --lane fast|sdd   # --lane fast is REFUSED (exit 1) for critical or vulnerability groups
+
+## Steps
+1. **Plan** — `wikitoolkit ledger plan-fix --json` (pass `--kind/--severity/--lane` through). Parse stdout as a FixPlan.
+   Require a successful exit and `planner_version == "1"` before selecting or claiming anything.
+   Reject missing/unsupported versions or malformed output; never re-implement ordering, grouping or lane rules.
+   `--lane fast` is refused for critical or vulnerability groups; stop on that planner error.
+   The plan presents severity-ordered groups with metadata: group_id, max_severity, lane assignment with reason,
+   suggested_slug, and the list of issues/files per group. In interactive mode, render a table showing each group's
+   key attributes for selection.
+2. **Select** — picker, or deterministic resolution from the arguments (issue-id → its whole group; --top N → first N groups).
+   Require a positive N. An empty plan or an issue absent from it is a no-op with an explanation, never a guessed selection.
+3. **Claim** — one `wikitoolkit ledger claim <issue-id> --actor agent:sdd-fix` per issue in the group, immediately before
+   executing. The plan is a snapshot; the claim is authoritative: a non-zero exit DROPS that issue and continues. Never close an
+   issue merely because an earlier plan listed it. Skip groups with no successful claims; preserve the planned lane for remaining issues.
+4. **Prime** — `wikitoolkit ledger context <group.files…> --max-tokens 3000` (full repo-relative paths from the plan, never basenames).
+5. **Route** by `group.lane`:
+   - Before changing branches, require a clean checkout; never carry unrelated changes into a fix.
+     If execution cannot proceed, release successful claims in step 7.
+   - **Fast lane** (`lane == "fast"`): in the MAIN checkout (no worktree), `git fetch origin dev && git switch -c fix/<issue-short-id>-<suggested_slug> origin/dev`,
+     edit, run the affected package's tests, commit, `git push -u origin <branch>`, then `gh pr create --base dev --title … --body …`.
+     ALWAYS a PR — there is no direct-push path.
+   - **SDD lane** (`lane == "sdd"`): if any `group.parents[].open` is true, reuse that parent spec (`$sdd-task <spec> --from-issue …` per issue);
+     otherwise `python -m scripts.sdd.reserve_ids --kind feature --count 1 --base-branch dev --label <suggested_slug>`, author
+     `sdd/specs/<suggested_slug>.spec.md` from the group, `$sdd-task`, then
+     `python -m scripts.sdd.ensure_worktree --slug <suggested_slug> --feature-id FEAT-<NNN>`. `$sdd-done <FEAT-ID>` closes it out unchanged.
+     For a new spec, the slug comes from `suggested_slug`; never re-derive it. For a reused parent,
+     use that parent index's existing slug, feature_id, spec and base_branch when provisioning the worktree.
+     Task creation alone is not resolution: implement and validate the task in that worktree before step 6.
+6. **Close** — two keys, fail-closed: an issue closes only if the implementing agent asserts its id as resolved AND at least one of
+   its `files` appears in `git diff --name-only <base>...HEAD`. Then `wikitoolkit ledger close <issue-id> --reason "<what changed>"
+   --actor agent:sdd-fix --resolved-by commit:<sha>` (fast, the implementing commit on the pushed PR branch)
+   or `--resolved-by task:TASK-<NNN>` (SDD, a completed and validated task).
+   Capture `<base>` before implementation and check the diff from the implementing checkout.
+   Do not infer a merge or fabricate a merge SHA merely because a PR was opened.
+7. **Release** — every claimed issue that failed either key: `wikitoolkit ledger unclaim <issue-id> --reason "<why>" --actor agent:sdd-fix`.
+   Run release on every exit path, including test/push/PR failures or interrupted execution.
+   If unclaim itself fails, report the issue ID and reason for recovery; do not claim success.
+   Never leave an issue claimed silently; acknowledgement stays human-only and out of scope here.
+
+## Output
+Per group processed:
+- Lane used (Fast/SDD)
+- Branch/PR URL (Fast) or FEAT-ID + worktree path (SDD)
+- Issues closed with their resolved_by evidence
+- Issues released with reason

querysource-5.1.4/.agents/skills/sdd-fromjira/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: sdd-fromjira
+description: Bootstrap an SDD Brainstorm from a Jira ticket, conducting Q&A and codebase research.
+---
+
+# SDD From Jira
+
+## Full procedure and Codex adaptations
+
+Before executing, read the [full sdd-fromjira procedure](../../../.claude/commands/sdd-fromjira.md)
+and the [Codex adaptation contract](../../../docs/sdd/CODEX.md#codex-adaptation-contract).
+Follow the full procedure for details omitted from this summary. The adaptation
+contract and the Codex-specific instructions below override Claude runtime syntax
+and legacy shell examples; retain all workflow gates and evidence requirements.
+
+Use this skill when the user asks to bootstrap an SDD brainstorm from a Jira ticket, run `sdd-fromjira`, or convert a Jira issue into a feature proposal.
+
+Invocation: `sdd-fromjira <JIRA_KEY> [--complexity=fix|simple|standard|complex] [--skip-qa]`.
+
+## Purpose
+
+Fetch requirements from a Jira ticket, structure them, conduct targeted Q&A, research the codebase for reusable components, and produce a worker-ready brainstorm document at `sdd/proposals/<issue-key>-<slug>.brainstorm.md`.
+
+## Guardrails
+
+- Read-only on Jira: do not modify the Jira issue in this skill.
+- Always use the official template at `sdd/templates/brainstorm.md`.
+- Always commit the brainstorm file to git upon generation.
+- Never write implementation code in the brainstorm document.
+- Set flow type in frontmatter: `type: feature, base_branch: dev` (or `hotfix`/`main` for bug tickets).
+- Fill frontmatter `projects` (parts of the codebase, vocabulary `KNOWN_PROJECTS` in
+  `scripts/sdd/sdd_meta.py`; unknown values warn) and `tags` (2–6 kebab-case keywords) — FEAT-576.
+
+## Workflow
+
+1. Fetch Jira ticket:
+   - Use Jira MCP tool (`jira_get_issue`) if available, or curl fallback via
+     `JIRA_INSTANCE`, `JIRA_USERNAME`, and `JIRA_API_TOKEN` without logging secrets.
+   - Extract summary, description, acceptance criteria, components, labels, subtasks.
+2. Parse content:
+   - Convert description/ADF to plain text.
+   - Extract acceptance criteria and constraints.
+3. Classify complexity:
+   - `fix` (1 round Q&A), `simple` (2 rounds), `standard` (2-3 rounds), `complex` (3+ rounds).
+   - `--complexity` overrides classification; `--skip-qa` skips the interview
+     when the supplied Jira description is exhaustive.
+4. Present ticket context:
+   - Show summary, components, AC, and complexity assessment to user.
+5. Interactive Q&A:
+   - Target genuine gaps left open by Jira (not generic questions).
+6. Codebase research:
+   - Run `wikitoolkit query` before source scans.
+   - Read source files to build verified Code Context (signatures, imports, and what does NOT exist).
+7. Generate 3+ options:
+   - Map each option against Jira AC.
+   - Recommend one option with explicit tradeoff rationale.
+8. Save and commit:
+   - Save to `sdd/proposals/<issue-key>-<slug>.brainstorm.md`.
+   - Stage only the brainstorm file and commit: `sdd: add brainstorm from Jira <issue-key> — <slug>`.
+
+## References
+
+- `sdd/templates/brainstorm.md`
+- `sdd/WORKFLOW.md`

querysource-5.1.4/.agents/skills/sdd-insight/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: sdd-insight
+description: Analyze Claude Code transcripts and repo-level SDD Process Discipline from the sdd/ artifact tree using the local Insight engine.
+---
+
+# SDD Insight
+
+## Full procedure and Codex adaptations
+
+Before executing, read the [full sdd-insight procedure](../../../.claude/commands/sdd-insight.md)
+and the [Codex adaptation contract](../../../docs/sdd/CODEX.md#codex-adaptation-contract).
+Follow the full procedure for details omitted from this summary. The adaptation
+contract and the Codex-specific instructions below override Claude runtime syntax
+and legacy shell examples; retain all workflow gates and evidence requirements.
+
+Use this skill when the user asks to analyze AI fluency, review prompt collaboration patterns, or evaluate repo-level SDD Process Discipline adherence.
+
+Invocation: `$sdd-insight [TRANSCRIPT_PATH] [--no-open] [--sdd-dir PATH | --no-sdd]`.
+
+## Purpose
+
+Execute `scripts/sdd/insight.py` to produce a two-layer analytical report:
+1. Personal AI-fluency skill map (score, archetype, competencies, growth levers) from transcripts.
+2. Repo-level SDD Process Discipline panel (pipeline progression, decomposition quality, AC coverage, cycle closure, review rigor) computed deterministically from `sdd/`.
+
+## Guardrails
+
+- Transcripts and `sdd/` files are read strictly read-only.
+- Always run within the virtual environment (`source .venv/bin/activate`).
+- The engine reads Claude Code JSONL transcripts (default `~/.claude/projects`).
+  Native Codex session logs are not supported by this workflow; never present
+  Claude-derived personal scores as measurements of Codex sessions.
+- Use a fresh report directory under `artifacts/` so old analysis cannot leak
+  into a new run. Do not delete previous reports.
+
+## Workflow
+
+1. Parse the optional transcript path and supported flags into a shell argument
+   array `insight_args`. Preserve paths as single quoted arguments; never eval
+   user text. With no arguments, use `insight_args=()`.
+2. Run deterministic measurement from the repository root:
+   ```bash
+   source .venv/bin/activate
+   mkdir -p artifacts
+   insight_run_dir=$(mktemp -d artifacts/sdd-insight.XXXXXX)
+   python3 scripts/sdd/insight.py --evidence "$insight_run_dir/evidence.json" --sdd-dir sdd --no-open --quiet -o "$insight_run_dir/report.html" "${insight_args[@]}"
+   ```
+   Check the exit status and evidence/report files. If no compatible transcripts
+   are found, report that limitation and stop; do not invent scores or promise
+   a standalone SDD report that this engine did not produce.
+3. If the `sdd-insight` analysis workflow capability is available, give it the
+   absolute evidence path and `reference/sdd-insight/ai-fluency-framework.md`.
+   Save its JSON to this run's `analysis.json`, then render with matching evidence:
+   ```bash
+   python3 scripts/sdd/insight.py --analysis "$insight_run_dir/analysis.json" --analysis-evidence "$insight_run_dir/evidence.json" --sdd-dir sdd -o "$insight_run_dir/report.html" "${insight_args[@]}"
+   ```
+   Otherwise use the complete deterministic report. A fingerprint mismatch also
+   falls back to deterministic output; disclose which report was produced.
+4. Link the final HTML report and present its findings, identifying the transcript source:
+   - Personal score and archetype.
+   - Top growth lever.
+   - Repo SDD Process Discipline score and weakest dimension.
+
+## References
+
+- `scripts/sdd/insight.py`
+- `reference/sdd-insight/ai-fluency-framework.md`
+- `sdd/WORKFLOW.md`