Skip to content

docs: salvage local governance and worklog notes #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
KooshaPari merged 1 commit into from
Apr 27, 2026
Merged

docs: salvage local governance and worklog notes #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# AGENTS.md — phenotype-tooling

This repository is part of the Phenotype ecosystem.

## Quick Links

- **Project governance:** See `CLAUDE.md` in this repository
- **Phenotype org guidance:** `/Users/kooshapari/CodeProjects/Phenotype/repos/CLAUDE.md`
- **Global agent instructions:** `~/.claude/AGENTS.md`
- **Work tracking:** AgilePlus at `/Users/kooshapari/CodeProjects/Phenotype/repos/AgilePlus`

@cursor cursor Bot Apr 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Hardcoded local filesystem paths in committed agent config

Medium Severity

The new AGENTS.md file contains three absolute paths specific to a single developer's machine (/Users/kooshapari/CodeProjects/Phenotype/repos/...). These paths are non-functional for any other contributor or CI environment. Since this file is described as providing "local routing and quality-gate pointers" for AI agents, the paths will silently resolve to nothing on other machines, making the agent guidance misleading.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit fdd2375. Configure here.


## Operating Model

1. Before implementing: check AgilePlus for existing specs.
2. Quality gates: see `CLAUDE.md` for build, test, and lint commands.
3. Worktrees: use `repos/phenotype-tooling-wtrees/<topic>/` for feature work.
4. Integration: commit to `main` only after gates pass.

---

**Parent contract:** See `CLAUDE.md` and `/Users/kooshapari/CodeProjects/Phenotype/repos/AGENTS.md` for complete governance.
20 changes: 17 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,19 @@
[![Phenotype](https://img.shields.io/badge/Phenotype-org-blueviolet)](https://github.com/KooshaPari)


Consolidated Rust workspace for Phenotype-org developer tooling. Replaces
dozens of duplicated shell and Python scripts scattered across repos with
a small set of clap-based CLIs aligned to the
Consolidated Rust workspace for Phenotype-org developer tooling. It replaces
duplicated shell and Python scripts scattered across repos with a focused set
of clap-based CLIs aligned to the
[scripting language hierarchy](https://github.com/KooshaPari/phenotype-infrakit/blob/main/docs/governance/scripting_policy.md)
(Rust default; no new Bash).

## Overview

`phenotype-tooling` centralizes build verification, code-quality checks,
documentation validation, release support, and software-bill-of-materials
generation into a single Rust workspace. Each crate is independently usable and
can be adopted by other Phenotype repos without copying implementation logic.

## Crates

### Pre-FocalPoint Lift
Expand Down Expand Up @@ -92,6 +99,13 @@ cargo fmt --check
cargo build --release --workspace
```

## Governance & Worklogs

- `CLAUDE.md` documents repo-specific conventions and workspace rules.

@codeant-ai codeant-ai Bot Apr 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟠 Architect Review — HIGH

README claims CLAUDE.md documents repo-specific conventions and workspace rules, but CLAUDE.md is still the generic template with placeholders and no project-specific commands, so the governance pointer does not deliver the promised guidance.

Suggestion: Populate CLAUDE.md with concrete phenotype-tooling rules and commands (or clearly mark it as a template and adjust the README wording) so governance links lead to actionable, repo-specific guidance.

Fix in Cursor | Fix in VSCode Claude

(Use Cmd/Ctrl + Click for best experience)

Prompt for AI Agent 🤖 
This is an **Architect / Logical Review** comment left during a code review. These reviews are first-class, important findings — not optional suggestions. Do NOT dismiss this as a 'big architectural change' just because the title says architect review; most of these can be resolved with a small, localized fix once the intent is understood.

**Path:** README.md
**Line:** 104:104
**Comment:**
	*HIGH: README claims `CLAUDE.md` documents repo-specific conventions and workspace rules, but `CLAUDE.md` is still the generic template with placeholders and no project-specific commands, so the governance pointer does not deliver the promised guidance.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
If a suggested approach is provided above, use it as the authoritative instruction. If no explicit code suggestion is given, you MUST still draft and apply your own minimal, localized fix — do not punt back with 'no suggestion provided, review manually'. Keep the change as small as possible: add a guard clause, gate on a loading state, reorder an await, wrap in a conditional, etc. Do not refactor surrounding code or expand scope beyond the finding.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix

- `AGENTS.md` gives AI agents the local routing and quality-gate pointers.
- `worklogs/` captures repo-local research, architecture, and governance notes.
- `CHANGELOG.md` tracks release-visible changes.

## License

MIT. See [LICENSE](LICENSE).
5 changes: 5 additions & 0 deletions worklogs/ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Architecture Decisions & Refactoring

## Index

Add entries as ADRs, library extractions, or refactoring decisions are made.
5 changes: 5 additions & 0 deletions worklogs/GOVERNANCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Governance & Quality

## Index

Add entries for policy decisions, quality-gate evidence, or org alignment findings.
15 changes: 15 additions & 0 deletions worklogs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Worklogs

Project worklogs capture research, decisions, architecture notes, governance evidence, and completion notes.

## Categories

| File | Purpose |
|------|---------|
| `ARCHITECTURE.md` | ADRs, library extraction notes, and refactoring decisions |
| `RESEARCH.md` | Analysis, repo research, and comparative studies |
| `GOVERNANCE.md` | Policy decisions, quality-gate evidence, and org alignment findings |

## Index

Add dated entries to the category files as work completes.
5 changes: 5 additions & 0 deletions worklogs/RESEARCH.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Research & Analysis

## Index

Add entries as research completions, repo analysis, or comparative studies conclude.
Loading