Skip to content

Render provenance into local PRD and design artifacts (#117) - #118

Open
tchughesiv wants to merge 2 commits into
flightctl:mainfrom
tchughesiv:117-render-local-provenance
Open

Render provenance into local PRD and design artifacts (#117)#118
tchughesiv wants to merge 2 commits into
flightctl:mainfrom
tchughesiv:117-render-local-provenance

Conversation

@tchughesiv

@tchughesiv tchughesiv commented Sep 9, 2026 •
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown
Contributor

Render provenance into local PRD and design artifacts

Issue: #117
Type: GitHub issue

Summary

Render provenance directly into local PRD and design artifacts immediately after
draft, revise, and respond phases capture a provenance event. This makes the
artifact independently readable before any optional documentation-repository
sync while retaining the existing published-copy rendering behavior.

Changes

  • Allow the shared provenance-footer recipe to target local artifacts as well
    as documentation-repository files.
  • Invoke that recipe after capture in all PRD and design draft, revise, and
    respond phase paths, before optional documentation sync.
  • Bump the PRD and design workflow minor versions for the behavioral change.
  • Add regression coverage for local rendering, manual-copy persistence, and
    accumulated-event rerendering.

Testing

  • python3 -m unittest discover -s _shared/scripts -p 'test_*.py' -v
  • python3 -m unittest discover -s triage/scripts -p 'test_*.py' -v
  • python3 -m unittest discover -s skills/report-bug/scripts -p 'test_*.py' -v
  • bash .github/scripts/test-install.sh
  • python3 skill-reviewer/scripts/pre-review-checks.py --all --repo-root .
  • git diff --check origin/main...HEAD

The repository version-validation script requires GNU head; Linux CI is the
authoritative environment for that check. Markdown linting is also CI-only.

Acceptance Criteria

  • Draft-only PRD and design artifacts contain both a readable footer and a
    machine-readable provenance marker.
  • Revise and respond events update accumulated local provenance history.
  • Published-copy rendering remains idempotent.
  • Manually copied local artifacts retain provenance without a documentation
    PR.
  • PRD and design workflow versions receive minor bumps.

Summary

  • PRD and design packages: Render provenance footers into local artifacts during draft, revise, and respond workflows. Preserve the footer when users copy artifacts manually. Replace the footer when new provenance events are recorded.
  • Shared resources: Extend _shared/recipes/render-provenance-footer.md to support local artifacts and documentation-repository copies. Retain published-copy behavior.
  • Cross-package conventions: Bump PRD and design skill versions to 0.10.0. Add regression tests for local rendering and accumulated provenance events.

@coderabbitai

coderabbitai Bot commented Sep 9, 2026 •
edited
Loading

Copy link
Copy Markdown

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: cbd6e7b2-b924-40b9-9324-cc3878155b69

📥 Commits

Reviewing files that changed from the base of the PR and between f121df6 and 5a4e5ae.

📒 Files selected for processing (10)
  • _shared/recipes/render-provenance-footer.md
  • _shared/scripts/test_provenance.py
  • design/SKILL.md
  • design/skills/draft.md
  • design/skills/respond.md
  • design/skills/revise.md
  • prd/SKILL.md
  • prd/skills/draft.md
  • prd/skills/respond.md
  • prd/skills/revise.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

📜 Recent review details
🧰 Additional context used
📓 Path-based instructions (6)
Injection prevention (prodsec-skills): SQL: parameterized queries only; no string concatenation Command: no shell=True, os.system, or backtick exec with user input LDAP/XPath: escape special characters in filters Path traversal: canonicaliz...

⚙️ CodeRabbit configuration file

Files:

  • _shared/scripts/test_provenance.py
Workflow script review (ai-workflows conventions): Scripts must be invoked by skill files, not by users directly Must work when the workflow is installed via symlink Exit code conventions must be documented in docstring: Report scripts: 0 =...

⚙️ CodeRabbit configuration file

Files:

  • _shared/scripts/test_provenance.py
Workflow skill review (ai-workflows conventions): First classify the file as a phase implementation, controller, dispatcher, completion guide, or other support file.

⚙️ CodeRabbit configuration file

Files:

  • design/skills/revise.md
  • design/skills/respond.md
  • prd/skills/draft.md
  • prd/skills/respond.md
  • design/skills/draft.md
  • prd/skills/revise.md
SKILL.md review (ai-workflows conventions): YAML frontmatter required: opening/closing --- delimiters Required fields: name (lowercase, hyphens only, max 64 chars), description (third person, includes trigger terms and activated-by commands...

⚙️ CodeRabbit configuration file

Files:

  • prd/SKILL.md
  • design/SKILL.md
Shared resource review (ai-workflows conventions): Shared resources may be referenced by multiple packages — changes here have cross-cutting impact.

⚙️ CodeRabbit configuration file

Files:

  • _shared/recipes/render-provenance-footer.md
  • _shared/scripts/test_provenance.py
Cross-package consistency (ai-workflows conventions): Package-resource references that an agent follows must be relative for symlink compatibility.

⚙️ CodeRabbit configuration file

Files:

  • prd/SKILL.md
  • design/skills/revise.md
  • design/skills/respond.md
  • prd/skills/draft.md
  • prd/skills/respond.md
  • _shared/recipes/render-provenance-footer.md
  • design/skills/draft.md
  • prd/skills/revise.md
  • design/SKILL.md
🪛 ast-grep (0.45.3)
_shared/scripts/test_provenance.py

[info] 718-733: use jsonify instead of json.dumps for JSON output
Context: json.dumps(
{
"workflow": workflow,
"events": [
{
"phase": "draft",
"authoring_mode": "skill",
"workflow_version": "0.10.0",
"ai_workflows": "workflow-hash",
"source_repo": "workspace-hash",
"source_repo_branch": "main",
}
],
"drift": {"context_changed": False},
}
)
Note: [CWE-116] Improper Encoding or Escaping of Output.

(use-jsonify)

[info] 793-799: use jsonify instead of json.dumps for JSON output
Context: json.dumps(
{
"workflow": workflow,
"events": [draft_event],
"drift": {"context_changed": False},
}
)
Note: [CWE-116] Improper Encoding or Escaping of Output.

(use-jsonify)

[info] 812-818: use jsonify instead of json.dumps for JSON output
Context: json.dumps(
{
"workflow": workflow,
"events": updated_events,
"drift": {"context_changed": False},
}
)
Note: [CWE-116] Improper Encoding or Escaping of Output.

(use-jsonify)

🔇 Additional comments (10)
_shared/recipes/render-provenance-footer.md (1)

3-3: LGTM!

Also applies to: 7-8, 16-16, 21-22

design/SKILL.md (1)

3-3: LGTM!

design/skills/draft.md (1)

218-221: LGTM!

design/skills/respond.md (1)

252-255: LGTM!

_shared/scripts/test_provenance.py (1)

9-9: LGTM!

Also applies to: 658-702, 704-756, 758-838

design/skills/revise.md (1)

212-215: LGTM!

prd/SKILL.md (1)

3-3: LGTM!

prd/skills/draft.md (1)

207-214: LGTM!

prd/skills/respond.md (1)

191-194: LGTM!

prd/skills/revise.md (1)

81-84: LGTM!

Walkthrough

The shared provenance recipe now supports local artifacts and docs-repository copies. PRD and design workflows render footers on source artifacts before synchronization. Tests cover ordering, copying, and footer replacement.

Changes

Provenance footer workflow

Layer / File(s) Summary
Recipe contract
_shared/recipes/render-provenance-footer.md		 The recipe accepts local artifact or docs-repository paths and keeps rendering before git add.
Skill workflow integration
design/SKILL.md, design/skills/*, prd/SKILL.md, prd/skills/*		 PRD and design workflows render provenance footers on source artifacts after provenance capture. Skill versions are updated.
Local rendering validation
_shared/scripts/test_provenance.py		 Tests verify execution order, footer persistence after copying, and replacement after session updates.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Merge Risk: ⚪ Minimal · up to 5a4e5

PRD and design artifacts now retain updated provenance footers before documentation copies are synchronized. The change is covered for ordering, copy persistence, and footer replacement, with no current merge-blocking risk identified.

Suggested labels: workflow-structure, shared-resources, scripts

Suggested reviewers: adalton, avishayt

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error, 1 warning)

Check name Status Explanation Resolution
Ai-Attribution ❌ Error The PR context states that CodeRabbit was used for the review. The two PR commits (c4e949d and 5a4e5ae) contain no Assisted-by, Generated-by, or Made-with trailer. They also contain no `Co-A… Add an accepted attribution trailer, such as Assisted-by: CodeRabbit, to the commits that used the AI tool. Do not use Co-Authored-By for the AI tool.
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 1 files. (9 skipped: 9 … Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (10 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly identifies the main change: rendering provenance into local PRD and design artifacts. It is concise and specific.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
No-Absolute-Paths-In-Skills ✅ Passed PASS. The changed workflow Markdown files add only relative links such as ../../_shared/... and relative artifact references under .artifacts/.... They do not add literal /home/, /Users/, `/tm…
Skill-Md-Under-30-Lines ✅ Passed PASS. The PR changes two SKILL.md files: design/SKILL.md has 29 lines and prd/SKILL.md has 26 lines, including frontmatter. Both are under the 30-line limit. The diff only changes workflow version val…
Command-Colon-Notation ✅ Passed All 75 top-level */commands/*.md files have YAML name fields with colon notation, and each prefix matches its workflow directory (for example, design:ingest and prd:revise). The pull request c…
No-Orphaned-References ✅ Passed PASS. The pull request adds only valid structural references. Each new ../../_shared/recipes/render-provenance-footer.md reference resolves to the existing shared recipe, and that recipe's `../prove…
No-Content-Duplication ✅ Passed PASS. The PR changes only the version front-matter line in design/SKILL.md and prd/SKILL.md; it adds no instruction prose. The corresponding guidelines.md and skills/controller.md files cont…
Step-Sequencing ✅ Passed PASS. The six changed workflow files are design/skills/{draft,respond,revise}.md and prd/skills/{draft,respond,revise}.md. Their main steps remain sequential: design draft 1–10, design respond 1–7…
Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 1 files. (9 skipped: 9 unsupported.)

Full details: Ai-Attribution

Explanation

The PR context states that CodeRabbit was used for the review. The two PR commits (c4e949d and 5a4e5ae) contain no Assisted-by, Generated-by, or Made-with trailer. They also contain no Co-Authored-By, but they still lack an accepted AI attribution trailer.

  • Fix all pre-merge checks with AI
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Comment @coderabbitai help to get the list of available commands.

@tchughesiv
tchughesiv marked this pull request as ready for review September 9, 2026 19:19
@tchughesiv

tchughesiv commented Sep 9, 2026

Copy link
Copy Markdown
Contributor Author

@coderabbitai full review

@coderabbitai

coderabbitai Bot commented Sep 9, 2026 •
edited
Loading

Copy link
Copy Markdown
✅ Action performed

Full review finished.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@tchughesiv