@flydocs/cli 0.6.0-alpha.1 → 0.6.0-alpha.10

package/template/.claude/skills/flydocs-cloud/scripts/validate_setup.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Validate workspace setup via the FlyDocs Relay API.
+
+Read-only validation that checks provider, team, status mapping, label config,
+and user identity. Writes result to .flydocs/validation-cache.json and sets
+setupComplete: true in config when all required checks pass.
+"""
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+
+# Required checks — failure blocks setup completion
+REQUIRED_CHECKS = {
+    "provider": {
+        "test": lambda cfg: cfg.get("provider", {}).get("connected") is True,
+        "message": "No provider connected — configure in FlyDocs dashboard",
+    },
+    "team": {
+        "test": lambda cfg: bool(cfg.get("team", {}).get("id")),
+        "message": "No team selected — configure in FlyDocs dashboard",
+    },
+    "statusMapping": {
+        "test": lambda cfg: cfg.get("statusMapping", {}).get("configured") is True,
+        "message": "Status mapping not configured — configure in FlyDocs dashboard",
+    },
+    "labelConfig": {
+        "test": lambda cfg: cfg.get("labelConfig", {}).get("configured") is True,
+        "message": "Label config not configured — configure in FlyDocs dashboard",
+    },
+}
+
+# Optional checks — warn but don't block
+OPTIONAL_CHECKS = {
+    "userIdentity": {
+        "test": lambda cfg: cfg.get("userIdentity", {}).get("linked") is True,
+        "message": (
+            "Provider identity not linked — run: "
+            "python3 .claude/skills/flydocs-cloud/scripts/set_identity.py <provider> <id>"
+        ),
+    },
+    "repos": {
+        "test": lambda cfg: (cfg.get("repos", {}).get("count", 0) or 0) > 0,
+        "message": "No repos linked — link a repo in FlyDocs dashboard settings",
+    },
+}
+
+
+def main() -> None:
+    client = get_client()
+
+    # Fetch workspace config from relay
+    config_response = client.get("/auth/config")
+
+    # Run checks
+    checks: dict[str, bool] = {}
+    valid: list[str] = []
+    missing: list[dict[str, str]] = []
+    warnings: list[dict[str, str]] = []
+
+    for name, check in REQUIRED_CHECKS.items():
+        passed = check["test"](config_response)
+        checks[name] = passed
+        if passed:
+            valid.append(name)
+        else:
+            missing.append({"check": name, "action": check["message"]})
+
+    for name, check in OPTIONAL_CHECKS.items():
+        passed = check["test"](config_response)
+        checks[name] = passed
+        if passed:
+            valid.append(name)
+        else:
+            warnings.append({"check": name, "action": check["message"]})
+
+    all_required_pass = len(missing) == 0
+
+    # Build workspace info from response
+    workspace = config_response.get("workspace", {})
+    provider_type = config_response.get("provider", {}).get("type", "unknown")
+
+    # Write validation cache
+    cache = {
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "valid": all_required_pass,
+        "workspace": {
+            "id": workspace.get("id", ""),
+            "name": workspace.get("name", ""),
+        },
+        "provider": provider_type,
+        "checks": checks,
+        "missing": [m["check"] for m in missing],
+        "warnings": [w["check"] for w in warnings],
+    }
+
+    cache_path = client.project_root / ".flydocs" / "validation-cache.json"
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(cache_path, "w") as f:
+        json.dump(cache, f, indent=2)
+        f.write("\n")
+
+    # If all required checks pass, set setupComplete in config
+    if all_required_pass:
+        config_path = client.config_path
+        if config_path.exists():
+            with open(config_path, "r") as f:
+                local_config = json.load(f)
+        else:
+            local_config = {}
+
+        local_config["setupComplete"] = True
+        with open(config_path, "w") as f:
+            json.dump(local_config, f, indent=2)
+            f.write("\n")
+
+    # Output structured report
+    report: dict = {
+        "valid": all_required_pass,
+        "checks": checks,
+        "passed": valid,
+    }
+    if missing:
+        report["missing"] = missing
+    if warnings:
+        report["warnings"] = warnings
+    if all_required_pass:
+        report["setupComplete"] = True
+
+    output_json(report)
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/skills/flydocs-local/SKILL.md

@@ -37,7 +37,7 @@ All scripts: `python3 .claude/skills/flydocs-local/scripts/<script>`
 | `comment.py`            | `<ref> ["<comment>"] \| stdin`                                                                                                                        | `{success, commentId}`                                                                   |
 | `list_issues.py`        | `[--status STATUS] [--active] [--assignee STR] [--mine] [--limit N]`                                                                                  | `[{id, identifier, title, status, assignee, priority}]`                                  |
 | `get_issue.py`          | `<ref>`                                                                                                                                               | `{id, identifier, title, description, status, assignee, priority, estimate, comments[]}` |
-| `assign.py`             | `<ref> <assignee>`                                                                                                                                    | `{success, issue, assignee}`                                                             |
+| `assign.py`             | `<ref> <assignee> \| --unassign`                                                                                                                      | `{success, issue, assignee}`                                                             |
 | `update_description.py` | `<ref> --text "..." \| --file PATH \| stdin`                                                                                                          | `{success, issue}`                                                                       |
 | `status_summary.py`     | `[--project ID]`                                                                                                                                      | `{statuses: {STATUS: count}, total}`                                                     |
 

package/template/.claude/skills/flydocs-local/scripts/assign.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Assign an issue to a person."""
+"""Assign or unassign an issue."""
 
 import json
 import sys
@@ -8,12 +8,21 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).parent))
 from flydocs_api import assign_issue
 
-if len(sys.argv) < 3:
-    print("Usage: assign.py <ref> <assignee>", file=sys.stderr)
+if len(sys.argv) < 2:
+    print("Usage: assign.py <ref> <assignee> | assign.py <ref> --unassign", file=sys.stderr)
     sys.exit(1)
 
+ref = sys.argv[1]
+unassign = "--unassign" in sys.argv
+
+if not unassign and len(sys.argv) < 3:
+    print("Usage: assign.py <ref> <assignee> | assign.py <ref> --unassign", file=sys.stderr)
+    sys.exit(1)
+
+assignee = None if unassign else sys.argv[2]
+
 try:
-    result = assign_issue(sys.argv[1], sys.argv[2])
+    result = assign_issue(ref, assignee)
     print(json.dumps(result))
 except Exception as e:
     print(str(e), file=sys.stderr)

package/template/.claude/skills/flydocs-local/scripts/flydocs_api.py

@@ -236,10 +236,13 @@ def get_issue(ref: str) -> dict:
     }
 
 
-def assign_issue(ref: str, assignee: str) -> dict:
+def assign_issue(ref: str, assignee: str | None) -> dict:
     filepath = _find_issue(ref)
     data = _parse_issue(filepath)
-    data["assignee"] = assignee
+    if assignee is None:
+        data.pop("assignee", None)
+    else:
+        data["assignee"] = assignee
     data["updated"] = datetime.now().strftime("%Y-%m-%d")
 
     fm = {k: v for k, v in data.items() if k not in ("description", "comments", "_path")}

package/template/.claude/skills/flydocs-workflow/SKILL.md

@@ -17,6 +17,10 @@ triggers:
   - transition
   - status
   - issue
+  - knowledge
+  - document
+  - PR
+  - pull request
 ---
 
 # FlyDocs Workflow
@@ -35,32 +39,33 @@ Capture → Refine → Activate → Implement → Review → Validate → Close
 
 ## Stage Index
 
-| Stage | File | Intent | Agent |
-|-------|------|--------|-------|
-| Capture | stages/capture.md | Create issue from input | PM |
-| Refine | stages/refine.md | Triage + spec completion | PM |
-| Activate | stages/activate.md | Assign + start work | PM |
-| Implement | stages/implement.md | Build + test + simplify | Implementation |
-| Review | stages/review.md | Code quality validation | Review |
-| Validate | stages/validate.md | User acceptance testing | QE |
-| Close | stages/close.md | Archive completed work | PM |
+| Stage     | File                | Intent                   | Agent          |
+| --------- | ------------------- | ------------------------ | -------------- |
+| Capture   | stages/capture.md   | Create issue from input  | PM             |
+| Refine    | stages/refine.md    | Triage + spec completion | PM             |
+| Activate  | stages/activate.md  | Assign + start work      | PM             |
+| Implement | stages/implement.md | Build + test + simplify  | Implementation |
+| Review    | stages/review.md    | Code quality validation  | Review         |
+| Validate  | stages/validate.md  | User acceptance testing  | QE             |
+| Close     | stages/close.md     | Archive completed work   | PM             |
 
 ## Session
 
