Skip to content

feat(performance): add governed performance goal-plan evidence - #92

Open
seonghobae wants to merge 5 commits into
developfrom
feat/performance-goal-plan-evidence
Open

feat(performance): add governed performance goal-plan evidence#92
seonghobae wants to merge 5 commits into
developfrom
feat/performance-goal-plan-evidence

Conversation

@seonghobae

@seonghobae seonghobae commented Aug 23, 2026

Copy link
Copy Markdown
Contributor

Exact-current-head state

Current exact head: 141574958df2238d107121138c1ffb5f854126cc.
Fresh live base: develop@9e3e4847510e1e612b48474ba42b177b8ed824df.

Buyer-visible gap closed

Protected develop has performance cycles and criterion observations, but no governed performance-goal plan activation evidence. This PR adds a value-minimized, transport-neutral goal-plan boundary without writing another CWL repository and without granting autonomous rating or employment-decision authority.

The packet binds tenant, Employment, Job, performance cycle, goal-set SHA-256, measurement-definition SHA-256, reviewed feedback cadence, distinct requester/reviewer, evidence version, and system-recorded time. Goal text, ratings, assessment scores, compensation values, and employment decisions remain outside durable governance evidence. The packet is fixed to requires_human_review, not_authorized_for_performance_rating, and not_authorized_for_employment_decision.

RED → implementation evidence

  1. Initial RED b661446e30336a1f49371d5a7393e90e4ff64004
    • Performance Goal Plan Quality 32609564146, job 97120230551, checked out the exact SHA and failed with ModuleNotFoundError because the production boundary was deliberately absent.
  2. Root implementation 70c38abea15a7dae4401b6d35b951832a6a541c5
    • Added the governed packet, exact runtime-primitive validation, ownership-aware UUID rules, redacted representation, live reference binding, creation-digest tamper evidence, ADR 0092, traceability, buyer docs, and research doctoring.
    • Focused run 32609619875 passed all 36 functional tests but correctly failed the exact coverage gate at 98%; this was non-passing evidence.
  3. Coverage-strengthening f75aee51f1129c66c083411b853d8366c9cda58d
    • Added realistic exact-runtime tenant and alternate valid review-state coverage. Performance Goal Plan Quality 32609675570 reached exact 100% statement/branch coverage.

Review-driven quality-trigger repair

Fresh Devin review found a real repository-quality defect: the dedicated workflow watched the package, doctoring, and traceability paths but omitted its own governed ADR docs/adr/0092-governed-performance-goal-plan.md. An ADR-only edit could therefore avoid Performance Goal Plan Quality.

  • Regression commit 6c152093c891dbede556cd51307606d810164993 adds test_quality_workflow_covers_governed_adr(). Its hosted runs materialized but were cancelled by the immediately following repair through the workflow concurrency policy; no cancelled result is claimed as passing or RED execution evidence.
  • Root repair/current head 141574958df2238d107121138c1ffb5f854126cc adds the ADR path to the workflow trigger.
  • Performance Goal Plan Quality 32611929753, job 97126268994, checked out the exact current head and ran 37 tests from the hash-bound installed wheel with owned production at 155 statements / 46 branches = exact 100% statement and branch coverage; clean checkout passed.
  • The verified workflow-path review thread is resolved. The two remaining review observations are informational: unsupported copied/unpickled process-local evidence does not acquire issuance authority, and live plan references intentionally fail closed on conflicting reissuance.

Exact-head hosted gates

Every applicable current-head workflow is terminal GREEN:

  • Performance Goal Plan Quality 32611929753
  • Foundation CI 32611929746
  • SAST Semgrep 32611929743
  • Security Scan 32611929767
  • Recovery Rehearsal Quality 32611929785

Merge policy

