majordomus plan

Model milníků a úkolů — ověřte ho, přečtěte ho a proveďte jím jeden úkol.

mění stav
plan
--json

Deset podpříkazů jen pro čtení a čtyři, které zapisují po jednom lifecycle markeru. Třída jmenuje příkaz jako celek, což je vše, co může říct jedno pole; sekce syntaxe odděluje READ od WRITE. Pracuje nad projektovým modelem, ne nad záznamem aktivní úlohy, takže nepotřebuje úlohu.

Syntaxe

majordomus plan <subcommand> [options]

Životní cyklus

Nastavit
Začít
Pracovat
Ověřit
Uzavřít
Prozkoumat

Další příkazy v této fázi:start, session.

Čte

.ai/repo/project/

Zapisuje

.ai/repo/project/

Návratové kódy

Jen kódy, které tento příkaz může vrátit. Úplný kontrakt je na indexu příkazů.

0 ok
2 použití
10 kontrakt nesplněn
12 chybějící artefakt
13 interní chyba
15 odmítnuto

Model, validovaný a čtený

plan čte kanonický projektový model a posouvá jím jeden úkol. Stav se nikdy neukládá — odvozuje se z toho, co bylo o úkolu zaznamenáno, a ze stavu jeho závislostí. Každý scénář zde se provádí proti skutečnému binárnímu souboru pomocí test/cases/34_command_fixtures.sh.

Model, který se zparsuje a drží pohromadě

závislost splněna: ne
model přítomen: ano

Pro tento repozitář platí

# Installed, with a canonical project model carrying one milestone and two issues, the
# second depending on the first. The helpers come from test/lib.sh, which the fixture
# runner has already sourced.
. "$FIXTURE_SETUP/installed.sh"
pj_init
pj_milestone M000
pj_issue I0001 M000
pj_issue I0002 M000 I0001

Spustit

$ majordomus plan validate

Výstup obsahuje

milestone
issue
0 selhání

ukončení 0

Schémata, odkazy, graf závislostí a konzistence stavů v jednom průchodu. Klíč, který nikdo nečte, je zde chyba ze stejného důvodu jako v politice: nečtené pole je přesvědčení, které nic nekontroluje.

Repozitář bez projektového modelu

závislost splněna: ne
model přítomen: ne

Pro tento repozitář platí

# A repository with Majordomus installed and projections generated, and one commit of work.
"$MJ" init >/dev/null
"$MJ" update >/dev/null
mkdir -p lib docs
echo a > lib/a
echo d > docs/d
git add . && git commit -qm base

Spustit

$ majordomus plan validate

Výstup obsahuje

žádný kanonický projektový model

ukončení 12

Kód 12 je MISSING_ARTIFACT: repozitář není nastaven pro model projektu, což je jiná skutečnost než model, který se nepodaří parsovat.

Co lze zahájit hned

závislost splněna: ne
model přítomen: ano

Pro tento repozitář platí

# Installed, with a canonical project model carrying one milestone and two issues, the
# second depending on the first. The helpers come from test/lib.sh, which the fixture
# runner has already sourced.
. "$FIXTURE_SETUP/installed.sh"
pj_init
pj_milestone M000
pj_issue I0001 M000
pj_issue I0002 M000 I0001

Spustit

$ majordomus plan ready

Výstup obsahuje

I0001

ukončení 0

I0002 závisí na I0001, takže připraven je jen I0001. Připravenost se odvozuje z grafu, a ne štítkuje na úkolu, takže se nemůže rozcházet se závislostmi.

Co čeká a na co

závislost splněna: ne
model přítomen: ano

Pro tento repozitář platí

# Installed, with a canonical project model carrying one milestone and two issues, the
# second depending on the first. The helpers come from test/lib.sh, which the fixture
# runner has already sourced.
. "$FIXTURE_SETUP/installed.sh"
pj_init
pj_milestone M000
pj_issue I0001 M000
pj_issue I0002 M000 I0001

Spustit

$ majordomus plan blocked

Výstup obsahuje

I0002

ukončení 0

Doplněk připravenosti, který jmenuje závislost, a ne jen skutečnost, že je blokováno — užitečná otázka je, co dokončit první.

Podpříkaz, který nemá

závislost splněna: ne
model přítomen: ano

Pro tento repozitář platí

