Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/governance/workstreams.md
Original file line number Diff line number Diff line change
Expand Up @@ -233,6 +233,7 @@ state to its index: [`docs/adr/`](../adr/README.md), [`docs/pdr/`](../pdr/README
| D217 | **The platform tests hung while another project ran its end-to-end tests.** On a workstation where a project ran a long end-to-end run, 2026-11-14, the platform suite stopped at the same test, again and again: `test_evidence.py` starts a real run, which waits on the machine's end-to-end lock (`$XDG_RUNTIME_DIR/nstack-e2e.lock`, D84's one run at a time) — held, rightly, by the other project's run | **Done**: every test has a runtime folder of its own (`conftest.py`), so no test ever takes or waits on the machine's lock; the tests of the lock itself already set theirs. Seen red first: the file hung under a held lock, and passes in seconds under the same lock |
| D218 | **A review's failed run blocked the merge for good** (#394). On an attested project, 2026-11-14, a code owner approved before the record was complete — the usual moment —: « Test sheet and cycle », triggered by the review, failed (A2). The record completed by a notes push, which is no event; a later run of the same head passed, and the ruleset still refused the merge on the review's run, kept beside it. An agent cannot re-run a workflow: the person had to | **Done**: the job runs on the pull request's own events only. A review or a comment stays a verifier's hand (T2), read at the next run, which any edit of the description starts — an agent's included; T2's message and the verification playbook say so. Not chosen: skipping the job on a review, which leaves a required check « skipped », counted as passed; a separate job, since this one reads no approval. A pull request already blocked by a review's failed run is unblocked by a new push, whose head starts afresh — or, before taking this version, by a new review; never by an edit, nor by a re-run, which replays the old event's payload and fails again (seen on that project). The workflow's test seen red first |
| D219 | **A workflow red on the default branch went unseen** (#387). On a desktop project, 2026-11-07 to 13, the Windows packaging workflow failed on every run of the default branch — six runs — and was noticed by chance: it is no required check, so every pull request merged green beside it | **Done**: `nstack doctor` reads, workflow by workflow — a quiet one, filtered by `paths:` or scheduled, never drops out of a window busier ones fill — the last completed runs of the default branch's own events (push, schedule, dispatch: never a pull request's, a fork's included) with the token it already has (Actions: read). It says, as information (N2) that never changes its exit, each active workflow whose last three or more runs all failed — timed out and failed to start count — with the first failure's link; cancelled and skipped runs say nothing either way. Unreadable runs are said, with the permission to add. Market: GitHub shows a red run and notifies nobody once the check is not required. Not built: a fitness check on a `paths:` filter that leaves out a module its jobs build, until it pays. Three tests seen red first; an independent verifier's findings written in (the per-workflow read, forks' runs, timeouts) |
| D220 | **An update left the generated skills behind.** On a multi-agent project taking v0.29.0, 2026-11-14, the first `nstack attest` after `nstack update` failed Fitness on S3 — skill 'verification' out of sync with its playbook: the update moved the playbook, and the skills, generated and git-ignored, stayed as they were. Neither the update's output nor its next step said to run `nstack skills` | **Done**: where the person generated skills (`.claude/skills/`), `nstack update` generates them again from the updated playbooks and says so — derived files, git-ignored, nothing of anyone's lost; what stops it is said with its action; an update stopped on conflicts says `nstack skills` in its action. `nstack skills` removes a generated skill whose playbook is gone — still loaded by the agent, said by no rule — never one a person wrote. Market: a package manager's post-install step regenerates what it derives. The update scenario and the orphan's test seen red first; an independent verifier's findings written in |
| v0.6.0 | **What is announced refuses, and the documents say what is true**: D51 to D54, and the documentary lot of the internal audit | **Done (2026-09-20)**: five workstreams merged (#83, #84, #85, #86, #87), **v0.6.0 published**, tag on `8ae544c`, verified on published artefacts — including an update of `tool-library` from v0.5.0, 9 files and no conflict, still compliant. Found doing it: D55. Next: the pilot, and M11 beside it |
| Pilot | **`NapkinStack/flet`, the first real project**, run by a session that knew nothing of this repository, with the maintainer as decider and this repository's agent as observer — public on the Free plan, where the whole checklist is available, rather than private on Team where G5 is paid and G6 does not exist | **Set aside by the maintainer, 2026-10-15**, at its cycle boundary; the real product followed since is `summit`. **Ran from 2026-09-20**: discovery decided *go* after three rounds and two independent challenges, charter accepted; cycle 01 closed `stopped/reframed`, **cycle 02 closed** with two deliverables accepted and one deferred (its #27), **cycle 03 framed and approved** (#28, #30), which starts its first `critical` module; the framework taken to v0.6.1 by itself at the boundary (#29), v0.6.2 proposed (#31). It has produced D56 to D63, D68, D70 to D77, replicated D26 and D55, and measured D49 — the first figures on what an independent verifier finds (PDR-0003) |
| M11 | **Ceremony follows consequence** (PDR-0011): the framework charges what a failure costs, per module and per project, and states each price before it is paid; with PDR-0004's routing, and PDR-0007, PDR-0008 and PDR-0010 — through to v0.7.0 | **Published as v0.7.0 (2026-10-12).** Planned 2026-09-23 (#98). Merged: **M11f** (#101), **M11a** (#102), **M11b** (#103), **M11d** (#104), **M11e** (#105), **M11c** (#106), **M11h** (#107), **M11g** (#108) closed by its probe — not clean, returned to M13; **M11m** (D68, D74, D75); **M11l** (PDR-0010, D59, D60); **M11n** (D79); **M11o** (PDR-0010 extended: every document has its moment); **M11p** (PDR-0002's three levels given a place: `docs/project/rules/`); **M11j** (PDR-0007: the unframed stage); **M11q** (no folder created empty; PDR-0012 proposed: a project's tree is the project's). **M11k** (PDR-0008's print mode: `nstack settings`; D77, D78). **M11s** (PDR-0012 accepted; the framework's files under `.nstack/`; an update carries what a project adapted); **M11u** (an update rewrites the old addresses a project wrote in its own files, D85). **M11t** (`nstack new-contract`: the contracts module is created by the first contract; PDR-0012 built in full); **M11v** (what the third project found: D81, D82, D83, D86, D87). **M11i**: v0.7.0 published 2026-10-12 (#125, D88). To do: **M11r** PDR-0008's apply mode and D57, after a probe on the real forge; the two earlier projects take v0.7.0 themselves, observed |
Expand Down
6 changes: 6 additions & 0 deletions platform/tests/run.sh
Original file line number Diff line number Diff line change
Expand Up @@ -872,6 +872,9 @@ commit_project "$A" "Adaptations and first module"
SEATS_BEFORE=$(git -C "$A" rev-parse HEAD:README.md HEAD:SECURITY.md HEAD:modules/README.md HEAD:docs/pdr/README.md)
MODULE_BEFORE=$(git -C "$A" rev-parse HEAD:modules/demo)

# The person's skills, generated and git-ignored, from the playbooks as they are before the update.
nstack skills --root "$A" >/dev/null || { echo "FAIL: nstack skills before the update."; exit 1; }

echo "-> update: started from another branch, it MUST be refused and name both (D74)"
# The pilot ran it from cycle/03-framing: the update branch carried a foreign commit and was
# replanted by hand. Refused before anything is written, and the way back is a command.
Expand Down Expand Up @@ -899,6 +902,9 @@ grep -qF "_commit: v90.2.0" "$A/.copier-answers.yml" \
# The kernel's trailer on the commit an agent's update makes (D135).
[ "$(git -C "$A" log -1 --format='%(trailers:key=Agent-Session,valueonly)' | head -1)" = nstack-test-session ] \
|| { echo "FAIL: the update's commit does not carry the session it was given (D135)."; git -C "$A" log -1; exit 1; }
# D220: a playbook the update moved left the generated skills behind, and the first attest failed S3.
nstack skills --check --root "$A" >/dev/null && grep_text "$OUT" -qF "Skills regenerated from the updated playbooks" \
|| { echo "FAIL: the update left the skills out of sync with its playbooks (D220)."; echo "$OUT"; exit 1; }
grep -qx "checks: attested" "$A/.copier-answers.yml" \
&& grep -qF "The project's answers below" "$A/.copier-answers.yml" \
|| { echo "FAIL: the decider's answer was not kept, or the header forbids writing it (D134)."; head -5 "$A/.copier-answers.yml"; exit 1; }
Expand Down
20 changes: 20 additions & 0 deletions platform/tests/test_skills.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@


def test_a_generated_skill_whose_playbook_is_gone_is_removed_never_a_person_s(tmp_path, capsys):
"""D220: a playbook an update removes left its skill loaded by the agent, said by no rule."""
from napkinstack import skills

playbooks = tmp_path / ".nstack" / "playbooks"
playbooks.mkdir(parents=True)
(playbooks / "kept.md").write_text("# Kept\n\nDo this.\n", encoding="utf-8")
(tmp_path / ".nstack" / "skills.yaml").write_text(
"skills:\n kept:\n source: .nstack/playbooks/kept.md\n description: Use when keeping.\n", encoding="utf-8")
gone = tmp_path / ".claude" / "skills" / "gone"
gone.mkdir(parents=True)
(gone / "SKILL.md").write_text("---\nname: gone\n---\n\n<!-- GENERATED from x by nstack skills - DO NOT EDIT.\n", encoding="utf-8")
mine = tmp_path / ".claude" / "skills" / "mine"
mine.mkdir()
(mine / "SKILL.md").write_text("---\nname: mine\n---\n\nWritten by a person.\n", encoding="utf-8")
assert skills.run(tmp_path) == 0
assert not gone.exists() and (mine / "SKILL.md").is_file()
assert "removed, their playbook gone: gone" in capsys.readouterr().out
27 changes: 25 additions & 2 deletions src/napkinstack/project.py
Original file line number Diff line number Diff line change
Expand Up @@ -555,8 +555,8 @@ def update(root: Path, ref: str, session: str | None = None) -> int:
for path in conflicts:
print(f" - {path}")
print(" Action: in each file, keep the right version between <<<<<<< and >>>>>>>, "
"then git add --all && git commit.\n The check-merge-conflict hook and CI "
"reject any remaining marker.")
"then git add --all && git commit, and nstack skills — the generated skills follow the playbooks.\n"
" The check-merge-conflict hook and CI reject any remaining marker.")
return 1
# An agent's update carries the kernel's trailer, as every commit it makes (D135).
message = f"NapkinStack {previous} -> {current}" + (f"\n\nAgent-Session: {session}" if session else "")
Expand Down Expand Up @@ -591,10 +591,33 @@ def update(root: Path, ref: str, session: str | None = None) -> int:
f"{release_notes(str(_answers(root).get('_src_path') or ''), previous, current)}")
if note := _not_yet_published(current):
print(note)
if said := _refresh_skills(root):
print(said)
print(f"\n{next_step(root, branch)}")
return 0


