Docs: Introduce CI-focused guidance ExecPlan (3.13.3)

[leynos]

Summary

Adds a new ExecPlan document for CI-focused guidance (3.13.3) to plan and document user-facing guidance for continuous integration workflows. The document outlines constraints, risks, plan milestones, and acceptance criteria, and ties into existing docs and tests.

Changes

• Added new file: docs/execplans/3-13-3-provide-ci-focused-guidance.md
  • Contains Purpose, Constraints, Tolerances, Risks, Progress, Surprises & Discoveries, Decision Log, Outcomes & Retrospective, Plan of work (Stage A–E), Validation & Acceptance, and Context sections.
  • Describes how CI-focused guidance will be integrated into docs/users-guide.md, docs/netsuke-design.md, tests, and the roadmap.

Rationale

• Establishes a cohesive, tested, user-facing CI guidance narrative for Netsuke automation features (JSON diagnostics, OrthoConfig layering, progress suppression, verbose timing, etc.).
• Enables traceable planning and validation across documentation and test artifacts, reducing ambiguity when implementing CI workflows.

Plan of work (Stage A–E)

• Stage A: Audit contract and settle wording
  • Confirm exact automation contract for quiet/verbose/JSON mode.
  • Decide documentation placement (likely a CI subsection in docs/users-guide.md).
  • Capture final design decisions in docs/netsuke-design.md.
• Stage B: Write CI-focused user guidance
  • Add a dedicated CI subsection to docs/users-guide.md with:
    • Quiet baseline examples (progress suppression, spinner_mode disabled).
    • Verbose troubleshooting example.
    • Structured diagnostics example (JSON mode).
    • Consuming JSON diagnostics in automation (stable fields).
    • OrthoConfig layering (CLI/env/config-file).
• Stage C: Add rstest-bdd behavioural coverage
  • Create tests/features/ci_guidance.feature (or extend existing) covering happy/unhappy/edge paths.
  • Reuse existing steps where feasible.
• Stage D: Add focused rstest coverage
  • Implement tests for JSON diagnostics, OrthoConfig layering, quiet/verbose interaction, and invalid configs (rstest-based).
• Stage E: Design/doc roadmap validation
  • Update docs/netsuke-design.md with final decisions.
  • Mark 3.13.3 done in docs/roadmap.md after gates pass.
  • Run full gate suite (fmt, check-fmt, lint, test, markdownlint, nixie).

Validation and acceptance

The feature is complete when all of the following are true:

1. docs/users-guide.md includes a dedicated CI-focused subsection with:
   • JSON-diagnostics consumption examples,
   • quiet/verbose automation guidance,
   • OrthoConfig layering examples for CLI, env, and config-file use.
2. docs/netsuke-design.md records the final terminology/behaviour decision.
3. rstest-bdd scenarios prove the documented CI workflows end to end.
4. rstest coverage proves the JSON fields and precedence combinations used in the docs.
5. Gate suite passes: make fmt, make check-fmt, make lint, make test, make markdownlint, make nixie.
6. docs/roadmap.md marks 3.13.3 done.

How to review

• Ensure the ExecPlan aligns with existing runtime behavior (JSON diagnostics, OrthoConfig, progress suppression).
• Verify cross-links to docs sections (users-guide, netsuke-design, ortho-config users guide).
• Check that the Stage A–E plans are coherent and actionable for implementation.
• Confirm acceptance criteria cover both documentation and testing aspects.

Notes

• This PR is documentation-oriented and does not modify runtime code paths.
• Future commits should flesh out Stage B–D with actual content and tests, per the plan.

◳ Generated by DevBoxer ◰

---

ℹ️ Tag @devboxerhub to ask questions and address PR feedback

📎 Task: https://www.devboxer.com/task/4915cc74-5b2c-4a90-91fe-802652fae511

Summary by Sourcery

Documentation:

• Add a new ExecPlan document outlining CI-focused guidance work for Netsuke, including planned documentation updates, testing coverage, and acceptance criteria.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 7eb42a33-0783-41a4-8e13-95448f64c3c2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature-ci-guidance-docs-e11hb3

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sourcery-ai]

Reviewer's Guide

Adds a new ExecPlan document that plans CI-focused user guidance, test coverage, and documentation updates for Netsuke roadmap item 3.13.3, without touching runtime code.

Flow diagram for ExecPlan stages A–E for CI-focused guidance

flowchart TD
  Start([Start roadmap item 3_13_3])
  A[Stage_A
Audit_contract_and_settle_wording]
  B[Stage_B
Write_CI_focused_user_guidance]
  C[Stage_C
Add_rstest_bdd_behavioural_coverage]
  D[Stage_D
Add_focused_rstest_coverage]
  E[Stage_E
Design_doc_roadmap_and_validation]
  Done([Feature_complete_per_validation_criteria])

  Start --> A
  A -->|Contract_fixed_for_quiet_verbose_JSON
Docs_targets_identified| B
  B -->|CI_subsection_added_to_docs_users_guide_md| C
  C -->|CI_workflows_covered_end_to_end| D
  D -->|JSON_fields_and_precedence_covered| E
  E -->|Docs_updated_roadmap_marked_done_gates_pass| Done

  subgraph Docs
    UG[docs_users_guide_md
CI_subsection]
    ND[docs_netsuke_design_md
terminology_behaviour]
    RC[docs_roadmap_md
item_3_13_3]
  end

  subgraph Tests
    BDD[tests_features_ci_guidance_feature
rstest_bdd]
    RT[tests_ci_guidance_tests_rs_or_advanced_usage_tests_rs
rstest]
  end

  A --> ND
  A --> UG
  B --> UG
  C --> BDD
  D --> RT
  E --> ND
  E --> RC

  subgraph Gates
    FMT[make_fmt]
    CFMT[make_check_fmt]
    LINT[make_lint]
    TEST[make_test]
    MDL[make_markdownlint]
    NIX[make_nixie]
  end

  E --> FMT & CFMT & LINT & TEST & MDL & NIX
  FMT --> Done
  CFMT --> Done
  LINT --> Done
  TEST --> Done
  MDL --> Done
  NIX --> Done

Loading

File-Level Changes

Change	Details	Files
Introduce an ExecPlan document that defines purpose, constraints, risks, staged plan, and acceptance criteria for CI-focused guidance around Netsuke automation features.	Document the current and intended behaviour of JSON diagnostics, OrthoConfig layering, progress suppression, and verbose output for CI use cases. Specify constraints, tolerances, and risks, particularly around the lack of a dedicated quiet flag and JSON-plus-verbose interactions. Lay out a Stage A–E implementation plan covering auditing behaviour, writing CI docs, adding rstest-bdd scenarios, adding rstest coverage, and updating design docs and roadmap. Define validation and acceptance criteria tying together user docs, design docs, tests, and gate runs. Record initial progress, discoveries, and design decisions about interpreting roadmap terminology and reusing existing docs/tests.	docs/execplans/3-13-3-provide-ci-focused-guidance.md

---

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.