This PR is ready for qualifying independent review, not merge-authorized. No qualifying independent non-author APPROVE exists. Orgmetra issue #89 also remains open because GitHub reports develop as protected: true while effective required-check enforcement is disabled/empty. Keep unmerged until independent approval and enforceable protected-branch policy are both present on fresh state. Immediately before any merge, refetch exact head, live base, rules/protection, reviews, threads, and checks and use expected-head protection. Do not self-approve, bypass protection, or transfer predecessor evidence.

Summary by CodeRabbit

  • 신규 기능

    • 검토된 성과 목표 계획의 활성화 증거 패킷을 생성하고 검증하는 기능을 추가했습니다.
    • 목표·측정 정의의 출처 다이제스트, 피드백 주기, 요청자와 인간 검토자 정보를 지원합니다.
    • 패킷의 무결성 검증과 변경·중복 활성화 감지를 제공합니다.
  • 문서

    • 사용 방법, 거버넌스 규칙, 연구 근거 및 요구사항 추적 문서를 추가했습니다.
  • 품질

    • 패키지 빌드, 의존성, 커버리지 및 저장소 품질을 자동 검증합니다.

@coderabbitai

coderabbitai Bot commented Aug 23, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7bb17389-4771-427e-8b26-7db8f087a6e8

📥 Commits

Reviewing files that changed from the base of the PR and between 9e3e484 and 1415749.

📒 Files selected for processing (11)
  • .github/workflows/performance-goal-plan-quality.yml
  • docs/adr/0092-governed-performance-goal-plan.md
  • docs/doctoring/performance-goal-plan-references.md
  • docs/traceability/performance-goal-plan.md
  • packages/performance-goal-plan/CHANGELOG.md
  • packages/performance-goal-plan/README.md
  • packages/performance-goal-plan/pyproject.toml
  • packages/performance-goal-plan/src/orgmetra_performance_goal_plan/__init__.py
  • packages/performance-goal-plan/src/orgmetra_performance_goal_plan/plan.py
  • packages/performance-goal-plan/tests/test_plan.py
  • packages/performance-goal-plan/tests/test_repository_contract.py

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


📝 Walkthrough

Walkthrough

성과 목표 계획 활성화 증거를 표현하는 Python 패키지를 추가했다. 패킷은 검토 상태, HR 참조, 출처 다이제스트와 피드백 주기를 검증한다. 정규 JSON, SHA-256 무결성, 재발행 충돌 방지와 전용 품질 검증 워크플로를 포함한다.

Changes

성과 목표 계획 활성화 증거

Layer / File(s) Summary
거버넌스 계약과 증거 범위
docs/adr/0092-governed-performance-goal-plan.md, docs/traceability/performance-goal-plan.md, docs/doctoring/performance-goal-plan-references.md, packages/performance-goal-plan/README.md, packages/performance-goal-plan/CHANGELOG.md
패킷의 포함·제외 데이터, 인간 검토 상태, 출처 다이제스트, 비권위 상태와 고영향 고용 결정 제한을 문서화했다.
패킷 API와 무결성 검증
packages/performance-goal-plan/src/orgmetra_performance_goal_plan/plan.py, packages/performance-goal-plan/src/orgmetra_performance_goal_plan/__init__.py, packages/performance-goal-plan/tests/test_plan.py
PerformanceGoalPlanPacketbuild_performance_goal_plan_packet을 추가했다. 입력 검증, UTC 정규화, 불변성, canonical JSON, SHA-256 다이제스트와 재발행 충돌 검사를 구현했다. 계약 테스트는 유효 입력, 잘못된 입력, 사후 변조와 민감 정보 제외를 검증한다.
패키지 빌드와 품질 검증
packages/performance-goal-plan/pyproject.toml, .github/workflows/performance-goal-plan-quality.yml, packages/performance-goal-plan/tests/test_repository_contract.py
Python 3.14 패키지 빌드 설정과 테스트 의존성을 추가했다. GitHub Actions는 고정 커밋 체크아웃, 해시 검증 의존성 설치, wheel 빌드·설치, pip check, 100% 브랜치 커버리지와 깨끗한 작업 트리를 검증한다.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: 🟡 Moderate · up to 14157

