Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Issue Tracking & Triage Standards

Issues, specs and tickets live in GitHub Issues for ngxccc/alolite. Use the gh CLI for every operation.

Source of truth for ticket state. Local markdown notes under re-notes/ are evidence, never tickets.

1. CLI Command Conventions

OperationCommandNotes
Create issuegh issue create --title "..." --body "..."Use a heredoc for structured bodies.
View issuegh issue view <number> --commentsDescription, labels and discussion.
List issuesgh issue list --state open --label "<label>"Filter by lifecycle, type or area.
Commentgh issue comment <number> --body "..."Post updates, link PRs, attach evidence.
Apply labelsgh issue edit <number> --add-label "<label>"Update type/area/priority.
Close issuegh issue close <number> --comment "..."Always close with a resolution summary.

2. Label Taxonomy

A. Lifecycle (exceptions only)

State lives in the issue itself (open/closed), PR links (Fixes #<id>) and GitHub Projects. Do not maintain in-progress / needs-review labels.

LabelMeaning
status:blockedWaiting on an external dependency, credentials, upstream protocol evidence or another issue.
wontfixClosed as out of scope, superseded or rejected.

B. Type (Conventional Commits alignment)

type:feat, type:fix, type:refactor, type:perf, type:test, type:docs, type:chore, type:ci, type:style, type:task.

C. Area (domain scopes)

LabelScope
area:coreCore engine, background runtime, common utilities and services (crates/alolite-core/src/{core,common,services}).
area:protocolZalo network protocol, wire codecs, cryptographic handshakes, and message sync (crates/alolite-core/src/protocol/).
area:authQR/password login, session.json, zpw_sek / zpw_enk, and trusted device pairing.
area:netHTTP endpoints, candidate failover, WebSocket framing, ParamCipher v2, and signkey.
area:chatThreads, message identity, reactions, recall, forwarding, and history sync.
area:storeSQLite schema, migrations, queries, and local offline cache (crates/alolite-core/src/storage/).
area:mcpMCP JSON-RPC protocol over stdio/HTTP, local REST daemon, and autoreply rules (crates/alolite-core/src/mcp/).
area:uiNative Tauri v2 host and React desktop frontend (apps/desktop/, crates/alolite-desktop/).
area:cliCommand-line interface, terminal QR login, and desktop launcher (crates/alolite-cli/).
area:packagingLinux distribution packages (.deb, .rpm, .AppImage, .tar.gz) under packaging/.
area:assetsDesktop icons, SVG branding assets, and reaction graphics under assets/ and .github/assets/.
area:docsDocumentation book (docs/), ADRs, standards, README, and user guides.
area:ciGitHub Actions workflows and CI/CD automation (.github/workflows/).
area:harnessAGENTS.md, AI agent tooling, .omp/, helper scripts, and Makefile.

D. Priority

LabelMeaning
priority:p0Critical: data loss, credential exposure, complete outage.
priority:p1Blocks the next release milestone.
priority:p2Normal (default).

3. Triage Label Vocabulary

Canonical vocabulary consumed by /triage. Do not introduce synonyms.

RoleRepo representation
needs-triageDefault: open issue with no type:* / area:* label.
needs-infostatus:blocked + a comment naming the missing evidence.
ready-for-agenttype:* + area:* set, acceptance criteria present, no open blocker.
ready-for-humanpriority:p0 / priority:p1, or requires protocol evidence / physical device testing.
wontfixwontfix label + closing comment.

4. Native Sub-Issues Protocol

  1. Create the child with canonical body format:

    gh issue create --title "task(<area>): <summary>" --label "type:task,area:<area>" --body "$(cat <<'EOF'
    ### Outcome
    <One-sentence observable behaviour or state when complete.>
    
    ### Context
    <Child task context or sub-problem specification.>
    
    ### Acceptance Criteria
    - [ ] <Specific verifiable condition>
    
    ### Non-goals
    - <Explicit boundaries>
    EOF
    )"
    
  2. Link it to the parent:

    CHILD_ID=$(gh api repos/ngxccc/alolite/issues/<child_number> --jq .id)
    gh api --method POST repos/ngxccc/alolite/issues/<parent_number>/sub_issues -F sub_issue_id=$CHILD_ID
    
  3. Query children:

    gh api repos/ngxccc/alolite/issues/<parent_number>/sub_issues \
      --jq '.[] | "#\(.number): \(.title)"'
    

5. Wayfinding

  • Map ticket: one issue labeled wayfinder:map, holding decisions and the fog tracker.
  • Child tickets: labeled wayfinder:<research|prototype|grilling|task> and linked as native sub-issues.
  • Blocking: use native issue dependencies; a ticket is unblocked when every blocker is closed.

6. Ticket Quality Bar

A ticket is actionable only when it adheres to the canonical issue body structure (enforced across .github/ISSUE_TEMPLATE/ and CLI usage):

A. Canonical Body Structure

### Outcome

<One-sentence observable behaviour or state when complete, not file inventory.>

### Context

<Current limitation, background, discrepancy, or reproduction steps.>

### Acceptance Criteria

- [ ] <Specific verifiable condition>
- [ ] <Verification command or test pass criteria>

### Non-goals

- <Explicit non-goal to prevent scope creep.>

B. Checklist Requirements

  • One-sentence outcome (observable behaviour, not file inventory).
  • Reproduction or acceptance checklist (- [ ]).
  • Affected area label (area:*) and type label (type:*).
  • Evidence for protocol changes (capture path, re-notes/ reference, server error_code).
  • Explicit non-goals when scope is easy to over-read.

C. CLI Heredoc Creation Template

gh issue create \
  --title "<type>(<area>): <summary>" \
  --label "type:<type>,area:<area>" \
  --body "$(cat <<'EOF'
### Outcome
...

### Context
...

### Acceptance Criteria
- [ ] ...

### Non-goals
- ...
EOF
)"

7. Security Rule

Never paste session.json, zpw_sek, zpw_enk, cookies, IMEI or raw captures containing them into an issue. Redact to zpw_sek=<redacted> and attach only sanitized excerpts.