Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Add a deterministic work-scope contract for review, merge follow-up, issues, research and code analysis

Open
  • Is something wrong?
#54 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 9 days

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
22/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
python
Domain
devtools

Research direction

Read the existing Work Instrument and Vitals contracts in related issues #34, #47, and #51–#52, then inspect the repository’s current observation and CLI/API entry points. Define a separate deterministic, model-free work-scope contract with five typed queues, evidence and invalidation rules, eligibility, bounded selection, and offline replay. Done means the acceptance fixtures and documented CLI/API cover the listed cases without changing the existing Vitals contracts.

Written by the indexing model from the issue text.

Description

Problem

On released v0.1.9, demand.json orders seven Vitals by attention level. It does not identify a pull/merge request, issue, research question or code slice that a developer can act on. Every consumer must rediscover those objects and reconstruct selection policy, often by rereading the entire repository.

The Work Instrument in #34/#47 measures activity; it is not a queue of next actions. Keep those contracts distinct.

Proposed consumer surface

Add a separately versioned, model-free work-scope projection (or an officially supported companion library if task selection belongs outside the observational core). Preserve the Vitals, devostasis.demand.v2, and the prohibition on aggregate health scores. Business priority and permission come from explicit consumer policy, never from a Vital band or a gauge.

Produce five typed queues:

  1. review: an independently reviewable change at a specific head, with outstanding review requirements.
  2. finish_merge: existing changes needing rework, failed-check repair, conflict resolution, discussion disposition or authorized merge-train admission. Separate blocked follow-up from actually merge-ready work.
  3. implement_issue: declared actionable issue criteria without equivalent completed or active implementation.
  4. research: a declared question, evidence contradiction or identified unknown with its specific decision, bounded inputs and expected output.
  5. analyze_code: named paths/symbols plus an observed trigger and verification objective.

Each item needs a stable identity independent of observation time; source object/criterion; repository identity; head/base or content revision; action kind; source priority and policy rationale; evidence references; paths/symbols/read budget; acceptance; implementation owner versus action executor; dependencies; eligibility and missing evidence. Bind the projection to immutable bundle/inventory digests, observation time, expiration and selection-policy version. Define invalidation for new commits, verdicts, claims and dependency changes.

The planner recommends actions. It must not assign claims, dispatch developers, mutate labels, close issues, resolve discussions, merge, or deploy. A consumer rechecks current authority, ownership and exact-head evidence immediately before execution. Unknown reviews/CI/ownership stay typed unknown, not "merge ready".

Use deterministic eligibility, then declared business priority, then continuation toward acceptance, followed by explicit action preferences and stable tie-breaks. Emit a bounded slice with continuation/overflow and excluded reasons; a top-N cut must not silently lose high-priority or older eligible work. A scoped empty queue and an incomplete inventory must be distinguishable.

Acceptance

  • Same admitted inputs, policy and clock produce byte-identical output; replay needs no API or model.
  • Fixture cases cover requested independent review; rework; stale review after head change; red/missing/manual checks; unresolved threads; conflicts; draft; merge train; foreign ownership; blocked dependency; already implemented issue; sibling criteria; explicit research gap; named analysis trigger.
  • Unknown or partially collected required evidence cannot admit a merge action; independently proven tasks can remain eligible with visible coverage limitations.
  • Missing input creates a bounded evidence-recovery item rather than invented implementation.
  • Changing a Vital's gauge cannot change business priority. A lower-priority merge-ready change does not overtake an eligible higher-priority issue.
  • Item IDs survive unrelated runs; updates replace the same actionable gap rather than duplicating it.
  • A documented CLI/API supports queue and role slices plus offline explain/replay.

Related: #34, #40, #47, #51, #52. This requests a consumer planning contract, not a replacement of the existing observation or Work Instrument contracts.

Dominant language
Python
Stars
4
Forks
1
Avg merge
5d 12h
Merged PRs (30d)
3

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from drevendev/Devostasis

All issues in drevendev/Devostasis

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.