This change adds a bounded performance-goal evidence record without granting rating or employment-decision authority, and the supplied checks show no actionable implementation defect. It should not merge yet because the required independent approval and effective protected-branch enforcement are not currently in place.

Sequence Diagram(s)

sequenceDiagram
  participant 호출자
  participant build_performance_goal_plan_packet
  participant PerformanceGoalPlanPacket
  participant SHA-256
  호출자->>build_performance_goal_plan_packet: 증거 필드 전달
  build_performance_goal_plan_packet->>PerformanceGoalPlanPacket: 검증된 패킷 생성
  PerformanceGoalPlanPacket->>SHA-256: canonical_json 해시 요청
  SHA-256-->>PerformanceGoalPlanPacket: 다이제스트 반환
  PerformanceGoalPlanPacket-->>호출자: 정규화된 패킷 반환
Loading
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.
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.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed 제목은 거버넌스 적용 성과 목표 계획 증거 패킷 추가라는 주요 변경을 명확하고 간결하게 설명합니다.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/performance-goal-plan-evidence

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

@seonghobae
seonghobae marked this pull request as ready for review August 23, 2026 01:11

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 3 potential issues.

Open in Devin Review

Comment thread .github/workflows/performance-goal-plan-quality.yml
Comment on lines +262 to +270
def canonical_json(self) -> str:
"""Return one verified snapshot of deterministic canonical audit evidence."""
payload_json = _canonical_payload_json(_payload(self))
current_digest = sha256(payload_json.encode("utf-8")).hexdigest()
with _REGISTRY_LOCK:
creation_digest = _CREATION_DIGESTS[self]
if current_digest != creation_digest:
raise ValueError("performance goal-plan evidence changed after issuance")
return payload_json

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 Info: Unpickled packet breaks canonical export

canonical_json reads _CREATION_DIGESTS[self], populated only by __post_init__. A packet rebuilt without it (unpickling a slotted frozen dataclass, copy.copy) is unregistered, so export raises KeyError rather than the intended ValueError. No caller exercises this today.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Comment on lines +254 to +260
key = (self.tenant_record_id, self.performance_goal_plan_reference)
with _REGISTRY_LOCK:
existing = _LIVE_REFERENCES.get(key)
if existing is not None and _CREATION_DIGESTS.get(existing) != creation_digest:
raise ValueError("performance goal-plan reference is bound to different live evidence")
_CREATION_DIGESTS[self] = creation_digest
_LIVE_REFERENCES[key] = self

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 Info: Re-issuing evidence for a live plan reference fails closed

The registry keys on (tenant, plan reference) and its digest includes generated_at. Regenerating evidence for the same plan reference while an earlier packet is still reachable raises 'bound to different live evidence'. This is intended per ADR 0092, so callers must treat the plan reference as a per-evidence key, not a reused plan identifier.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

@seonghobae
seonghobae marked this pull request as draft August 23, 2026 02:04
@seonghobae
seonghobae marked this pull request as ready for review August 23, 2026 02:06

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 1 new potential issue.

Open in Devin Review

Comment on lines +255 to +260
with _REGISTRY_LOCK:
existing = _LIVE_REFERENCES.get(key)
if existing is not None and _CREATION_DIGESTS.get(existing) != creation_digest:
raise ValueError("performance goal-plan reference is bound to different live evidence")
_CREATION_DIGESTS[self] = creation_digest
_LIVE_REFERENCES[key] = self

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 Info: Reissuance guard scoped to object liveness

_LIVE_REFERENCES and _CREATION_DIGESTS are weak. After the original packet is garbage collected, a new packet reusing the same tenant/plan reference with different content is accepted, since existing resolves to None. The conflict guard holds only while the original is alive.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

@seonghobae

Copy link
Copy Markdown
Contributor Author

@opencode-agent Please review the current unchanged head against protected develop. Local exact-head verification: all owned package suites pass at 100% statement/branch coverage.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant