diff added

Author: PredictabilityAtScale

.capabilities/core/assessment/assess-implementation-coverage.capability.yaml

@@ -12,6 +12,16 @@ acceptance:
   - Presents each acceptance criterion beside relevant implementation evidence.
   - Marks criteria as covered, uncovered, or uncertain.
   - Reports missing or unreadable references as uncovered evidence.
+  - Provides an advisory report that groups coverage findings by recommended
+    action.
+  - Provides a developer-facing status summary that separates needs-action,
+    needs-review, ok, and planned capabilities.
+  - Advisory reports prefer saved agent.review criteria over deterministic text
+    evidence.
+  - Lists noisy capabilities that are good candidates for semantic Codex review.
+  - Can update agent.review from current implementation evidence without
+    changing capability status.
+  - Allows accepted advisory findings to be ignored with an explicit reason.
   - Keeps the first version deterministic or review-assisted rather than
     silently trusting an AI judgment.
 guidance:
@@ -28,28 +38,64 @@ agent:
     - referenced source and documentation files
   outputs:
     - implementation coverage report
+    - actionable assessment advice
+    - synchronized review evidence
     - uncovered or uncertain acceptance criteria
   depends_on:
     - core/validation/verify-implementation-references
   implementation:
     references:
       - packages/core/src/assessImplementationCoverage.ts
+      - packages/core/src/assessmentAdvice.ts
+      - packages/core/src/capabilityStatus.ts
+      - packages/core/src/syncReviewEvidence.ts
+      - packages/core/src/schema.ts
+      - packages/core/src/types.ts
       - packages/core/src/index.ts
       - packages/cli/src/index.ts
       - packages/core/tests/assessImplementationCoverage.test.ts
+      - packages/core/tests/assessmentAdvice.test.ts
+      - packages/core/tests/capabilityStatus.test.ts
+      - packages/core/tests/syncReviewEvidence.test.ts
   verification:
     automated:
       - id: coverage-report-tests
         description: Unit tests cover report generation for covered, uncovered, and
           missing-reference cases.
         command: npm test -- packages/core/tests/assessImplementationCoverage.test.ts
+      - id: advisory-report-tests
+        description: Unit tests cover advisory classification and formatted recommended
+          actions.
+        command: npm test -- packages/core/tests/assessmentAdvice.test.ts
+      - id: capability-status-tests
+        description: Unit tests cover developer-facing capability health summaries.
+        command: npm test -- packages/core/tests/capabilityStatus.test.ts
+      - id: sync-review-tests
+        description: Unit tests cover syncing agent.review without changing capability
+          status.
+        command: npm test -- packages/core/tests/syncReviewEvidence.test.ts
       - id: dogfood-coverage-report
         description: The CLI reports implementation coverage for this capability.
-        command: node packages/cli/dist/index.js assess core/assessment/assess-implementation-coverage
+        command: node packages/cli/dist/index.js assess
+          core/assessment/assess-implementation-coverage
+      - id: dogfood-advisory-report
+        description: The CLI reports actionable advice for this capability.
+        command: node packages/cli/dist/index.js advise
+          core/assessment/assess-implementation-coverage
+      - id: dogfood-sync-review-dry-run
+        description: The CLI can preview review evidence synchronization for this
+          capability.
+        command: node packages/cli/dist/index.js sync-review
+          core/assessment/assess-implementation-coverage --dry-run
     manual:
-      - Run the coverage report against core/validation/verify-implementation-references
-        and confirm the output gives a reviewer enough context to judge the
-        implementation.
+      - Run the coverage report against
+        core/validation/verify-implementation-references and confirm the output
+        gives a reviewer enough context to judge the implementation.
     gaps:
       - Deterministic text evidence can identify review targets but cannot prove
         semantic correctness without human or explicit AI review.
+    ignore_gaps:
+      - code: declared-gap
+        message_contains: Deterministic text evidence can identify review targets
+        reason: This is an accepted limitation of the deterministic assessor; semantic
+          review is handled through agent-review and review-result.

.capabilities/core/graph/compile-capabilities.capability.yaml

@@ -27,6 +27,7 @@ agent:
     references:
       - packages/core/src/compileCapabilities.ts
       - packages/cli/src/index.ts
+      - packages/core/tests/compile.test.ts
   verification:
     automated:
       - id: compile-tests

.capabilities/core/graph/diff-capabilities.capability.yaml

