Skip to content

Issue Tracking

GitHub Issues are Nuzo's execution tracker.

Docs and roadmap explain direction. Issues should describe work that can be assigned, reviewed, and closed.

Labels

Use three label groups together when possible:

  • area:* for ownership;
  • type:* for the kind of work;
  • priority:* for sequencing.

Current area labels:

  • area:core
  • area:cli
  • area:mcp
  • area:codex
  • area:claude-code
  • area:docs
  • area:release

Current type labels:

  • type:feature
  • type:bug
  • type:docs
  • type:architecture

Current priority labels:

  • priority:p0
  • priority:p1
  • priority:p2

Use status:blocked only when an issue has a concrete external blocker.

Milestones

Active release milestones follow docs/operations/release-goals.md:

  • 0.3.1 Trust Baseline
  • 0.4.0 Audit And Provenance
  • 0.5.0 Recall Quality
  • 0.6.0 Capture Intelligence
  • 0.7.0 Optional Semantics
  • 0.8.0 Host Reliability
  • 0.9.0 Contract Stabilization
  • 1.0.0 Stable Release

Historical milestones may remain closed for traceability. Milestones should stay small enough to guide execution and must not become permanent categories.

Create focused issues for the current or immediately upcoming milestone. Keep distant release direction in the release-goals document until evidence is strong enough to define assignable work. This avoids turning speculative implementation details into stale issue backlogs.

Issue Quality

Good issues include:

  • a clear goal;
  • relevant package or docs boundaries;
  • concrete tasks;
  • acceptance criteria;
  • links to docs or prior decisions when useful.

Avoid issues that only say "improve docs" or "make plugin better". Convert them into a specific deliverable before starting work.

Use the Architecture Proposal form for substantial, cross-boundary, or hard-to-reverse changes. Follow spec-driven-workflow.md to separate the proposal, public contract, durable decisions, and executable task status.

Periodic Issue Hunting

Run issue hunting after meaningful changes and before larger next-step work.

Check:

  • docs and README for stale product claims;
  • roadmap status against implemented packages;
  • CLI, MCP, and plugin commands shown in docs against real commands;
  • generated artifacts or runtime memory accidentally staged;
  • GitHub Issues for duplicates or completed work that should be closed;
  • GitHub Pages and release workflow status when public docs change;
  • repository controls such as branch protection, Dependabot alerts and security updates, CodeQL, secret scanning, and push protection;
  • tests and validation gaps around recently changed behavior.

Small safe fixes can be handled immediately. Larger work should become a focused GitHub Issue with labels, milestone, concrete tasks, and acceptance criteria.

Security

Issues must not include:

  • runtime memory files;
  • real memory exports;
  • API tokens;
  • credentials;
  • cookies;
  • private keys;
  • private user data.

Use fake data for examples and reproduction steps.

Pull Request Governance

Routine changes must use a branch and pull request. Branch protection applies to administrators and requires the Node.js 22, Node.js 24, documentation, and CodeQL checks to pass against the current main.

Nuzo does not require approving reviews while the repository has one primary maintainer. The pull request still provides a reviewable diff, check history, discussion surface, and atomic squash-merge boundary.

Same-repository topic branches are short-lived. GitHub automatically deletes a head branch after its pull request is merged; protected branches and branches with open pull requests are unaffected. Nuzo does not keep permanent version-number branches. A release or hotfix branch is justified only when an active, documented workflow requires it, and should be deleted when that work is integrated.

The scheduled Repository Governance workflow verifies the observable policy: main remains the default and no same-repository branch from a merged pull request remains. GitHub intentionally hides the administrative delete_branch_on_merge field from workflow and unauthenticated tokens, so a maintainer also verifies the setting during periodic issue hunting with:

gh api repos/fabionfsc/nuzo-memory --jq .delete_branch_on_merge

If branch protection must be relaxed for repository recovery, open or update a focused Issue with the reason, restore protection immediately after recovery, and attach validation evidence for the resulting main.