Skip to content

Commit ea0e435

Browse files
Copilotdevlux76
Copilot
and
devlux76
committed
Remove broken TODO-to-issue sync system and set up GitHub-native project management
- Remove scripts/sync-github-project.mjs and its workflow - Remove TODO.md and PLAN.md (replaced by GitHub Issues/Projects) - Remove sync:github-project npm script - Add issue templates (bug, feature, task) with structured forms - Add PR template with checklist - Add auto-label workflow using actions/labeler with path-based rules - Add close-legacy-issues workflow to close all 29 existing issues - Add stale issue/PR management workflow - Update copilot-instructions.md, README.md, DESIGN.md, docs/development.md Co-authored-by: devlux76 <86517969+devlux76@users.noreply.github.com>
1 parent 2c6b8c8 commit ea0e435

18 files changed

Lines changed: 448 additions & 1931 deletions

‎.github/ISSUE_TEMPLATE/bug.yml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
name: "🐛 Bug Report"
2+
description: Report a bug in CORTEX
3+
labels: ["bug"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Thanks for reporting a bug. Please fill in the details below.
9+
10+
- type: textarea
11+
id: description
12+
attributes:
13+
label: Description
14+
description: A clear and concise description of the bug.
15+
validations:
16+
required: true
17+
18+
- type: textarea
19+
id: reproduction
20+
attributes:
21+
label: Steps to Reproduce
22+
description: Minimal steps to reproduce the behavior.
23+
placeholder: |
24+
1. Call `ingestText(...)` with ...
25+
2. Then call `query(...)` with ...
26+
3. Observe ...
27+
validations:
28+
required: true
29+
30+
- type: textarea
31+
id: expected
32+
attributes:
33+
label: Expected Behavior
34+
description: What you expected to happen.
35+
validations:
36+
required: true
37+
38+
- type: textarea
39+
id: actual
40+
attributes:
41+
label: Actual Behavior
42+
description: What actually happened. Include error messages or screenshots if applicable.
43+
validations:
44+
required: true
45+
46+
- type: dropdown
47+
id: layer
48+
attributes:
49+
label: Affected Layer
50+
description: Which CORTEX layer does this bug affect?
51+
multiple: true
52+
options:
53+
- Foundation (core/)
54+
- Storage (storage/)
55+
- Vector Compute (root backends)
56+
- Embeddings (embeddings/)
57+
- Hippocampus (hippocampus/)
58+
- Cortex (cortex/)
59+
- Daydreamer
60+
- Runtime Harness (runtime/)
61+
- CI / Build
62+
- Documentation
63+
validations:
64+
required: true
65+
66+
- type: input
67+
id: browser
68+
attributes:
69+
label: Browser / Runtime
70+
description: Browser version, Electron version, or Node/Bun version.
71+
placeholder: "Chrome 120, Electron 28, Bun 1.3.10"

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: "📖 Architecture Reference"
4+
url: https://github.com/devlux76/cortex/blob/main/DESIGN.md
5+
about: Review DESIGN.md before proposing architectural changes.

‎.github/ISSUE_TEMPLATE/feature.yml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: "✨ Feature Request"
2+
description: Propose a new feature or enhancement for CORTEX
3+
labels: ["enhancement"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Describe the feature you'd like to see in CORTEX.
9+
10+
- type: textarea
11+
id: summary
12+
attributes:
13+
label: Summary
14+
description: A concise description of the proposed feature.
15+
validations:
16+
required: true
17+
18+
- type: textarea
19+
id: motivation
20+
attributes:
21+
label: Motivation
22+
description: Why is this feature needed? What problem does it solve?
23+
validations:
24+
required: true
25+
26+
- type: textarea
27+
id: design
28+
attributes:
29+
label: Proposed Design
30+
description: How should this feature work? Reference DESIGN.md sections if applicable.
31+
32+
- type: dropdown
33+
id: layer
34+
attributes:
35+
label: Target Layer
36+
description: Which CORTEX layer would this feature primarily affect?
37+
multiple: true
38+
options:
39+
- Foundation (core/)
40+
- Storage (storage/)
41+
- Vector Compute (root backends)
42+
- Embeddings (embeddings/)
43+
- Hippocampus (hippocampus/)
44+
- Cortex (cortex/)
45+
- Daydreamer
46+
- Runtime Harness (runtime/)
47+
- CI / Build
48+
- Documentation
49+
validations:
50+
required: true
51+
52+
- type: textarea
53+
id: exit-criteria
54+
attributes:
55+
label: Exit Criteria
56+
description: What must be true for this feature to be considered complete?
57+
placeholder: |
58+
- [ ] Unit tests pass
59+
- [ ] Integration test covers end-to-end flow
60+
- [ ] DESIGN.md updated if architecture changed

‎.github/ISSUE_TEMPLATE/task.yml‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
name: "🔧 Implementation Task"
2+
description: Define a specific implementation task
3+
labels: ["task"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Define a concrete implementation task. Reference DESIGN.md for architectural context.
9+
10+
- type: textarea
11+
id: objective
12+
attributes:
13+
label: Objective
14+
description: What needs to be built or changed?
15+
validations:
16+
required: true
17+
18+
- type: dropdown
19+
id: priority
20+
attributes:
21+
label: Priority
22+
options:
23+
- "P0: critical — blocks dependent work"
24+
- "P1: high — targets next milestone"
25+
- "P2: medium — important but not blocking"
26+
- "P3: low — polish or nice-to-have"
27+
validations:
28+
required: true
29+
30+
- type: dropdown
31+
id: layer
32+
attributes:
33+
label: Target Layer
34+
description: Which CORTEX layer does this task target?
35+
multiple: true
36+
options:
37+
- Foundation (core/)
38+
- Storage (storage/)
39+
- Vector Compute (root backends)
40+
- Embeddings (embeddings/)
41+
- Hippocampus (hippocampus/)
42+
- Cortex (cortex/)
43+
- Daydreamer
44+
- Runtime Harness (runtime/)
45+
- CI / Build
46+
- Documentation
47+
validations:
48+
required: true
49+
50+
- type: textarea
51+
id: files
52+
attributes:
53+
label: Files to Create or Modify
54+
description: List the files this task will touch.
55+
placeholder: |
56+
- `cortex/MetroidBuilder.ts` (create)
57+
- `tests/cortex/MetroidBuilder.test.ts` (create)
58+
- `DESIGN.md` (update if architecture changes)
59+
60+
- type: textarea
61+
id: exit-criteria
62+
attributes:
63+
label: Exit Criteria
64+
description: Checklist of conditions that must be met to close this task.
65+
placeholder: |
66+
- [ ] Implementation complete
67+
- [ ] Unit tests passing
68+
- [ ] Lint and typecheck clean
69+
- [ ] guard:model-derived passes (if numerics changed)
70+
validations:
71+
required: true
72+
73+
- type: textarea
74+
id: dependencies
75+
attributes:
76+
label: Dependencies
77+
description: List any issues or tasks that must be completed first. Use `#issue_number` references.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
## Summary
2+
3+
<!-- What does this PR do? Reference the issue it addresses with "Closes #123". -->
4+
5+
## Changes
6+
7+
<!-- List the key changes made in this PR. -->
8+
9+
-
10+
11+
## Checklist
12+
13+
- [ ] Lint passes (`npm run lint`)
14+
- [ ] Typecheck passes (`npm run build`)
15+
- [ ] Unit tests pass (`npm run test:unit`)
16+
- [ ] `guard:model-derived` passes (if numeric constants changed)
17+
- [ ] DESIGN.md updated (if architecture changed)
18+
- [ ] No hardcoded model-derived numbers — all sourced from `core/`
19+
- [ ] No server-side dependencies, cloud calls, or telemetry added

‎.github/copilot-instructions.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,20 @@ The engine models three biological brain regions:
1515
|---|---|
1616
| `README.md` | Product vision and quick start |
1717
| `DESIGN.md` | Complete architecture specification and design principles |
18-
| `PLAN.md` | Module-by-module implementation status and development phases |
19-
| `TODO.md` | Prioritized actionable tasks to ship v1.0 |
2018

21-
Keep all documents synchronized with the real code state after every implementation pass.
19+
Keep `DESIGN.md` synchronized with the real code state after every implementation pass.
20+
21+
## Project Management
22+
23+
All task tracking, prioritization, and status is managed through **GitHub-native features** — not markdown files:
24+
25+
- **GitHub Issues** — Every task, bug, and feature request is a GitHub Issue (use the issue templates in `.github/ISSUE_TEMPLATE/`).
26+
- **GitHub Projects** — Use project boards for Kanban-style lifecycle tracking (To Do → In Progress → Done).
27+
- **Milestones** — Group issues by release phase (`v0.1`, `v0.5`, `v1.0`).
28+
- **Labels** — Auto-applied on PRs by `.github/workflows/auto-label.yml` using path-based rules in `.github/labeler.yml`. Priority labels (`P0`–`P3`) and layer labels (`layer: foundation`, `layer: cortex`, etc.) are used for classification.
29+
- **Issue linking** — Reference dependencies with `#issue_number`. Use `Closes #N` in PR descriptions to auto-close issues on merge.
30+
31+
Agents with `gh` CLI access can create, update, and close issues directly. Do not create markdown files for task tracking.
2232

2333
## Directory Structure
2434

@@ -119,8 +129,10 @@ Run `npm run guard:model-derived` after any numeric change to verify compliance.
119129

120130
- All CI checks must pass: `lint`, `build` (typecheck), `test:unit`.
121131
- `npm run guard:model-derived` must pass for any change that touches numeric constants.
122-
- Keep `README.md`, `CORTEX-DESIGN-PLAN-TODO.md`, and `PROJECT-EXECUTION-PLAN.md` synchronized with any implementation state changes.
123-
- Record blockers with file path, failure symptom, and next action.
132+
- PRs are auto-labeled by layer based on changed files (`.github/labeler.yml`).
133+
- Use the PR template (`.github/PULL_REQUEST_TEMPLATE.md`) — it is pre-populated on every PR.
134+
- Reference the issue being addressed with `Closes #N` in the PR description.
135+
- Keep `DESIGN.md` synchronized with any architectural changes.
124136

125137
## What NOT to Do
126138

‎.github/labeler.yml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Maps file-path globs to labels applied automatically on PRs.
2+
# Used by the auto-label.yml workflow (actions/labeler).
3+
4+
"layer: foundation":
5+
- changed-files:
6+
- any-glob-to-any-file: "core/**"
7+
8+
"layer: storage":
9+
- changed-files:
10+
- any-glob-to-any-file: "storage/**"
11+
12+
"layer: compute":
13+
- changed-files:
14+
- any-glob-to-any-file:
15+
- "VectorBackend.ts"
16+
- "WebGPUVectorBackend.ts"
17+
- "WebGLVectorBackend.ts"
18+
- "WebNNVectorBackend.ts"
19+
- "WasmVectorBackend.ts"
20+
- "CreateVectorBackend.ts"
21+
- "BackendKind.ts"
22+
- "TopK.ts"
23+
- "Vectors.glsl"
24+
- "Vectors.wgsl"
25+
- "Vectors.wat"
26+
27+
"layer: embeddings":
28+
- changed-files:
29+
- any-glob-to-any-file: "embeddings/**"
30+
31+
"layer: hippocampus":
32+
- changed-files:
33+
- any-glob-to-any-file: "hippocampus/**"
34+
35+
"layer: cortex":
36+
- changed-files:
37+
- any-glob-to-any-file: "cortex/**"
38+
39+
"layer: daydreamer":
40+
- changed-files:
41+
- any-glob-to-any-file: "daydreamer/**"
42+
43+
"layer: testing":
44+
- changed-files:
45+
- any-glob-to-any-file: "tests/**"
46+
47+
"layer: ci":
48+
- changed-files:
49+
- any-glob-to-any-file:
50+
- ".github/workflows/**"
51+
- ".github/labeler.yml"
52+
53+
"layer: documentation":
54+
- changed-files:
55+
- any-glob-to-any-file:
56+
- "*.md"
57+
- "docs/**"
58+
- ".github/copilot-instructions.md"
59+
- ".github/ISSUE_TEMPLATE/**"
60+
- ".github/PULL_REQUEST_TEMPLATE.md"

‎.github/workflows/auto-label.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: Auto-Label PRs
2+
3+
on:
4+
pull_request:
5+
types: [opened, synchronize, reopened]
6+
7+
permissions:
8+
contents: read
9+
pull-requests: write
10+
11+
jobs:
12+
label:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- name: Label PR by changed files
16+
uses: actions/labeler@v5
17+
with:
18+
configuration-path: .github/labeler.yml
19+
sync-labels: true

0 commit comments

Comments
 (0)