@@ -0,0 +1,53 @@
+id: core/graph/diff-capabilities
+title: Diff capabilities
+status: implemented
+area: core
+summary: Compare current capability files with a Git base and summarize added,
+  changed, and removed capabilities.
+intent: Help developers understand product and agent-facing intent changes
+  without reading raw YAML diffs.
+acceptance:
+  - Compares current capabilities against a configurable Git base ref.
+  - Reports added, changed, and removed capabilities by capability ID.
+  - Summarizes meaningful field changes such as status, intent, acceptance,
+    dependencies, implementation references, verification, and ignore policy.
+  - Excludes saved agent.review evidence churn by default while allowing it to
+    be included explicitly.
+  - Includes downstream impact context for changed capabilities.
+  - Defaults to a concise PR-review-style summary and offers verbose
+    field-level output.
+  - Exposes the report through the CLI with human-readable and JSON output.
+guidance:
+  - Compare normalized parsed capabilities, not raw YAML text.
+  - Keep review evidence diffs out of the default view because they can be
+    large and stale.
+  - Include ignore policy changes because they affect assessment behavior.
+  - Avoid raw JSON in the default human output.
+agent:
+  inputs:
+    - current capability files
+    - Git base ref
+  outputs:
+    - capability diff report
+    - added, changed, and removed capability IDs
+    - field-level change summaries
+  depends_on:
+    - core/graph/compile-capabilities
+    - core/graph/analyze-capability-impact
+  implementation:
+    references:
+      - packages/core/src/capabilityDiff.ts
+      - packages/core/src/index.ts
+      - packages/cli/src/index.ts
+      - packages/core/tests/capabilityDiff.test.ts
+  verification:
+    automated:
+      - id: capability-diff-tests
+        description: Unit tests cover Git-backed capability diff reporting.
+        command: npm test -- packages/core/tests/capabilityDiff.test.ts
+      - id: dogfood-capability-diff
+        description: The CLI compares current CapabilityKit capabilities against HEAD.
+        command: node packages/cli/dist/index.js diff --base HEAD
+    manual:
+      - Run capabilitykit diff during a working-tree change and confirm it
+        explains capability intent changes more clearly than git diff.

.capabilities/core/validation/detect-verification-gaps.capability.yaml

@@ -11,6 +11,8 @@ acceptance:
   - Reports implemented or verified capabilities without
     agent.implementation.references values.
   - Reports declared agent.verification.gaps from capability files.
+  - Allows capability files to suppress selected verification gap warnings with
+    an explicit reason.
 guidance:
   - Prefer specific gap messages tied to capability IDs.
   - Keep gap detection rules deterministic and covered by automated tests.
@@ -25,6 +27,9 @@ agent:
   implementation:
     references:
       - packages/core/src/validateCapabilities.ts
+      - packages/core/src/schema.ts
+      - packages/core/src/types.ts
+      - packages/core/tests/validation.test.ts
   verification:
     automated:
       - id: verification-gap-tests

.capabilities/core/validation/validate-capability-files.capability.yaml

@@ -26,9 +26,13 @@ agent:
     - core/model/define-capability-format
   implementation:
     references:
+      - packages/core/src/parseCapability.ts
+      - packages/core/src/schema.ts
       - packages/core/src/validateCapabilities.ts
       - packages/core/src/loadCapabilities.ts
       - packages/cli/src/index.ts
+      - packages/core/tests/parser.test.ts
+      - packages/core/tests/validation.test.ts
   verification:
     automated:
       - id: validation-tests

.capabilities/developer-experience/cli/cli-workflow.capability.yaml

@@ -6,7 +6,8 @@ summary: Provide CLI commands for init, create, validate, compile, and inspect.
 intent: Make capability management fast enough to stay close to normal
   development workflows.
 acceptance:
-  - Supports init, create, validate, compile, and inspect commands.
+  - Supports init, create, status, diff, validate, compile, and inspect
+    commands.
   - Returns a non-zero exit code for validation failures.
   - Prints verification gaps in validation and inspect output.
 guidance:

.capabilities/developer-experience/examples/example-project.capability.yaml

@@ -23,6 +23,10 @@ agent:
     references:
       - examples/basic-app/.capabilities/capabilitykit.yaml
       - examples/basic-app/.capabilities/account/login.capability.yaml
