deepclause-pi 0.2.0 → 0.4.0

package/src/assets/specs.dml

@@ -0,0 +1,995 @@
+%%% specs.dml — deterministic DML spec engine (phase 1).
+%%%
+%%% Parses DeepClause/OpenSpec-style Markdown specs and deltas, validates their
+%%% structure, and produces reports, status, queries and Mermaid graphs.
+%%%
+%%% Pure Prolog: never calls the model (no task/1, no prompt/1) and never
+%%% executes a runtime tool. Skills consult it and supply agent_main.
+%%%
+%%% Layout it understands:
+%%%   .pi/deepclause/specs/**/*.md                 capability specs (source of truth)
+%%%   .pi/deepclause/changes/<slug>/specs/**/*.md  change deltas
+
+%% ---------------------------------------------------------------------------
+%% Line and heading utilities
+%% ---------------------------------------------------------------------------
+
+sp_count_hashes(S, Acc, N) :-
+    (   sub_string(S, 0, 1, _, "#")
+    ->  sub_string(S, 1, _, 0, S1),
+        Acc1 is Acc + 1,
+        sp_count_hashes(S1, Acc1, N)
+    ;   N = Acc
+    ).
+
+%% sp_heading(+Line, -Level, -Text). Level is 0 for a non-heading line.
+sp_heading(Line, Level, Text) :-
+    sp_count_hashes(Line, 0, C),
+    (   C > 0,
+        sub_string(Line, C, _, 0, Rest),
+        sub_string(Rest, 0, 1, _, " ")
+    ->  Level = C,
+        sub_string(Rest, 1, _, 0, Raw),
+        normalize_space(string(Text), Raw)
+    ;   Level = 0,
+        Text = ""
+    ).
+
+sp_number([], _, []).
+sp_number([Line|Lines], N, [line(Line, N)|Out]) :-
+    N1 is N + 1,
+    sp_number(Lines, N1, Out).
+
+sp_lines(Text, Numbered) :-
+    split_string(Text, "\n", "", Raw),
+    sp_number(Raw, 1, Numbered).
+
+sp_trimmed(List, Out) :-
+    findall(Text, (
+        member(line(Line, _), List),
+        normalize_space(string(Text), Line),
+        Text \= ""
+    ), Out).
+
+%% Join non-blank body lines with spaces, for prose (purpose, description).
+sp_prose(List, Text) :-
+    sp_trimmed(List, Parts),
+    atomics_to_string(Parts, " ", Text).
+
+%% ---------------------------------------------------------------------------
+%% Section splitting: stops at heading levels 1-3; level 4+ stays in the body.
+%% ---------------------------------------------------------------------------
+
+sp_sections(Lines, Sections) :-
+    sp_skip_plain(Lines, Rest),
+    sp_sections_from(Rest, Sections).
+
+sp_skip_plain([], []).
+sp_skip_plain([Item|Rest], Out) :-
+    (   Item = line(Line, _), sp_heading(Line, Level, _), Level >= 1, Level =< 3
+    ->  Out = [Item|Rest]
+    ;   sp_skip_plain(Rest, Out)
+    ).
+
+sp_sections_from([], []).
+sp_sections_from([line(Line, N)|Rest], [section(Level, Text, N, Body)|More]) :-
+    sp_heading(Line, Level, Text),
+    Level >= 1,
+    Level =< 3,
+    sp_take_body(Rest, Body, Tail),
+    sp_sections_from(Tail, More).
+
+sp_take_body([], [], []).
+sp_take_body([Item|Rest], Body, Tail) :-
+    (   Item = line(Line, _), sp_heading(Line, Level, _), Level >= 1, Level =< 3
+    ->  Body = [], Tail = [Item|Rest]
+    ;   Body = [Item|Body1], sp_take_body(Rest, Body1, Tail)
+    ).
+
+%% Split a requirement body (level-4 headings inline) into description + scenarios.
+sp_split_scenarios(Body, DescLines, ScenarioSections) :-
+    sp_take_plain(Body, DescLines, Rest),
+    sp_scenario_sections(Rest, ScenarioSections).
+
+sp_take_plain([], [], []).
+sp_take_plain([Item|Rest], Body, Tail) :-
+    (   Item = line(Line, _), sp_heading(Line, Level, _), Level >= 4
+    ->  Body = [], Tail = [Item|Rest]
+    ;   Body = [Item|Body1], sp_take_plain(Rest, Body1, Tail)
+    ).
+
+sp_scenario_sections([], []).
+sp_scenario_sections([line(Line, N)|Rest], [section(4, Text, N, Body)|More]) :-
+    sp_heading(Line, 4, Text),
+    sp_take_until_level4(Rest, Body, Tail),
+    sp_scenario_sections(Tail, More).
+
+sp_take_until_level4([], [], []).
+sp_take_until_level4([Item|Rest], Body, Tail) :-
+    (   Item = line(Line, _), sp_heading(Line, Level, _), Level >= 4
+    ->  Body = [], Tail = [Item|Rest]
+    ;   Body = [Item|Body1], sp_take_until_level4(Rest, Body1, Tail)
+    ).
+
+%% ---------------------------------------------------------------------------
+%% Term extraction
+%% ---------------------------------------------------------------------------
+
+sp_requirement_name(Text, Name) :-
+    string_concat("Requirement:", Rest, Text),
+    normalize_space(string(Name), Rest),
+    Name \= "".
+
+sp_scenario_name(Text, Name) :-
+    string_concat("Scenario:", Rest, Text),
+    normalize_space(string(Name), Rest),
+    Name \= "".
+
+sp_requirement_body(Body, Desc, Scenarios) :-
+    sp_split_scenarios(Body, DescLines, ScenarioSections),
+    sp_prose(DescLines, Desc),
+    findall(scenario(Name, N, Steps), (
+        member(section(4, Text, N, SBody), ScenarioSections),
+        sp_scenario_name(Text, Name),
+        sp_trimmed(SBody, Steps)
+    ), Scenarios).
+
+%% spec(Title, Purpose, [req(Name, Line, Description, Scenarios)])
+sp_parse_spec(Text, spec(Title, Purpose, Requirements)) :-
+    sp_lines(Text, Lines),
+    sp_sections(Lines, Sections),
+    (   member(section(1, T, _, _), Sections)
+    ->  Title = T
+    ;   Title = ""
+    ),
+    (   member(section(2, "Purpose", _, PurposeBody), Sections)
+    ->  sp_prose(PurposeBody, Purpose)
+    ;   Purpose = ""
+    ),
+    findall(req(Name, N, Desc, Scenarios), (
+        member(section(3, Heading, N, Body), Sections),
+        sp_requirement_name(Heading, Name),
+        sp_requirement_body(Body, Desc, Scenarios)
+    ), Requirements).
+
+%% Delta op section headers.
+sp_delta_header("ADDED Requirements", added).
+sp_delta_header("MODIFIED Requirements", modified).
+sp_delta_header("REMOVED Requirements", removed).
+sp_delta_header("RENAMED Requirements", renamed).
+
+%% [delta(Op, [req(Name, Line, Description, Scenarios)])]
+sp_parse_delta(Text, Deltas) :-
+    sp_lines(Text, Lines),
+    sp_sections(Lines, Sections),
+    sp_drop_to_op(Sections, Rest),
+    sp_collect_ops(Rest, Deltas).
+
+sp_drop_to_op([], []).
+sp_drop_to_op([Item|Rest], Out) :-
+    (   Item = section(2, Header, _, _), sp_delta_header(Header, _)
+    ->  Out = [Item|Rest]
+    ;   sp_drop_to_op(Rest, Out)
+    ).
+
+sp_collect_ops([], []).
+sp_collect_ops([section(2, Header, _, _)|Rest], Deltas) :-
+    (   sp_delta_header(Header, Op)
+    ->  sp_take_until_op(Rest, Group, Tail),
+        findall(req(Name, N, Desc, Scenarios), (
+            member(section(3, Heading, N, Body), Group),
+            sp_requirement_name(Heading, Name),
+            sp_requirement_body(Body, Desc, Scenarios)
+        ), Reqs),
+        Deltas = [delta(Op, Reqs)|More],
+        sp_collect_ops(Tail, More)
+    ;   sp_collect_ops(Rest, Deltas)
+    ).
+
+sp_take_until_op([], [], []).
+sp_take_until_op([Item|Rest], Group, Tail) :-
+    (   Item = section(2, Header, _, _), sp_delta_header(Header, _)
+    ->  Group = [], Tail = [Item|Rest]
+    ;   Group = [Item|Group1], sp_take_until_op(Rest, Group1, Tail)
+    ).
+
+%% ---------------------------------------------------------------------------
+%% Validation
+%% ---------------------------------------------------------------------------
+
+%% 3-hash Scenario and 4-hash Requirement are the classic silent failures.
+sp_heading_errors(File, Lines, Errors) :-
+    findall(error(File, N, Message), (
+        member(line(Line, N), Lines),
+        sp_heading(Line, Level, Text),
+        Level > 0,
+        sp_heading_error(Level, Text, Message)
+    ), Errors).
+
+sp_heading_error(3, Text, "scenario heading must use #### (4 hashes), not ###") :-
+    string_concat("Scenario", _, Text),
+    !.
+sp_heading_error(4, Text, "requirement heading must use ### (3 hashes), not ####") :-
+    string_concat("Requirement", _, Text),
+    !.
+
+sp_requirement_errors(File, Requirements, Errors) :-
+    findall(error(File, N, Message), (
+        member(req(Name, N, _, Scenarios), Requirements),
+        Scenarios == [],
+        format(string(Message), "requirement '~w' has no scenario", [Name])
+    ), Errors).
+
+sp_duplicate_errors(File, Requirements, Errors) :-
+    findall(error(File, N, Message), (
+        member(req(Name, N, _, _), Requirements),
+        member(req(Name, Earlier, _, _), Requirements),
+        Earlier < N,
+        format(string(Message), "duplicate requirement '~w' (first at line ~w)", [Name, Earlier])
+    ), Errors).
+
+sp_delta_errors(File, Deltas, Errors) :-
+    findall(error(File, N, Message), (
+        member(delta(Op, Requirements), Deltas),
+        ( Op == added ; Op == modified ),
+        member(req(Name, N, _, Scenarios), Requirements),
+        Scenarios == [],
+        format(string(Message), "~w requirement '~w' has no scenario", [Op, Name])
+    ), Errors).
+
+sp_validate_spec(File, Text, Errors) :-
+    sp_lines(Text, Lines),
+    sp_parse_spec(Text, spec(_, _, Requirements)),
+    sp_heading_errors(File, Lines, E1),
+    sp_requirement_errors(File, Requirements, E2),
+    sp_duplicate_errors(File, Requirements, E3),
+    append(E1, E2, A),
+    append(A, E3, Errors).
+
+sp_validate_delta(File, Text, Errors) :-
+    sp_lines(Text, Lines),
+    sp_parse_delta(Text, Deltas),
+    sp_heading_errors(File, Lines, E1),
+    sp_delta_errors(File, Deltas, E2),
+    append(E1, E2, Errors).
+
+%% ---------------------------------------------------------------------------
+%% File discovery (missing directories simply yield no files)
+%% ---------------------------------------------------------------------------
+
+sp_walk(Dir, Exts, Files) :-
+    (   exists_directory(Dir)
+    ->  directory_files(Dir, Names),
+        sp_walk_names(Names, Dir, Exts, Files)
+    ;   Files = []
+    ).
+
+sp_walk_names([], _, _, []).
+sp_walk_names([Name|Rest], Dir, Exts, Files) :-
+    Name \= ".",
+    Name \= "..",
+    atomic_list_concat([Dir, "/", Name], Path),
+    (   exists_directory(Path)
+    ->  sp_walk(Path, Exts, Sub)
+    ;   (   file_name_extension(_, Ext, Path),
+            memberchk(Ext, Exts)
+        ->  Sub = [Path]
+        ;   Sub = []
+        )
+    ),
+    sp_walk_names(Rest, Dir, Exts, More),
+    append(Sub, More, Files).
+
+sp_spec_files(Files) :-
+    sp_walk(".pi/deepclause/specs", [md], Files).
+
+sp_change_dirs(Dirs) :-
+    (   exists_directory(".pi/deepclause/changes")
+    ->  directory_files(".pi/deepclause/changes", Names),
+        findall(Path, (
+            member(Name, Names),
+            Name \= ".",
+            Name \= "..",
+            Name \= "archive",
+            atomic_list_concat([".pi/deepclause/changes/", Name], Path),
+            exists_directory(Path)
+        ), Dirs)
+    ;   Dirs = []
+    ).
+
+sp_change_delta_files(Change, Files) :-
+    atomic_list_concat([Change, "/specs"], Dir),
+    sp_walk(Dir, [md], Files).
+
+sp_all_delta_files(Dirs, Files) :-
+    findall(All, (member(D, Dirs), sp_change_delta_files(D, All)), Nested),
+    append(Nested, Files).
+
+%% Capability id from a spec path: specs/ui/theme.spec.md -> ui/theme
+sp_capability_id(File, Id) :-
+    (   sub_string(File, Before, _, _, "/specs/")
+    ->  After is Before + 7,
+        sub_string(File, After, _, 0, Rest),
+        (   string_concat(Id, ".spec.md", Rest)
+        ->  true
+        ;   string_concat(Id, ".md", Rest)
+        ->  true
+        ;   Id = Rest
+        )
+    ;   sp_short_id(File, Id)
+    ).
+
+%% Capability id from a single-file path: ui/theme.spec.md -> ui/theme
+sp_short_id(File, Id) :-
+    file_base_name(File, Base),
+    (   file_name_extension(Stem, md, Base)
+    ->  atom_string(StemText, Stem),
+        (   string_concat(Id, ".spec", StemText)
+        ->  true
+        ;   Id = StemText
+        )
+    ;   Id = Base
+    ).
+
+%% ---------------------------------------------------------------------------
+%% Reports
+%% ---------------------------------------------------------------------------
+
+sp_read_check_spec(File, Summary, Errors) :-
+    read_file_to_string(File, Text, []),
+    sp_capability_id(File, Id),
+    sp_parse_spec(Text, spec(Title, _, Reqs)),
+    length(Reqs, ReqCount),
+    findall(S, (member(req(_, _, _, Ss), Reqs), member(S, Ss)), Scenarios),
+    length(Scenarios, ScenarioCount),
+    format(string(Summary), "spec ~w: ~w requirements, ~w scenarios", [Id, ReqCount, ScenarioCount]),
+    sp_validate_spec(File, Text, Errors).
+
+sp_read_check_delta(File, Summary, Errors) :-
+    read_file_to_string(File, Text, []),
+    sp_parse_delta(Text, Deltas),
+    findall(op(Op, Reqs), member(delta(Op, Reqs), Deltas), Ops),
+    findall(S, (member(op(_, Reqs), Ops), member(req(_, _, _, Ss), Reqs), member(S, Ss)), Scenarios),
+    length(Scenarios, ScenarioCount),
+    format(string(Summary), "delta ~w: ~w operation sections, ~w scenarios", [File, Ops, ScenarioCount]),
+    sp_validate_delta(File, Text, Errors).
+
+sp_error_line(error(File, Line, Message), Rendered) :-
+    format(string(Rendered), "  ~w:~w  ~w", [File, Line, Message]).
+
+sp_check_all(Report) :-
+    sp_spec_files(SpecFiles),
+    sp_change_dirs(ChangeDirs),
+    sp_all_delta_files(ChangeDirs, DeltaFiles),
+    findall(Summary, (member(F, SpecFiles), sp_read_check_spec(F, Summary, _)), SpecSummaries),
+    findall(Summary, (member(F, DeltaFiles), sp_read_check_delta(F, Summary, _)), DeltaSummaries),
+    findall(E, (member(F, SpecFiles), sp_read_check_spec(F, _, Es), member(E, Es)), SpecErrors),
+    findall(E, (member(F, DeltaFiles), sp_read_check_delta(F, _, Es), member(E, Es)), DeltaErrors),
+    append(SpecErrors, DeltaErrors, BaseErrors),
+    findall(Line, (member(Dir, ChangeDirs), sp_coverage_line(Dir, Line)), CoverageLines),
+    findall(E, (member(Dir, ChangeDirs), sp_coverage_errors(Dir, Es), member(E, Es)), CoverageErrors),
+    append(BaseErrors, CoverageErrors, Errors),
+    length(Errors, ErrorCount),
+    (   ErrorCount =:= 0 -> Status = "OK" ; Status = "FAILED" ),
+    length(SpecFiles, CapCount),
+    length(DeltaFiles, DeltaCount),
+    findall(EL, (member(E, Errors), sp_error_line(E, EL)), ErrorLines),
+    (   ErrorLines == [] -> ErrorBlock = ["  no structural errors"] ; ErrorBlock = ErrorLines ),
+    format(string(Header), "spec check: ~w  (~w capabilities, ~w deltas, ~w errors)", [Status, CapCount, DeltaCount, ErrorCount]),
+    append([Header], SpecSummaries, L1),
+    append(L1, DeltaSummaries, L2),
+    append(L2, [""], L3),
+    append(L3, CoverageLines, L4),
+    append(L4, [""], L5),
+    append(L5, ErrorBlock, Body),
+    atomics_to_string(Body, "\n", Report).
+
+sp_status(Report) :-
+    sp_spec_files(SpecFiles),
+    sp_change_dirs(ChangeDirs),
+    sp_all_delta_files(ChangeDirs, DeltaFiles),
+    findall(Cap, (member(F, SpecFiles), sp_capability_id(F, Cap)), CapIds),
+    length(SpecFiles, CapCount),
+    length(DeltaFiles, DeltaCount),
+    length(ChangeDirs, ChangeCount),
+    atomics_to_string(CapIds, ", ", CapList),
+    (   CapIds == [] -> CapList = "none" ; true ),
+    format(string(CapLine), "capabilities: ~w  (~w)", [CapCount, CapList]),
+    format(string(ChangeLine), "active changes: ~w", [ChangeCount]),
+    format(string(DeltaLine), "delta files: ~w", [DeltaCount]),
+    atomics_to_string([CapLine, ChangeLine, DeltaLine], "\n", Report).
+
+sp_capability_file(Capability, File) :-
+    sp_spec_files(Files),
+    member(File, Files),
+    sp_capability_id(File, Capability).
+
+sp_query(Capability, Report) :-
+    (   sp_capability_file(Capability, File)
+    ->  read_file_to_string(File, Text, []),
+        sp_parse_spec(Text, spec(Title, Purpose, Reqs)),
+        findall(RL, (member(req(Name, _, Desc, Ss), Reqs), length(Ss, SN),
+            format(string(RL), "  ~w  (~w scenarios)  ~w", [Name, SN, Desc])), RLs),
+        format(string(Header), "capability ~w — ~w", [Capability, Title]),
+        format(string(PurposeLine), "purpose: ~w", [Purpose]),
+        (   RLs == [] -> ReqBlock = ["  (no requirements)"] ; ReqBlock = RLs ),
+        append([Header, PurposeLine, "requirements:"], ReqBlock, Body),
+        atomics_to_string(Body, "\n", Report)
+    ;   format(string(Report), "unknown capability: ~w", [Capability])
+    ).
+
+%% ---------------------------------------------------------------------------
+%% Mermaid graphs
+%% ---------------------------------------------------------------------------
+
+sp_graph_caps([], N, [], N).
+sp_graph_caps([File|Rest], N0, Lines, N) :-
+    read_file_to_string(File, Text, []),
+    sp_parse_spec(Text, spec(Title, _, Reqs)),
+    sp_capability_id(File, Cap),
+    N1 is N0 + 1,
+    format(string(CapNode), "  n~w[\"~w — ~w\"]", [N1, Cap, Title]),
+    N2 is N1 + 1,
+    sp_graph_reqs(Reqs, N1, N2, N3, ReqLines),
+    sp_graph_caps(Rest, N3, RestLines, N),
+    append([CapNode|ReqLines], RestLines, Lines).
+
+sp_graph_reqs([], _, N, N, []).
+sp_graph_reqs([req(Name, _, _, Scenarios)|Rest], Parent, N0, N, Lines) :-
+    N1 is N0 + 1,
+    format(string(NodeLine), "  n~w[\"Requirement: ~w\"]", [N1, Name]),
+    format(string(EdgeLine), "  n~w --> n~w", [Parent, N1]),
+    N2 is N1 + 1,
+    sp_graph_scenarios(Scenarios, N1, N2, N3, ScenarioLines),
+    sp_graph_reqs(Rest, Parent, N3, N, RestLines),
+    append([NodeLine, EdgeLine|ScenarioLines], RestLines, Lines).
+
+sp_graph_scenarios([], _, N, N, []).
+sp_graph_scenarios([scenario(Name, _, _)|Rest], Parent, N0, N, Lines) :-
+    N1 is N0 + 1,
+    format(string(NodeLine), "  n~w[\"Scenario: ~w\"]", [N1, Name]),
+    format(string(EdgeLine), "  n~w --> n~w", [Parent, N1]),
+    sp_graph_scenarios(Rest, Parent, N1, N, RestLines),
+    Lines = [NodeLine, EdgeLine|RestLines].
+
+% The runtime passes CLI arguments as strings, while the view clauses below are
+% keyed on atoms. Normalize before dispatch so a string view does not silently
+% fall through to the capabilities catch-all.
+sp_graph(View, Mermaid) :-
+    string(View),
+    atom_string(Atom, View),
+    sp_graph(Atom, Mermaid).
+
+sp_graph(changes, Mermaid) :-
+    sp_change_dirs(ChangeDirs),
+    sp_graph_change_nodes(ChangeDirs, 0, Lines, _),
+    (   Lines == [] -> Body = ["  empty[\"no active changes\"]"] ; Body = Lines ),
+    atomics_to_string(["flowchart LR"|Body], "\n", Mermaid).
+
+sp_graph_change_nodes([], N, [], N).
+sp_graph_change_nodes([Dir|Rest], N0, Lines, N) :-
+    file_base_name(Dir, Name),
+    N1 is N0 + 1,
+    format(string(NodeLine), "  n~w[\"~w\"]", [N1, Name]),
+    sp_change_delta_files(Dir, DeltaFiles),
+    sp_graph_delta_edges(DeltaFiles, N1, N1, N2, EdgeLines),
+    sp_graph_change_nodes(Rest, N2, RestLines, N),
+    append([NodeLine|EdgeLines], RestLines, Lines).
+
+sp_graph_delta_edges([], _, N, N, []).
+sp_graph_delta_edges([File|Rest], Parent, N0, N, Lines) :-
+    sp_capability_id(File, Cap),
+    N1 is N0 + 1,
+    format(string(NodeLine), "  n~w[\"~w\"]", [N1, Cap]),
+    format(string(EdgeLine), "  n~w -- touches --> n~w", [Parent, N1]),
+    sp_graph_delta_edges(Rest, Parent, N1, N, RestLines),
+    Lines = [NodeLine, EdgeLine|RestLines].
+
+sp_graph(capabilities, Mermaid) :-
+    sp_spec_files(Files),
+    sp_graph_caps(Files, 0, Lines, _),
+    (   Lines == [] -> Body = ["  empty[\"no specs found\"]"] ; Body = Lines ),
+    atomics_to_string(["flowchart LR"|Body], "\n", Mermaid).
+
+sp_graph(_, Mermaid) :-
+    sp_graph(capabilities, Mermaid).
+
+%% ---------------------------------------------------------------------------
+%% Merge and archive
+%%
+%% Reads an existing capability spec plus a change delta and produces the merged
+%% spec. Unchanged requirement blocks are preserved line-for-line; only added,
+%% modified and removed requirements change. RENAMED is refused for now.
+%% ---------------------------------------------------------------------------
+
+sp_line_at([line(Line, N)|_], N, Line) :- !.
+sp_line_at([_|Rest], N, Line) :- sp_line_at(Rest, N, Line).
+
+sp_raw_lines(List, Lines) :- findall(Line, member(line(Line, _), List), Lines).
+
+sp_last([X], X) :- !.
+sp_last([_|Rest], X) :- sp_last(Rest, X).
+
+%% Purpose + delta operations, including the delta's ## Purpose section.
+sp_parse_delta_full(Text, Purpose, Deltas) :-
+    sp_lines(Text, Lines),
+    sp_sections(Lines, Sections),
+    (   member(section(2, "Purpose", _, PurposeBody), Sections)
+    ->  sp_prose(PurposeBody, Purpose)
+    ;   Purpose = ""
+    ),
+    sp_drop_to_op(Sections, Rest),
+    sp_collect_ops(Rest, Deltas).
+
+%% Existing requirements with their source line ranges.
+sp_spec_ranges(Text, Reqs) :-
+    sp_lines(Text, Lines),
+    sp_sections(Lines, Sections),
+    findall(req_range(Name, Start, End, Desc, Scenarios), (
+        member(section(3, Heading, Start, Body), Sections),
+        sp_requirement_name(Heading, Name),
+        sp_body_end(Body, Start, End),
+        sp_requirement_body(Body, Desc, Scenarios)
+    ), Reqs).
+
+sp_body_end([], Start, Start).
+sp_body_end(Body, Start, End) :-
+    findall(N, member(line(_, N), Body), Numbers),
+    (   Numbers == []
+    ->  End = Start
+    ;   sp_last(Numbers, End)
+    ).
+
+sp_read_optional(Path, Text) :-
+    (   catch(read_file_to_string(Path, Text0, []), _, fail)
+    ->  Text = Text0
+    ;   Text = none
+    ).
+
+sp_write_file(Path, Text) :-
+    open(Path, write, Stream),
+    write(Stream, Text),
+    close(Stream).
+
+%% Delta helpers.
+sp_delta_ops(Deltas, Op, Reqs) :-
+    findall(Req, (member(delta(Op, Group), Deltas), member(Req, Group)), Reqs).
+
+sp_delta_has(Deltas, Op, Name) :-
+    member(delta(Op, Group), Deltas),
+    member(req(Name, _, _, _), Group),
+    !.
+
+sp_delta_req(Deltas, Op, Name, Req) :-
+    member(delta(Op, Group), Deltas),
+    member(Req, Group),
+    Req = req(Name, _, _, _),
+    !.
+
+sp_delta_op_summary(Deltas, Ops) :-
+    findall(op(Op, Name), (
+        member(delta(Op, Group), Deltas),
+        member(req(Name, _, _, _), Group)
+    ), Ops).
+
+%% Canonical rendering of one requirement and its scenarios.
+sp_render_requirement(req(Name, _, Desc, Scenarios), Lines) :-
+    format(string(Heading), "### Requirement: ~w", [Name]),
+    findall(Block, (member(Scenario, Scenarios), sp_render_scenario(Scenario, Block)), Blocks),
+    append(Blocks, Flat),
+    (   Desc == ""
+    ->  Head = [Heading, ""]
+    ;   Head = [Heading, "", Desc, ""]
+    ),
+    append(Head, Flat, Lines).
+
+sp_render_scenario(scenario(Name, _, Steps), Lines) :-
+    format(string(Heading), "#### Scenario: ~w", [Name]),
+    append([Heading|Steps], [""], Lines).
+
+sp_render_new_spec(Capability, Purpose, Deltas, Lines) :-
+    format(string(Title), "# ~w Specification", [Capability]),
+    sp_delta_ops(Deltas, added, Added),
+    findall(Block, (member(Req, Added), sp_render_requirement(Req, Block)), Blocks),
+    append(Blocks, Flat),
+    (   Purpose == ""
+    ->  Head = [Title, "", "## Purpose", "", "## Requirements", ""]
+    ;   Head = [Title, "", "## Purpose", "", Purpose, "", "## Requirements", ""]
+    ),
+    append(Head, Flat, Lines).
+
+%% Merge actions: drop or replace one existing requirement block.
+sp_build_actions([], _, []).
+sp_build_actions([req_range(Name, Start, End, _, _)|Rest], Deltas, Actions) :-
+    (   sp_delta_has(Deltas, removed, Name)
+    ->  Action = op(Start, End, drop)
+    ;   sp_delta_req(Deltas, modified, Name, NewReq)
+    ->  sp_render_requirement(NewReq, NewLines),
+        Action = op(Start, End, replace(NewLines))
+    ;   Action = none
+    ),
+    sp_build_actions(Rest, Deltas, RestActions),
+    (   Action == none
+    ->  Actions = RestActions
+    ;   Actions = [Action|RestActions]
+    ).
+
+sp_skip_to([], _, []).
+sp_skip_to([line(_, N)|Rest], End, Tail) :-
+    N =< End,
+    !,
+    sp_skip_to(Rest, End, Tail).
+sp_skip_to(List, _, List).
+
+sp_merge_walk([], _, []).
+sp_merge_walk([line(Line, N)|Rest], Actions, Out) :-
+    (   memberchk(op(N, End, drop), Actions)
+    ->  sp_skip_to(Rest, End, Tail),
+        sp_merge_walk(Tail, Actions, Out)
+    ;   memberchk(op(N, End, replace(NewLines)), Actions)
+    ->  sp_skip_to(Rest, End, Tail),
+        sp_merge_walk(Tail, Actions, Out1),
+        append(NewLines, Out1, Out)
+    ;   Out = [Line|Out1],
+        sp_merge_walk(Rest, Actions, Out1)
+    ).
+
+sp_added_lines(Deltas, Lines) :-
+    sp_delta_ops(Deltas, added, Added),
+    (   Added == []
+    ->  Lines = []
+    ;   findall(Block, (member(Req, Added), sp_render_requirement(Req, Block)), Blocks),
+        append(Blocks, Flat),
+        Lines = [""|Flat]
+    ).
+
+%% Merge one delta file into its capability spec.
+sp_do_merge(Capability, Purpose, Deltas, SpecPath, Mode, Ops) :-
+    sp_delta_op_summary(Deltas, Ops),
+    sp_read_optional(SpecPath, Existing),
+    (   Existing == none
+    ->  sp_require_added_only(Deltas),
+        sp_render_new_spec(Capability, Purpose, Deltas, Lines)
+    ;   sp_lines(Existing, Numbered),
+        sp_spec_ranges(Existing, Reqs),
+        sp_require_targets(Deltas, Reqs),
+        sp_build_actions(Reqs, Deltas, Actions),
+        sp_merge_walk(Numbered, Actions, Preserved),
+        sp_added_lines(Deltas, Added),
+        append(Preserved, Added, Lines)
+    ),
+    (   Mode == apply
+    ->  atomics_to_string(Lines, "\n", Joined),
+        (   sub_string(Joined, _, 1, 0, "\n")
+        ->  Text = Joined
+        ;   string_concat(Joined, "\n", Text)
+        ),
+        sp_write_file(SpecPath, Text)
+    ;   true
+    ).
+
+sp_merge_error_message(error(merge_error(Message)), Message) :- !.
+sp_merge_error_message(Err, Message) :- format(string(Message), "merge failed: ~w", [Err]).
+
+%% A brand-new capability may only add requirements.
+sp_require_added_only(Deltas) :-
+    findall(Op, (member(delta(Op, Reqs), Deltas), (Op == modified ; Op == removed), Reqs \= []), Ops0),
+    sort(Ops0, Ops),
+    (   Ops == []
+    ->  true
+    ;   atomics_to_string(Ops, ", ", OpList),
+        format(string(Message), "~w operations need an existing spec; only ## ADDED Requirements is allowed for a new capability", [OpList]),
+        throw(error(merge_error(Message)))
+    ).
+
+%% MODIFIED and REMOVED must name requirements that exist in the target spec.
+sp_require_targets(Deltas, Reqs) :-
+    findall(Name, (
+        member(delta(Op, Group), Deltas),
+        ( Op == modified ; Op == removed ),
+        member(req(Name, _, _, _), Group)
+    ), Targets0),
+    sort(Targets0, Targets),
+    findall(BaseName, member(req_range(BaseName, _, _, _, _), Reqs), BaseNames0),
+    sort(BaseNames0, BaseNames),
+    findall(Name, (member(Name, Targets), \+ memberchk(Name, BaseNames)), Missing0),
+    sort(Missing0, Missing),
+    (   Missing == []
+    ->  true
+    ;   atomics_to_string(Missing, ", ", MissingList),
+        format(string(Message), "MODIFIED/REMOVED requirements not found in the target spec: ~w", [MissingList]),
+        throw(error(merge_error(Message)))
+    ).
+
+sp_spec_relpath(File, Rel) :-
+    sub_string(File, Before, _, _, "/specs/"),
+    After is Before + 7,
+    sub_string(File, After, _, 0, Rel).
+
+sp_spec_path_from_delta(File, SpecPath) :-
+    sp_spec_relpath(File, Rel),
+    atomic_list_concat([".pi/deepclause/specs/", Rel], SpecPath).
+
+sp_merge_capability(File, Mode, Result) :-
+    read_file_to_string(File, DeltaText, []),
+    sp_parse_delta_full(DeltaText, Purpose, Deltas),
+    sp_capability_id(File, Capability),
+    sp_spec_path_from_delta(File, SpecPath),
+    sp_delta_ops(Deltas, renamed, RenamedOps),
+    (   RenamedOps \= []
+    ->  Result = result(Capability, SpecPath, [], error("RENAMED requirements are not supported by spec_archive yet"))
+    ;   (   catch(sp_do_merge(Capability, Purpose, Deltas, SpecPath, Mode, Ops), Err,
+                  (sp_merge_error_message(Err, Message), Ops = error(Message)))
+        ->  (   Ops = error(Message)
+            ->  Result = result(Capability, SpecPath, [], error(Message))
+            ;   Result = result(Capability, SpecPath, Ops, ok)
+            )
+        ;   Result = result(Capability, SpecPath, [], error("merge failed"))
+        )
+    ).
+
+sp_archive_result_line(result(Capability, SpecPath, Ops, ok), Line) :-
+    length(Ops, Count),
+    format(string(Line), "  ~w -> ~w  (~w changes)", [Capability, SpecPath, Count]).
+sp_archive_result_line(result(Capability, SpecPath, _, error(Reason)), Line) :-
+    format(string(Line), "  ~w -> ~w  ERROR: ~w", [Capability, SpecPath, Reason]).
+
+sp_archive(Change, Mode, Report) :-
+    atomic_list_concat([".pi/deepclause/changes/", Change], ChangeDir),
+    (   catch(directory_files(ChangeDir, _), _, fail)
+    ->  sp_change_delta_files(ChangeDir, DeltaFiles),
+        findall(R, (member(File, DeltaFiles), sp_merge_capability(File, Mode, R)), Results),
+        sp_archive_render(Change, Mode, Results, Body),
+        atomics_to_string(Body, "\n", Report)
+    ;   format(string(Report), "unknown change: ~w", [Change])
+    ).
+
+sp_archive_render(Change, Mode, Results, Lines) :-
+    (   Mode == apply
+    ->  Verb = "apply"
+    ;   Verb = "plan (read-only)"
+    ),
+    format(string(Header), "spec archive [~w]: ~w", [Verb, Change]),
+    findall(ResultLine, (member(Result, Results), sp_archive_result_line(Result, ResultLine)), ResultLines),
+    (   ResultLines == []
+    ->  Body = ["  no delta files found"]
+    ;   Body = ResultLines
+    ),
+    append([Header, ""], Body, Lines).
+
+%% ---------------------------------------------------------------------------
+%% Tasks and scenario coverage (phase 3)
+%%
+%% tasks.dml holds `plan_task/2` facts. The functor is deliberately not
+%% `task/2`, which collides with DML's built-in task/N predicate and makes the
+%% term un-unifiable. Completion state uses `plan_task_status/2`.
+%% ---------------------------------------------------------------------------
+
+sp_read_terms(Path, Terms) :-
+    (   catch(open(Path, read, Stream), _, fail)
+    ->  sp_read_terms_loop(Stream, Terms),
+        close(Stream)
+    ;   Terms = []
+    ).
+
+sp_read_terms_loop(Stream, Terms) :-
+    catch(read(Stream, Term), _, Term = end_of_file),
+    (   Term == end_of_file
+    ->  Terms = []
+    ;   Terms = [Term|Rest],
+        sp_read_terms_loop(Stream, Rest)
+    ).
+
+sp_tasks(ChangeDir, Tasks) :-
+    atomic_list_concat([ChangeDir, "/tasks.dml"], Path),
+    sp_read_terms(Path, Terms),
+    findall(plan_task(Id, Props), (
+        member(Term, Terms),
+        Term = plan_task(Id, Props),
+        is_dict(Props)
+    ), Tasks).
+
+sp_task_satisfies(Props, Ids) :- catch(get_dict(satisfies, Props, Ids), _, Ids = []).
+sp_task_checks(Props, Checks) :- catch(get_dict(checks, Props, Checks), _, Checks = []).
+
+%% Slug and scenario ids: "User toggles dark mode" -> "user-toggles-dark-mode".
+sp_char_alnum(C) :- char_code(C, Code), Code >= 97, Code =< 122, !.
+sp_char_alnum(C) :- char_code(C, Code), Code >= 48, Code =< 57, !.
+
+sp_slug_chars([], []).
+sp_slug_chars([C|Chars], [Mapped|Rest]) :-
+    (   sp_char_alnum(C)
+    ->  Mapped = C
+    ;   Mapped = "-"
+    ),
+    sp_slug_chars(Chars, Rest).
+
+sp_keep_nonempty([], []).
+sp_keep_nonempty([Part|Parts], Out) :-
+    (   Part == ""
+    ->  Out = Rest
+    ;   Out = [Part|Rest]
+    ),
+    sp_keep_nonempty(Parts, Rest).
+
+sp_slug(Text, Slug) :-
+    string_lower(Text, Lower),
+    string_chars(Lower, Chars),
+    sp_slug_chars(Chars, Mapped),
+    atomics_to_string(Mapped, Raw),
+    split_string(Raw, "-", "-", Parts0),
+    sp_keep_nonempty(Parts0, Parts),
+    atomics_to_string(Parts, "-", Slug).
+
+sp_scenario_id(Capability, Name, Id) :-
+    sp_slug(Name, Slug),
+    atomics_to_string([Capability, "#", Slug], Id).
+
+sp_delta_scenarios_named(Deltas, Capability, Pairs) :-
+    findall(Id-Name, (
+        member(delta(Op, Reqs), Deltas),
+        ( Op == added ; Op == modified ),
+        member(req(_, _, _, Scenarios), Reqs),
+        member(scenario(Name, _, _), Scenarios),
+        sp_scenario_id(Capability, Name, Id)
+    ), Pairs).
+
+sp_delta_scenario_ids(Deltas, Capability, Ids) :-
+    sp_delta_scenarios_named(Deltas, Capability, Pairs),
+    findall(Id, member(Id-_, Pairs), Ids).
+
+sp_covered(Tasks, Id) :-
+    member(plan_task(_, Props), Tasks),
+    sp_task_satisfies(Props, Ids),
+    memberchk(Id, Ids).
+
+%% Scenarios, tasks, uncovered scenarios, tasks without checks, orphan satisfies.
+sp_coverage(ChangeDir, Scenarios, Tasks, Uncovered, NoCheck, Orphan) :-
+    sp_tasks(ChangeDir, Tasks),
+    sp_change_delta_files(ChangeDir, DeltaFiles),
+    findall(Id, (
+        member(File, DeltaFiles),
+        sp_capability_id(File, Capability),
+        read_file_to_string(File, Text, []),
+        sp_parse_delta_full(Text, _, Deltas),
+        sp_delta_scenario_ids(Deltas, Capability, Ids),
+        member(Id, Ids)
+    ), RawScenarios),
+    sort(RawScenarios, Scenarios),
+    findall(Id, (member(Id, Scenarios), \+ sp_covered(Tasks, Id)), Uncovered0),
+    sort(Uncovered0, Uncovered),
+    findall(TaskId, (
+        member(plan_task(TaskId, Props), Tasks),
+        sp_task_checks(Props, Checks),
+        Checks == []
+    ), NoCheck0),
+    sort(NoCheck0, NoCheck),
+    findall(Sat, (
+        member(plan_task(_, Props), Tasks),
+        sp_task_satisfies(Props, Sats),
+        member(Sat, Sats),
+        \+ memberchk(Sat, Scenarios)
+    ), Orphan0),
+    sort(Orphan0, Orphan).
+
+sp_coverage_line(ChangeDir, Line) :-
+    file_base_name(ChangeDir, Name),
+    sp_coverage(ChangeDir, Scenarios, Tasks, Uncovered, NoCheck, _),
+    length(Scenarios, ScenarioCount),
+    length(Tasks, TaskCount),
+    length(Uncovered, UncoveredCount),
+    length(NoCheck, NoCheckCount),
+    Covered is ScenarioCount - UncoveredCount,
+    (   TaskCount =:= 0
+    ->  format(string(Line), "coverage ~w: no tasks.dml yet (~w scenarios)", [Name, ScenarioCount])
+    ;   format(string(Line), "coverage ~w: ~w/~w scenarios covered, ~w tasks, ~w without checks",
+               [Name, Covered, ScenarioCount, TaskCount, NoCheckCount])
+    ).
+
+sp_coverage_errors(ChangeDir, Errors) :-
+    sp_tasks(ChangeDir, Tasks),
+    (   Tasks == []
+    ->  Errors = []
+    ;   sp_coverage(ChangeDir, _, _, Uncovered, NoCheck, _),
+        atomic_list_concat([ChangeDir, "/tasks.dml"], File),
+        findall(error(File, 0, Message), (
+            member(Id, Uncovered),
+            format(string(Message), "no task satisfies scenario ~w", [Id])
+        ), E1),
+        findall(error(File, 0, Message), (
+            member(Id, NoCheck),
+            format(string(Message), "task ~w declares no verification check", [Id])
+        ), E2),
+        append(E1, E2, Errors)
+    ).
+
+%% Draft tasks.dml scaffold (read-only).
+sp_scaffold_tasks([], _, []).
+sp_scaffold_tasks([Id-Name|Rest], N, Lines) :-
+    format(string(TaskId), "1.~w", [N]),
+    format(string(Do), "Implement: ~w", [Name]),
+    format(string(Expected), "The scenario ~w holds.", [Id]),
+    format(string(Block),
+        "plan_task(\"~w\", task{\\n    executor:  pi,\\n    do:        \"~w\",\\n    tools:     [\"read\", \"edit\"],\\n    expected:  \"~w\",\\n    satisfies: [\"~w\"],\\n    checks:    []\\n}).",
+        [TaskId, Do, Expected, Id]),
+    N1 is N + 1,
+    sp_scaffold_tasks(Rest, N1, RestLines),
+    Lines = [Block, ""|RestLines].
+
+sp_scaffold_statuses([], _, []).
+sp_scaffold_statuses([_|Rest], N, Lines) :-
+    format(string(TaskId), "1.~w", [N]),
+    format(string(Line), "plan_task_status(\"~w\", pending).", [TaskId]),
+    N1 is N + 1,
+    sp_scaffold_statuses(Rest, N1, RestLines),
+    Lines = [Line|RestLines].
+
+sp_scaffold(Change, Draft) :-
+    atomic_list_concat([".pi/deepclause/changes/", Change], ChangeDir),
+    sp_change_delta_files(ChangeDir, DeltaFiles),
+    findall(Id-Name, (
+        member(File, DeltaFiles),
+        sp_capability_id(File, Capability),
+        read_file_to_string(File, Text, []),
+        sp_parse_delta_full(Text, _, Deltas),
+        sp_delta_scenarios_named(Deltas, Capability, Pairs),
+        member(Id-Name, Pairs)
+    ), Pairs),
+    sp_scaffold_tasks(Pairs, 1, TaskLines),
+    sp_scaffold_statuses(Pairs, 1, StatusLines),
+    format(string(Header), "% tasks.dml — draft scaffold for change ~w", [Change]),
+    append([
+        Header,
+        "% Fill in executor, tools, expected and checks, then run /dc-check.",
+        ""
+    ], TaskLines, A),
+    append(A, ["", "% --- execution state (managed by apply.dml; do not edit by hand) ---"], B),
+    append(B, StatusLines, All),
+    atomics_to_string(All, "\n", Draft0),
+    string_concat(Draft0, "\n", Draft).
+
+%% ---------------------------------------------------------------------------
+%% Task status: read and rewrite the managed block in tasks.dml
+%% ---------------------------------------------------------------------------
+
+sp_task_statuses(ChangeDir, Statuses) :-
+    atomic_list_concat([ChangeDir, "/tasks.dml"], Path),
+    sp_read_terms(Path, Terms),
+    findall(plan_task_status(Id, Status), (
+        member(Term, Terms),
+        Term = plan_task_status(Id, Status)
+    ), Statuses).
+
+sp_set_status([], Id, Status, [plan_task_status(Id, Status)]).
+sp_set_status([plan_task_status(Id, _)|Rest], Id, Status, [plan_task_status(Id, Status)|Rest]) :- !.
+sp_set_status([Other|Rest], Id, Status, [Other|Out]) :- sp_set_status(Rest, Id, Status, Out).
+
+sp_status_done(Statuses, Id) :- memberchk(plan_task_status(Id, done(_)), Statuses).
+
+sp_count_repairs(Statuses, Count) :-
+    findall(1, (member(plan_task_status(_, done(N)), Statuses), N > 1), Repairs),
+    length(Repairs, Count).
+
+sp_take_head([], [], no).
+sp_take_head([Line|_], [Line], yes) :- sub_string(Line, _, _, _, "execution state"), !.
+sp_take_head([Line|Rest], [Line|Head], Found) :- sp_take_head(Rest, Head, Found).
+
+sp_split_managed(Text, Head) :-
+    split_string(Text, "\n", "", Lines),
+    sp_take_head(Lines, Head0, Found),
+    (   Found == yes
+    ->  Head = Head0
+    ;   append(Head0, ["", "% --- execution state (managed by apply.dml; do not edit by hand) ---"], Head)
+    ).
+
+sp_write_statuses(TasksPath, Statuses) :-
+    read_file_to_string(TasksPath, Text, []),
+    sp_split_managed(Text, Head),
+    findall(Line, (
+        member(plan_task_status(Id, Status), Statuses),
+        format(string(Line), "plan_task_status(~q, ~q).", [Id, Status])
+    ), StatusLines),
+    append(Head, StatusLines, Body),
+    append(Body, [""], All),
+    atomics_to_string(All, "\n", Out),
+    sp_write_file(TasksPath, Out).