def _refresh_skills(root: Path) -> str | None:
"""D220: the skills are generated from the playbooks and git-ignored, so an update that moves a
playbook leaves them behind, and the first check fails S3. Where the person generated them, the
update generates them again: derived files, nothing of anyone's lost. None where there are none."""
import contextlib
import io

from napkinstack import skills

if not (root / ".claude" / "skills").is_dir():
return None
said = io.StringIO()
with contextlib.redirect_stdout(said):
code = skills.run(root)
if code == 0:
return "Skills regenerated from the updated playbooks (.claude/skills/, not committed)."
return ("The skills could not be regenerated from the updated playbooks:\n"
+ "".join(f" {line}\n" for line in said.getvalue().splitlines())
+ " Action: fix what it says, then nstack skills.")


def _not_yet_published(ref: str) -> str | None:
"""D201: the project's CI installs a published version from the registry. Updated to one it does
not list yet — an engine run from its sources is ahead of the release — the pull request's
Expand Down
13 changes: 12 additions & 1 deletion src/napkinstack/skills.py
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,18 @@ def run(root: Path, check_only: bool = False) -> int:
print(f"Skills: {len(mapping)} in sync with the playbooks.")
return 0

print(f"Skills generated in .claude/skills/: {written}")
# A playbook gone leaves its skill behind, still loaded by the agent: removed when generated here,
# never a skill a person wrote (no banner).
removed = []
for folder in sorted(skill_dir.glob("*/")) if skill_dir.is_dir() else []:
made = folder / "SKILL.md"
if folder.name not in mapping and made.is_file() and "by nstack skills - DO NOT EDIT" in made.read_text(encoding="utf-8"):
made.unlink()
if not any(folder.iterdir()):
folder.rmdir()
removed.append(folder.name)
print(f"Skills generated in .claude/skills/: {written}"
+ (f"; removed, their playbook gone: {', '.join(removed)}" if removed else ""))
for name in sorted(mapping):
print(f" - {name}")
print("\nThey trigger on their own from their description; an agent can also")
Expand Down
Loading