-| Action | File |
-|--------|------|
-| Start session | session.md |
-| Wrap session | session.md |
+| Action          | File       |
+| --------------- | ---------- |
+| Start session   | session.md |
+| Wrap session    | session.md |
 | Stale detection | session.md |
 
 ## Reference
 
-| Topic | File |
-|-------|------|
-| Comment templates | reference/comment-templates.md |
-| Status transitions | reference/status-workflow.md |
+| Topic                | File                            |
+| -------------------- | ------------------------------- |
+| Comment templates    | reference/comment-templates.md  |
+| Status transitions   | reference/status-workflow.md    |
 | Priority & estimates | reference/priority-estimates.md |
-| Golden rules | reference/golden-rules.md |
+| PR & git workflow    | reference/pr-workflow.md        |
+| Golden rules         | reference/golden-rules.md       |
 
 ## Templates
 

package/template/.claude/skills/flydocs-workflow/reference/comment-templates.md

@@ -56,6 +56,7 @@ Canonical templates for all workflow transitions. Copy exactly, fill bracketed v
 **Files:** [count] modified
 **Testing:** [How it was verified]
 **Criteria:** [X]/[Y] complete
+**PR:** [link or "direct commit"]
 ```
 
 ## Code Review Passed

package/template/.claude/skills/flydocs-workflow/reference/pr-workflow.md

@@ -0,0 +1,105 @@
+# PR & Git Workflow
+
+## Branch Naming
+
+Format: `<type>/<ref>-<slug>`
+
+| Type      | When                                   |
+| --------- | -------------------------------------- |
+| `feature` | New functionality                      |
+| `fix`     | Bug fixes                              |
+| `chore`   | Maintenance, refactoring, dependencies |
+| `docs`    | Documentation only                     |
+
+Examples:
+
+- `feature/FLY-255-knowledge-capture`
+- `fix/FLY-301-login-timeout`
+- `chore/FLY-290-upgrade-deps`
+
+Keep the slug short (2-4 words, kebab-case). Include the issue reference.
+
+## Commit Messages
+
+Format: `<type>: <description> (<ref>)`
+
+- Lead with what changed, not how
+- Use imperative mood ("Add", not "Added")
+- Keep the first line under 72 characters
+- Add a body for non-obvious changes
+
+Examples:
+
+```
+feat: Add knowledge doc templates and /knowledge command (FLY-255)
+fix: Handle null milestone in create_issue response (FLY-301)
+chore: Remove deprecated auth middleware (FLY-290)
+```
+
+## When to Create a PR
+
+**Create a PR when:**
+
+- Changes affect shared code (not just local config or docs)
+- Multiple files changed across different concerns
+- Changes need review before merging
+- Working on a branch (not committing directly to main)
+
+**Commit directly when:**
+
+- Single-file documentation updates
+- Config changes for local development
+- Trivial fixes (typos, formatting)
+- The user explicitly requests direct commit
+
+When in doubt, create a PR. It's easier to merge a PR than to revert a direct commit.
+
+## PR Description Template
+
+```markdown
+## Summary
+
+[1-3 bullet points describing what changed and why]
+
+Closes [ISSUE-REF]
+
+## Changes
+
+- [Key change 1]
+- [Key change 2]
+- [Key change 3]
+
+## Test Plan
+
+- [ ] [How to verify change 1]
+- [ ] [How to verify change 2]
+
+## Notes
+
+[Anything reviewers should know — tradeoffs, follow-up work, decisions made]
+```
+
+## PR Workflow in Practice
+
+### During Implement Stage
+
+After self-review (step 7 in `implement.md`), before handing off to review:
+
+1. Create branch: `git checkout -b <type>/<ref>-<slug>`
+2. Stage and commit changes with a descriptive message
+3. Push branch: `git push -u origin <branch>`
+4. Create PR with the template above, linking the issue
+5. Include the PR link in the "Ready for Review" comment
+
+### During Review Stage
+
+The reviewer should:
+
+- Review the PR diff (not just local git diff)
+- Leave comments on the PR for specific code feedback
+- Reference the PR in review comments on the issue
+
+### After Review
+
+- **Approved**: Merge the PR, then transition issue to Testing
+- **Changes needed**: Push fixes to the same branch, re-request review

package/template/.claude/skills/flydocs-workflow/reference/priority-estimates.md

@@ -2,27 +2,49 @@
 
 ## Priority Values
 
-| Value | Name | Use When |
-|-------|------|----------|
-| 0 | None | Not yet triaged |
-| 1 | Urgent | Drop everything, fix now |
-| 2 | High | Next up, unblocks others |
-| 3 | Medium | Normal priority (default) |
-| 4 | Low | Nice to have |
+| Value | Name   | Use When                  |
+| ----- | ------ | ------------------------- |
+| 0     | None   | Not yet triaged           |
+| 1     | Urgent | Drop everything, fix now  |
+| 2     | High   | Next up, unblocks others  |
+| 3     | Medium | Normal priority (default) |
+| 4     | Low    | Nice to have              |
 
 ## Estimate Values (Complexity)
 
-| Value | Name | Rough Effort |
-|-------|------|--------------|
-| 1 | XS | < 1 hour |
-| 2 | S | 1-4 hours |
-| 3 | M | Half day to full day |
-| 4 | L | 2-3 days |
-| 5 | XL | Week+ |
+| Value | Name | Rough Effort         |
+| ----- | ---- | -------------------- |
+| 1     | XS   | < 1 hour             |
+| 2     | S    | 1-4 hours            |
+| 3     | M    | Half day to full day |
+| 4     | L    | 2-3 days             |
+| 5     | XL   | Week+                |
 
 ## Guidance
 
 - Set priority during Refine or Activate stages
 - Set estimate during Refine stage (before Ready)
 - If estimate is missing at Activate, set it before transitioning
-- XL estimates often indicate the issue should be broken into smaller pieces
+- Estimate values may vary by provider — the relay translates per provider configuration
+
+## Decomposition
+
+When an estimate is large (XL / 5+ or provider equivalent), prompt for decomposition:
+
+1. **Identify natural boundaries** — separate concerns, independent deliverables, sequential phases
+2. **Create child issues** — each should be independently estimable at M or smaller
+3. **Link parent to children** — use `link.py` with type `blocks` (parent blocks children conceptually)
+4. **Re-estimate parent** — set to 0 or remove estimate, since children carry the work
+5. **Move parent to a tracking role** — it becomes the "epic" or summary issue
+
+**Split pattern:**
+
+```
+Original: FLY-100 "Build auth system" (XL)
+  → FLY-101 "Add login endpoint" (S)
+  → FLY-102 "Add session management" (M)
+  → FLY-103 "Add role-based access control" (M)
+  → FLY-104 "Add password reset flow" (S)
+```
+
+Don't force decomposition on every large issue — some are genuinely large and atomic. Use judgment. The prompt is: "This is estimated as XL. Can it be broken into smaller, independently deliverable pieces?"

package/template/.claude/skills/flydocs-workflow/session.md

@@ -52,6 +52,7 @@ When a conversation begins or the user returns after a gap:
 
 7. **Surface other product issues briefly** — If there are issues in the product scope
    but outside the active project, mention the count with a one-line summary:
+
    ```
    Also in [Product Name]: [N] issues across other projects (use --all to see)
    ```
@@ -69,10 +70,16 @@ automatically via the config cascade.
 When the user indicates they're done for the session:
 
 1. **Gather session data** — What was completed, what's in progress, what's blocked.
-2. **Compose summary** using the template below.
-3. **Determine health status** — See health table.
-4. **Post project update** — `project_update.py` with health and summary body.
-5. **Record session in context graph** — Call `graph_session.py` with summary and issues worked on:
+2. **Knowledge capture check** — Review the session's work for uncaptured knowledge:
+   - Were any architectural decisions made?
+   - Were any non-obvious behaviors or workarounds discovered?
+   - Were any patterns established that future work should follow?
+   - Did debugging reveal something worth documenting?
+     If yes, prompt the user: "This session involved [specific discovery]. Should we capture it in a knowledge doc before wrapping?" Use `/knowledge` if they agree.
+3. **Compose summary** using the template below.
+4. **Determine health status** — See health table.
+5. **Post project update** — `project_update.py` with health and summary body.
+6. **Record session in context graph** — Call `graph_session.py` with summary and issues worked on:
    ```
    python3 .claude/skills/flydocs-context-graph/scripts/graph_session.py \
        --summary "Brief summary of session outcomes" \
@@ -80,8 +87,8 @@ When the user indicates they're done for the session:
        [--decision NNN]
    ```
    This creates a session node for cross-session continuity. Skip silently if the script is not installed.
-6. **Verify** — Confirm the project update was posted (update ID returned).
-7. **Ask about uncommitted changes** — If git shows uncommitted work, offer to commit.
+7. **Verify** — Confirm the project update was posted (update ID returned).
+8. **Ask about uncommitted changes** — If git shows uncommitted work, offer to commit.
 
 Do not just summarize in chat. Actually post the update. Do not skip if the user seems in a hurry.
 
@@ -104,15 +111,16 @@ Do not just summarize in chat. Actually post the update. Do not skip if the user
 
 ### Health Status
 
-| Status | When to Use |
-|--------|-------------|
-| onTrack | Progress made, no blockers |
-| atRisk | Minor delays, attention needed |
+| Status   | When to Use                     |
+| -------- | ------------------------------- |
+| onTrack  | Progress made, no blockers      |
+| atRisk   | Minor delays, attention needed  |
 | offTrack | Major blockers, behind schedule |
 
 ### Wrap Detection Phrases
 
 Offer session wrap when the user says:
+
 - "I'm done for today" / "wrapping up" / "that's it for now"
 - "save progress" / "end of day" / "stopping here"
 
@@ -120,9 +128,9 @@ Offer session wrap when the user says:
 
 Proactively surface issues that may be stuck:
 
-| State | Threshold | Action |
-|-------|-----------|--------|
-| Implementing | > 7 days without activity | Warn |
-| Review | > 3 days without activity | Warn |
-| Testing/QA | > 3 days without activity | Warn |
-| Blocked | Any | Always surface |
+| State        | Threshold                 | Action         |
+| ------------ | ------------------------- | -------------- |
+| Implementing | > 7 days without activity | Warn           |
+| Review       | > 3 days without activity | Warn           |
+| Testing/QA   | > 3 days without activity | Warn           |
+| Blocked      | Any                       | Always surface |

package/template/.claude/skills/flydocs-workflow/stages/capture.md

@@ -21,9 +21,14 @@ When the user has enough context to describe the issue:
    - **Why** — User story or business value
    - **How** — Technical notes or approach (if known)
    - **Done when** — Acceptance criteria as checkboxes
-4. **Create issue** — `create_issue.py` with title, type, description, priority, and estimate (if known).
-5. **Add comment** — Use the Capture template from `reference/comment-templates.md`.
-6. **Verify** — Confirm issue identifier returned.
+4. **Apply labels** — Include appropriate labels from config:
+   - **Category label**: Automatic from issue type (feature, bug, chore, idea) via `issueLabels.category` in config
+   - **Repo label**: If multi-repo workspace, apply the repo label from `issueLabels.repo` in config
+   - **Product labels**: Applied automatically by the mechanism scripts from `workspace.product.labelIds`
+   - **Ad-hoc labels**: Only if explicitly relevant (e.g., "accessibility", "performance")
+5. **Create issue** — `create_issue.py` with title, type, description, priority, estimate (if known), and labels.
+6. **Add comment** — Use the Capture template from `reference/comment-templates.md`.
+7. **Verify** — Confirm issue identifier returned.
 
 ### Quick Capture
 

package/template/.claude/skills/flydocs-workflow/stages/close.md

@@ -11,12 +11,13 @@ Archive verified and completed work.
 ## Steps
 
 1. **Verify QE approval** — Check issue comments for a "QE Approved" comment. If not found, do not close — direct to Validate stage first.
-2. **Determine terminal state:**
+2. **Final knowledge check** — If the issue involved significant implementation, verify `knowledge/INDEX.md` reflects any decisions or discoveries. This is informational — don't block close, but prompt the user if notable knowledge appears uncaptured.
+3. **Determine terminal state:**
    - **Done** — Work completed and verified (normal path)
    - **Archived** — Deferring to a later date (not cancelled, may return)
    - **Canceled** — Not pursuing (won't be done)
-3. **Transition** — `transition.py` with the appropriate Close comment from `reference/comment-templates.md`.
-4. **Verify** — Confirm terminal state reached.
+4. **Transition** — `transition.py` with the appropriate Close comment from `reference/comment-templates.md`.
+5. **Verify** — Confirm terminal state reached.
 
 ## Gates
 

package/template/.claude/skills/flydocs-workflow/stages/implement.md

@@ -20,6 +20,7 @@ Build, test, simplify, and hand off to code review.
 ### 2. Show Implementation Checklist
 
 Present to the user:
+
 - Issue ID and title
 - All acceptance criteria
 - Estimate
@@ -46,7 +47,18 @@ Rationale: [Why this choice over alternatives]
 
 For significant architectural decisions, also create a record in `knowledge/decisions/`.
 
-### 5. TODO to Issue
+### 5. Knowledge Capture Check
+
+Before moving to self-review, check if any of these occurred during implementation:
+
+- **Architectural decision** — framework choice, pattern established, approach rejected
+- **Discovery** — API quirk, debugging technique, non-obvious behavior
+- **Workaround** — limitation found, temporary fix applied
+- **Pattern** — reusable approach that future work should follow
+
+If yes, prompt the user: "Should we capture this in a knowledge doc?" Use `/knowledge` to create the doc, or note it for session wrap if the user wants to defer.
+
+### 6. TODO to Issue
 
 When adding a TODO comment in code:
 
@@ -56,7 +68,7 @@ When adding a TODO comment in code:
 
 Every TODO must have a tracked issue. No orphaned TODOs.
 
-### 6. Simplify
+### 7. Simplify
 
 After implementation is functionally complete, review modified files for:
 
@@ -67,7 +79,7 @@ After implementation is functionally complete, review modified files for:
 
 Apply standards from installed community skills and `preferences.md`. Preserve all functionality.
 
-### 7. Self-Review
+### 8. Self-Review
 
 Before handing off:
 
@@ -77,7 +89,18 @@ Before handing off:
 - [ ] No obvious security issues
 - [ ] No orphaned TODOs
 
-### 8. Hand Off to Review
+### 9. Create PR (if applicable)
+
+See `reference/pr-workflow.md` for full conventions. If changes warrant a PR:
+
+1. Create branch: `git checkout -b <type>/<ref>-<slug>`
+2. Stage and commit with a descriptive message: `<type>: <description> (<ref>)`
+3. Push: `git push -u origin <branch>`
+4. Create PR linking the issue, using the PR description template
+
+If the user requested a direct commit or changes are trivial, skip the PR and commit directly.
+
+### 10. Hand Off to Review
 
 Transition to Review via `transition.py` with the "Ready for Review" comment from `reference/comment-templates.md`. Include:
 
@@ -85,6 +108,7 @@ Transition to Review via `transition.py` with the "Ready for Review" comment fro
 - File count
 - How it was tested
 - Criteria completion count
+- PR link (if PR was created)
 
 ## Checkbox Protocol
 

package/template/.claude/skills/flydocs-workflow/stages/refine.md

@@ -32,14 +32,30 @@ For backlog items that need fleshing out before activation:
 5. **Add technical notes** — Implementation guidance, dependencies, affected areas.
 6. **Set estimate and priority** — If not already set. See `reference/priority-estimates.md`.
 7. **Check dependencies** — Blocked by other issues? Related work?
-8. **Update description** — `update_description.py` with refined content.
-9. **Transition to Ready** — `transition.py` with Refine comment from `reference/comment-templates.md`.
+8. **Assign milestone** — If the issue fits a current or upcoming milestone, assign it via `--milestone` on `update_issue.py`. If no milestone is appropriate, leave unassigned but note it.
+9. **Update description** — `update_description.py` with refined content.
+10. **Quality gate check** — Verify all criteria pass before transitioning:
+
+| Gate                | Check                                            | Required |
+| ------------------- | ------------------------------------------------ | -------- |
+| Description         | Context section filled, not just a title         | Yes      |
+| Acceptance criteria | Specific, testable, written as checkboxes        | Yes      |
+| Estimate            | Set (see `reference/priority-estimates.md`)      | Yes      |
+| Priority            | Set (P1-P4)                                      | Yes      |
+| Labels              | Category label applied, repo label if multi-repo | Yes      |
+| Dependencies        | Identified and documented, or explicitly "none"  | Yes      |
+| Milestone           | Assigned if applicable                           | No       |
+
+If any required gate fails, address it before transitioning.
+
+11. **Transition to Ready** — `transition.py` with Refine comment from `reference/comment-templates.md`.
 
 ## Gates
 
+- All quality gate checks pass (see table above)
 - Acceptance criteria defined (specific, testable, as checkboxes)
-- Estimate set (1-5)
-- Priority set (1-4)
+- Estimate set
+- Priority set (P1-P4)
 
 ## Outputs