# Installed, with a canonical project model carrying one milestone and two issues, the
# second depending on the first. The helpers come from test/lib.sh, which the fixture
# runner has already sourced.
. "$FIXTURE_SETUP/installed.sh"
pj_init
pj_milestone M000
pj_issue I0001 M000
pj_issue I0002 M000 I0001

Spustit

$ majordomus plan explain

Výstup obsahuje

plan

ukončení 2

Kód ukončení 2 je USAGE. Překlepnutý podpříkaz se odmítne, místo aby se bral jako výchozí, takže skript se nemůže mlčky zeptat na jinou otázku, než zamýšlel.

Reference

Číst kanonický projektový model a provést jeden úkol jeho životním cyklem. Milník je spustitelná specifikace výsledku; úkol je ohraničený kontrakt provedení; graf závislostí mezi úkoly rozhoduje, co se smí provést dál. Sémantiku viz docs/PLANNING.md.

Čte: .ai/repo/project/project.yaml, .ai/repo/project/milestones/*.yaml, .ai/repo/project/issues/*.yaml, share/allow/{project,milestone,issue}.txt. Zapisuje: jedno pole životního cyklu v jednom souboru úkolu a jednu událost knihy — jen start, verify, evidence a done. Každý další podpříkaz nezapisuje nic.

majordomus plan validate         schemas, references, the DAG, status consistency
majordomus plan status           milestone progress and the next executable issue
majordomus plan list             one line per issue: id, status, wave, milestone, title
majordomus plan show <id>        the full record of one milestone or issue
majordomus plan ready            issues whose dependencies are all satisfied
majordomus plan blocked          issues waiting on a dependency, and on which one
majordomus plan waves            topological execution waves, derived from the graph
majordomus plan graph            the dependency DAG as Mermaid
majordomus plan next             the one issue a worker should take now
majordomus plan body <id>        the provider-neutral projection body for one record
majordomus plan start <id>       record that execution began
majordomus plan verify <id>      record that implementation is complete, evidence pending
majordomus plan evidence <id>    attach one piece of evidence
majordomus plan done <id>        record completion

Volby: --json u čtecích podpříkazů, které povrch spotřebovává; --milestone <id> k omezení list, ready, blocked, waves a graph; --covers, --type, --command, --result a --artifact u evidence.

Behaviour:

Žádný stav se nikde neukládá. BLOCKED, READY, ACTIVE, VERIFY, DONE a CANCELLED se odvozují z toho, co úkol zaznamenává o sobě, a ze stavu jeho závislostí, pomocí lib/project.awk. Zápis pole status: je neznámý klíč.
validate hlásí neznámé klíče, neznámé a vlastní závislosti, duplicitní id, cykly, úkoly provedené před svou závislostí a úkoly bez kritérií přijetí. Skončí s 10, když je jakýkoli nález selhání, a s 0, když zbývají jen varování.
start odmítne (15) úkol, který není READY, a uvede, na co čeká. verify odmítne úkol, který není ACTIVE.
evidence odmítne (15) token, který úkol nedeklaruje, a odmítne (2) bez --command nebo --artifact: vyprávění není důkaz. Připojí se k souboru úkolu s commitem a časovým razítkem.
done odmítá (10), dokud je jakýkoli deklarovaný token důkazu nepokrytý, a odmítá (15), dokud závislost není DONE. Každý zapisující podpříkaz vypíše další připravený úkol po přepočtu grafu.
Končí kódem 12, když pojmenovaný záznam neexistuje nebo když repozitář nemá vůbec žádný kanonický projektový model — model je dobrovolný a doctor ho přeskočí, místo aby tam, kde chybí, selhal.

Stejný model promítá na GitHub scripts/github-sync a na web scripts/generate-site-data. Žádný z nich neodvozuje stav znovu; oba čtou tento engine.

Důkazy

Každý případ níže běží v CI na Linuxu i macOS. Web se odmítne sestavit, pokud veřejný příkaz nemá behaviorální případ, negativní případ nebo ukázku.

Chování

Způsoby selhání

Implementace

Ukázka

fixtures/plan.json

Testuje test/cases/34_command_fixtures.sh, který přehraje fixture a porovná ji s tím, co příkaz vypíše.

Záruky, které tento příkaz nese

zaručeno Úkol nelze dokončit, dokud chybí povinný důkaz