%%% 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).