179 lines
4.6 KiB
Markdown
179 lines
4.6 KiB
Markdown
# 09 — Repository intelligence
|
|
|
|
## Purpose
|
|
|
|
Repository intelligence converts repository evidence into a reusable, human-reviewable profile. It does not attempt to understand every line of code or claim certainty beyond observed evidence.
|
|
|
|
## Profile sections
|
|
|
|
### Identity
|
|
|
|
- display name;
|
|
- source and external reference;
|
|
- default branch;
|
|
- repository type: single app, monorepo, infrastructure, library, mixed;
|
|
- archived/read-only status.
|
|
|
|
### Stack
|
|
|
|
- languages with evidence paths;
|
|
- frameworks;
|
|
- package managers;
|
|
- runtimes;
|
|
- test frameworks;
|
|
- databases and queues;
|
|
- container/deployment technologies;
|
|
- CI/CD system.
|
|
|
|
### Command registry
|
|
|
|
Logical roles:
|
|
|
|
- install;
|
|
- format;
|
|
- format-check;
|
|
- lint;
|
|
- typecheck;
|
|
- unit-test;
|
|
- integration-test;
|
|
- end-to-end-test;
|
|
- build;
|
|
- dev-start;
|
|
- smoke-test;
|
|
- migration-status;
|
|
- migration-apply;
|
|
- security-scan;
|
|
- dependency-audit.
|
|
|
|
Each command stores value, working directory, platform, source, confidence and whether it is safe for direct future execution. MVP uses commands only as prompt text.
|
|
|
|
### Structure
|
|
|
|
- application roots;
|
|
- package roots;
|
|
- service roots;
|
|
- documentation paths;
|
|
- test paths;
|
|
- generated paths;
|
|
- data/runtime paths;
|
|
- protected paths;
|
|
- ignored paths.
|
|
|
|
### Policies
|
|
|
|
- backwards compatibility;
|
|
- new dependency policy;
|
|
- migration policy;
|
|
- commit/push policy;
|
|
- required documentation;
|
|
- required validation roles;
|
|
- branch conventions;
|
|
- environment constraints.
|
|
|
|
### Source evidence
|
|
|
|
Every inferred fact references one or more evidence records:
|
|
|
|
- file path and digest;
|
|
- forge API field;
|
|
- manual user entry;
|
|
- prior profile revision;
|
|
- observation timestamp.
|
|
|
|
## Detection strategy
|
|
|
|
Use deterministic detectors, not an LLM, for MVP profile import.
|
|
|
|
Examples:
|
|
|
|
- `package.json`, lockfiles and workspace files;
|
|
- `.csproj`, `.sln`, `global.json`;
|
|
- `pyproject.toml`, `requirements*.txt`, `poetry.lock`;
|
|
- `go.mod`, `Cargo.toml`, `pom.xml`, Gradle files;
|
|
- Dockerfile and Compose files;
|
|
- common CI workflow directories;
|
|
- test configuration files;
|
|
- root and nested `AGENTS.md` files;
|
|
- README command snippets only as untrusted suggestions requiring confirmation.
|
|
|
|
Detectors return evidence, confidence and possible conflicts. They do not overwrite manual policy silently.
|
|
|
|
## Manual profile workflow
|
|
|
|
1. Name repository.
|
|
2. Select repository type.
|
|
3. Add stack technologies.
|
|
4. Add command roles.
|
|
5. Define paths and scope rules.
|
|
6. Define policies.
|
|
7. Review validation and save revision.
|
|
|
|
The user can create a useful profile without exposing a repository.
|
|
|
|
## Source versus override model
|
|
|
|
A normalized field can contain:
|
|
|
|
```json
|
|
{
|
|
"value": "pnpm test",
|
|
"source": "manual_override",
|
|
"observedValue": "npm test",
|
|
"evidence": ["package.json#scripts.test"],
|
|
"confirmedAt": "..."
|
|
}
|
|
```
|
|
|
|
This avoids losing observed evidence while respecting operator knowledge.
|
|
|
|
## Findings model
|
|
|
|
Repository findings are rule-based, evidence-linked observations such as:
|
|
|
|
- no repository-level `AGENTS.md` found;
|
|
- test command not identified;
|
|
- no protected default branch evidence;
|
|
- no release history;
|
|
- README setup command conflicts with package manager lockfile;
|
|
- Dockerfile appears to run as root;
|
|
- generated or runtime directory appears tracked;
|
|
- no issue or pull-request template found;
|
|
- multiple package managers detected;
|
|
- CI workflow does not run the profile's required build command.
|
|
|
|
Each finding includes confidence and limitations. “No evidence found” is not the same as “feature definitely absent” when permissions or API capabilities are incomplete.
|
|
|
|
## Recommendation rules
|
|
|
|
A finding maps to a playbook slug and optional prefilled inputs. Example:
|
|
|
|
```text
|
|
Finding: No AGENTS.md found
|
|
Recommendation: codex-agents-instructions
|
|
Prefill: repository commands, protected paths and contribution policy
|
|
```
|
|
|
|
Recommendations must explain why they appear and can be dismissed.
|
|
|
|
## Snapshot refresh
|
|
|
|
A refresh creates new evidence and findings. It does not automatically replace a manually edited profile revision. The UI presents a reviewable diff:
|
|
|
|
- new observation;
|
|
- removed observation;
|
|
- changed value;
|
|
- conflict with manual override;
|
|
- unchanged evidence.
|
|
|
|
User can accept all safe changes, accept individually or retain the existing profile.
|
|
|
|
## Privacy controls
|
|
|
|
- allowlist inspected file names and paths;
|
|
- configurable maximum file size;
|
|
- never import `.env`, secret stores, private keys or common credential files;
|
|
- redact token-like strings in text snippets;
|
|
- show exactly which files were read;
|
|
- allow repository snapshots to omit raw snippets and retain only normalized facts;
|
|
- support deleting snapshots independently from manual profiles.
|