[SenolIsci]

Adds a Schema Health section to walkthrough.md, rendered only when intermediate/schema_drift.json exists. Shows declared vs used counts, unused concepts/properties with classification and reason, undeclared types, and the prune-schema preview hint. A record whose fingerprint no longer matches the current schema + output counts is shown as stale (counts withheld); unreadable/unverifiable records degrade without raising. Later sections renumber by one only when present.

Also moves the post-prune drift re-record in prune-schema before the output refresh (cli.py, 3 lines) so the regenerated walkthrough is not stale.

🤖 Generated with Claude Code

Summary by Sourcery

Add verified Schema Health reporting to walkthroughs and keep generated drift information current after schema pruning.

New Features:

• Add a conditional Schema Health walkthrough section showing schema usage, unused and undeclared items, and pruning guidance.

Bug Fixes:

• Mark schema drift walkthrough data as stale when the schema, graph counts, or schema locks have changed, while degrading safely for unreadable verification inputs.
• Ensure post-prune drift records are refreshed before walkthrough output is regenerated.

Enhancements:

• Renumber subsequent walkthrough sections dynamically when Schema Health is present and safely quote session names in command hints.

Tests:

• Add coverage for fresh, stale, corrupt, unverifiable, lock-sensitive, and safely quoted Schema Health walkthrough output.

[sourcery-ai]

Reviewer's Guide

The PR adds a resilient, conditionally rendered Schema Health walkthrough section with fingerprint-based freshness checks and coverage for fresh, stale, corrupt, and unverifiable records. It also moves post-prune drift recording ahead of output refresh so regenerated walkthroughs remain consistent with the pruned schema, while renumbering later sections dynamically.

Sequence diagram for freshness verification in Schema Health

sequenceDiagram
    participant W as Walkthrough
    participant D as DriftReport
    participant F as Fingerprint logic
    participant S as schema.json
    participant G as Graph output

    W->>D: model_validate_json()
    D-->>W: report.timestamp and schema_fingerprint
    W->>F: _current_drift_fingerprint()
    F->>S: _load_json()
    F->>G: stream_jsonl(nodes.jsonl)
    F->>G: stream_jsonl(edges.jsonl)
    F-->>W: current fingerprint
    alt fingerprints match
        W->>D: unused_concepts()
        W->>D: unused_properties()
        W-->>W: Render counts, classifications, and reasons
    else fingerprint differs
        W-->>W: Render stale status and withhold counts
    else verification unavailable
        W-->>W: Render unverified warning and figures
    end

Loading

Sequence diagram for consistent post-prune drift recording

sequenceDiagram
    participant User as User
    participant CLI as prune_schema
    participant Drift as _run_drift_analysis
    participant Refresh as _refresh_after_prune
    participant Walkthrough as Walkthrough output

    User->>CLI: prune-schema
    CLI->>Drift: _run_drift_analysis(intermediate_dir, output_dir)
    Drift-->>CLI: schema_drift.json for pruned schema
    CLI->>Refresh: _refresh_after_prune(session_root, intermediate_dir, output_dir)
    Refresh-->>CLI: regenerated outputs and walkthrough
    Walkthrough-->>User: Schema Health matches pruned schema

Loading

Flow diagram for conditional Schema Health walkthrough rendering

flowchart TD
    A[Generate walkthrough] --> B{schema_drift.json exists?}
    B -- No --> C[Render existing sections]
    B -- Yes --> D[Read and validate DriftReport]
    D --> E{Record readable?}
    E -- No --> F[Show unreadable record message]
    E -- Yes --> G[Compute current schema and graph fingerprint]
    G --> H{Fingerprint verifiable and matches?}
    H -- No --> I[Show unverified or stale status]
    H -- Yes --> J[Show declared, used, and unused counts]
    J --> K[Show unused items and undeclared types]
    K --> L{Prunable items exist?}
    L -- Yes --> M[Show prune-schema preview hint]
    L -- No --> N[Finish Schema Health]
    F --> O[Renumber later sections]
    I --> O
    M --> O
    N --> O
    C --> P[Render walkthrough]
    O --> P

Loading

File-Level Changes

Change	Details	Files
Adds a conditional Schema Health walkthrough section that validates drift records against the current schema and exported graph before displaying findings.	Render declared, used, and unused concept/property counts. List unused items with classification and reason, undeclared graph types, and prune preview guidance. Mark verified records stale when the schema or graph fingerprint changes, while degrading safely for corrupt or unverifiable records. Insert the section after Schema Evolution and shift subsequent section numbering only when present.	src/mykg/walkthrough.py tests/test_walkthrough_sections.py
Reorders post-prune drift analysis so regenerated walkthrough output uses a record matching the pruned schema.	Run drift analysis before refreshing generated output. Remove the former post-refresh drift analysis call.	src/mykg/cli.py
Updates the locked dependency metadata.	Refresh the lockfile entry associated with the change.	uv.lock

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="src/mykg/walkthrough.py" line_range="342" />
<code_context>
             "flattened_schema.json refreshed; nodes.json/edge_metadata.json missing, "
             f"so run: {follow_up}"
         )
-    # Re-record so schema_drift.json describes the pruned schema, not the old one.
-    _run_drift_analysis(intermediate_dir, output_dir, quiet=True)
</code_context>
<issue_to_address>
**Suggested command runs attacker code**

When an attacker can place or rename a session directory to a name containing shell syntax and a user copies and runs a suggested command from its walkthrough, the session directory name is interpolated unquoted into shell commands. When a reader copies and runs either hint, shell metacharacters in that name execute as shell syntax, so the user runs attacker-controlled commands.

Shell-quote the session name when building suggested commands, for example with `shlex.quote`.

Also at `src/mykg/walkthrough.py:370`.
</issue_to_address>

Sourcery assessment

Needs a human reviewer. 1 finding to address first, and if the fingerprint or drift summary is wrong, the generated walkthrough and drift record can show inaccurate schema-health figures. Re-running drift analysis and regenerating the walkthrough can repair them; reverting the code would not remove artifacts already generated.

Blocking findings: src/mykg/walkthrough.py:342

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[sourcery-ai]

Sourcery assessment

Approved.

[SenolIsci]

Part of #88 (schema drift detection and pruning tracking issue). Merge order: #83, #84, #85, #86, #87.