+      - examples/basic-app/.capabilities/account/profile.capability.yaml
+      - examples/basic-app/.capabilities/checkout/cart.capability.yaml
+      - examples/basic-app/.capabilities/checkout/payment.capability.yaml
+      - packages/core/tests/parser.test.ts
   verification:
     automated:
       - id: parser-tests

.capabilities/docs/reference/capability-format-documentation.capability.yaml

@@ -32,3 +32,22 @@ agent:
     manual:
       - Read README from a new user's perspective and confirm the format is
         clear.
+  review:
+    ignore_findings:
+      - status: weak-evidence
+        criterion: README explains what a capability is.
+        reason: README documentation evidence has been manually reviewed for this
+          criterion.
+      - status: weak-evidence
+        criterion: README includes an example capability file.
+        reason: README documentation evidence has been manually reviewed for this
+          criterion.
+      - status: weak-evidence
+        criterion: README explains verification gaps.
+        reason: README documentation evidence has been manually reviewed for this
+          criterion.
+      - status: weak-evidence
+        criterion: README explains how folder hierarchy and capability IDs should
+          align.
+        reason: README documentation evidence has been manually reviewed for this
+          criterion.

.gitignore

@@ -1,5 +1,6 @@
 node_modules/
 dist/
 coverage/
+tmp/
 .capabilities/dist/
 *.tsbuildinfo

README.md

@@ -89,17 +89,64 @@ agent:
 - `capabilitykit init` creates a starter `.capabilities/` folder.
 - `capabilitykit create <name> --area <area>` creates a capability file.
 - `capabilitykit skill` creates or updates CapabilityKit skill files and agent entrypoints.
+- `capabilitykit status [capability-id]` shows a developer-friendly capability health summary.
 - `capabilitykit validate` validates capability files and reports verification gaps.
 - `capabilitykit compile` writes normalized JSON to `.capabilities/dist/capabilities.json`.
 - `capabilitykit inspect <capability-id>` prints one capability and its relationships.
 - `capabilitykit impact <capability-id>` reports direct and transitive downstream capabilities plus suggested verification.
+- `capabilitykit diff [capability-id]` compares capability changes against a Git base ref.
+- `capabilitykit assess <capability-id>` compares acceptance criteria with referenced implementation evidence.
+- `capabilitykit advise [capability-id]` groups assessment findings into recommended next actions.
+- `capabilitykit review-noisy --limit 5` lists high-value capabilities for semantic Codex or human review.
+- `capabilitykit sync-review [capability-id]` updates `agent.review` from current implementation evidence without changing capability status.
+
+`status` is the best first command when you want to understand what the
+capability map says about the project:
+
+```bash
+capabilitykit status
+capabilitykit status core/graph/compile-capabilities
+capabilitykit diff --base HEAD
+capabilitykit diff --base HEAD --verbose
+```
 
 ## Verification Gaps
 
 CapabilityKit treats missing confidence as a first-class signal. Missing automated checks, vague acceptance criteria, broken references, missing `agent.implementation.references`, and manual review gaps are reported as verification gaps.
 
 Gaps are warnings by default. They should be fixed or intentionally documented so humans and agents know what still needs review.
 
+When a warning is intentionally accepted, suppress it in the capability with an explicit reason:
+
+```yaml
+agent:
+  verification:
+    ignore_gaps:
+      - code: missing-automated-checks
+        reason: Manual review is the accepted verification path for this documentation-only capability.
+      - code: declared-gap
+        message_contains: Known external dependency.
+        reason: Tracked outside CapabilityKit for this release.
+```
+
+Use `code: "*"` only when every verification gap for that capability is intentionally handled elsewhere.
+
+Advisory assessment findings can also be ignored when a maintainer accepts the
+deterministic assessor's limitation for a specific criterion. Ignored findings
+are removed from recommended actions and `review-noisy` scoring, but remain
+auditable in the capability file:
+
+```yaml
+agent:
+  review:
+    ignore_findings:
+      - status: weak-evidence
+        criterion: README explains what a capability is.
+        reason: Documentation wording was manually reviewed and accepted.
+```
+
+Use `criterion_contains` for a small family of related findings, and `status: "*"` only for intentionally accepted findings across statuses.
+
 ## Dogfooding
 
 CapabilityKit uses its own `.capabilities/` folder from the first usable version. Each MVP feature has a matching capability spec, and the project verification loop validates and compiles those specs.